@node System-wide configuration of the library
@chapter System-wide configuration of the library
@cindex System-wide configuration

@acronym{GnuTLS} 3.6.9 introduced a system-wide configuration of the library
which can be used to disable or mark algorithms and protocols as insecure
system-wide, overriding the library defaults. The format of this
configuration file is of an INI file, with the hash ('#') allowed for
commenting. It intentionally does not allow switching algorithms or protocols
which were disabled or marked as insecure during compile time to the secure
set. This is to prevent the feature from being used to attack the system.
Unknown options or sections in the configuration file are skipped unless
the environment variable @code{GNUTLS_SYSTEM_PRIORITY_FAIL_ON_INVALID} is
set to 1, where it would cause the library to exit on unknown options.

The location of the default configuration file is @code{/etc/gnutls/config},
but its actual location may be overridden during compile time or at run-time
using the @code{GNUTLS_SYSTEM_PRIORITY_FILE} environment variable. The file
used can be queried using @funcref{gnutls_get_system_config_file}.

@showfuncdesc{gnutls_get_system_config_file}

@menu
* Application-specific priority strings::
* Disabling algorithms and protocols::
* Querying for disabled algorithms and protocols::
* Overriding the parameter verification profile::
* Overriding the default priority string::
@end menu

@node Application-specific priority strings
@section Application-specific priority strings

It is possible to specify custom cipher priority strings, in addition to the
default priority strings (@code{NORMAL}, @code{PERFORMANCE}, etc.). These can
be used either by individual applications, or even as the default option if
the library is compiled with the configuration option
@code{--with-default-priority-string}. In the latter case the defined
priority string will be used for applications using @funcref{gnutls_set_default_priority}
or @funcref{gnutls_set_default_priority_append}.

The priority strings can be specified in the global section of the
configuration file, or in the section named @code{[priorities]}.
The format is '@code{KEYWORD = VALUE}', e.g.,

When used they may be followed by additional options that will be appended to the
system string (e.g., '@code{@@EXAMPLE-PRIORITY:+SRP}'). '@code{EXAMPLE-PRIORITY=NORMAL:+ARCFOUR-128}'.
Since version 3.5.1 applications are allowed to specify fallback keywords such as
@@KEYWORD1,@@KEYWORD2, and the first valid keyword will be used.

The following example configuration defines a priority string called @code{@@SYSTEM}.
When set, its full settings can be queried using @code{gnutls-cli --priority @@SYSTEM --list}.

@example
[priorities]
SYSTEM = NORMAL:-AES-128-CBC:-AES-256-CBC
@end example


@node Disabling algorithms and protocols
@section Disabling algorithms and protocols

The approach above works well to create consistent system-wide settings
for cooperative GnuTLS applications. When an application however does not
use the @funcref{gnutls_set_default_priority} or @funcref{gnutls_set_default_priority_append}
functions, the method is not sufficient to prevent applications from using
protocols or algorithms forbidden by a local policy.
The override method described below enables the deprecation of algorithms and
protocols system-wide for all applications.

The available options must be set in the @code{[overrides]} section of the
configuration file and can be
@itemize
@item @code{insecure-sig-for-cert}: to mark the signature algorithm as insecure when used in certificates.
@item @code{insecure-sig}: to mark the signature algorithm as insecure for any use.
@item @code{insecure-hash}: to mark the hash algorithm as insecure for digital signature use (provides a more generic way to disable digital signatures for broken hash algorithms).
@item @code{disabled-version}: to disable the specified TLS versions.
@item @code{tls-disabled-cipher}: to disable the specified ciphers for use in the TLS or DTLS protocols.
@item @code{tls-disabled-mac}: to disable the specified MAC algorithms for use in the TLS or DTLS protocols.
@item @code{tls-disabled-group}: to disable the specified group for use in the TLS or DTLS protocols.
@item @code{tls-disabled-kx}: to disable the specified key exchange algorithms for use in the TLS or DTLS protocols (applies to TLS1.2 or earlier).
@end itemize

Each of the options can be repeated multiple times when multiple values need
to be disabled.

The valid values for the options above can be found in the 'Protocols', 'Digests'
'PK-signatures', 'Protocols', 'Ciphrers', and 'MACs' fields of the output of @code{gnutls-cli --list}.

@subsection Examples

The following example marks as insecure all digital signature algorithms
which depend on SHA384, as well as the RSA-SHA1 signature algorithm.

@example
[overrides]
insecure-hash = sha384
insecure-sig = rsa-sha1
@end example

The following example marks RSA-SHA256 as insecure for use in certificates
and disables the TLS1.0 and TLS1.1 protocols.

@example
[overrides]
insecure-sig-for-cert = rsa-sha256
disabled-version = tls1.0
disabled-version = tls1.1
@end example

The following example disables the @code{AES-128-CBC} and @code{AES-256-CBC}
ciphers, the @code{HMAC-SHA1} MAC algorithm and the @code{GROUP-FFDHE8192}
group for TLS and DTLS protocols.

@example
[overrides]
tls-disabled-cipher = aes-128-cbc
tls-disabled-cipher = aes-256-cbc
tls-disabled-mac = sha1
tls-disabled-group = group-ffdhe8192
@end example

@node Querying for disabled algorithms and protocols
@section Querying for disabled algorithms and protocols

When necessary applications can query whether a particular algorithm
or protocol has been marked as insecure or disabled system-wide.
Digital signatures can be queried using the following algorithms.
@showfuncB{gnutls_sign_is_secure,gnutls_sign_is_secure2}

Any disabled protocol versions or elliptic curves will not show up in the
lists provided by the following functions.

@showfuncC{gnutls_protocol_list,gnutls_group_list,gnutls_ecc_curve_list}

It is not possible to query for insecure hash algorithms directly
(only indirectly through the signature API).


@node Overriding the parameter verification profile
@section Overriding the parameter verification profile

When verifying a certificate or TLS session parameters, GnuTLS uses a set
of profiles associated with the session to determine whether the parameters
seen in the session are acceptable. For example, whether the RSA public key
size as seen on the wire, or the Diffie-Hellman parameters for the session.
These profiles are normally set using the @code{%PROFILE} priority string
(see @ref{Priority Strings} and @ref{Selecting cryptographic key sizes}).

It is possible to set the low bar profile that applications cannot override
using the following.

@example
[overrides]

# do not allow applications use the LOW or VERY-WEAK profiles.
min-verification-profile = legacy

@end example

@node Overriding the default priority string
@section Overriding the default priority string

GnuTLS uses default priority string which is defined at compiled
time. Usually it is set to @code{NORMAL}. This override allows to set
the default priority string to something more appropriate for a given
deployment.

Below example sets a more specific default priority string.
@example
[overrides]
default-priority-string = SECURE128:-VERS-TLS-ALL:+VERS-TLS1.3

@end example