System-wide configuration of the library
****************************************

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 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 /etc/gnutls/config, but its actual location may be overridden during compile time or at run-time using the GNUTLS_SYSTEM_PRIORITY_FILE environment variable. The file used can be queried using gnutls_get_system_config_file.

gnutls_get_system_config_file

Application-specific priority strings
=====================================

It is possible to specify custom cipher priority strings, in addition to the default priority strings (NORMAL, 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 --with-default-priority-string. In the latter case the defined priority string will be used for applications using gnutls_set_default_priority or gnutls_set_default_priority_append.

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

When used they may be followed by additional options that will be appended to the system string (e.g., '@EXAMPLE-PRIORITY:+SRP'). '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 @SYSTEM. When set, its full settings can be queried using gnutls-cli --priority @SYSTEM --list.

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

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 gnutls_set_default_priority or 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 [overrides] section of the configuration file and can be

  * insecure-sig-for-cert: to mark the signature algorithm as insecure when used in certificates.

  * insecure-sig: to mark the signature algorithm as insecure for any use.

  * 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).

  * disabled-curve: to disable the specified elliptic curve.

  * disabled-version: to disable the specified TLS versions.

  * tls-disabled-cipher: to disable the specified ciphers for use in the TLS or DTLS protocols.

  * tls-disabled-mac: to disable the specified MAC algorithms for use in the TLS or DTLS protocols.

  * tls-disabled-group: to disable the specified group for use in the TLS or DTLS protocols.

  * tls-disabled-kx: to disable the specified key exchange algorithms for use in the TLS or DTLS protocols (applies to TLS1.2 or earlier).

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

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

Sometimes the system administrator wants to enable only specific algorithms, despite the library defaults. GnuTLS provides an alternative mode of overriding: allowlisting.

As shown below in the examples, it is hard to use this mode correctly, as it requires understanding of how algorithms are used underneath by the protocols.  Allowlisting configuration mode is intended to be used by the operating system vendors that prefer laying out the library defaults exhaustively from scratch instead on depending on gnutls presets, such as NORMAL.  Applications are then expected to optionally disable or enable only a subset algorithms on top of the vendor-provided configuration.

In the allowlisting mode, all the algorithms are initially marked as insecure or disabled, and shall be explicitly turned on by the options listed below in the [overrides] section.  As the allowlisting mode is mutually exclusive to the blocklisting mode, the options listed above for the blocklisting mode are forbidden in the allowlisting mode, and vice versa.

  * secure-sig-for-cert: to mark the signature algorithm as secure when used in certificates.

  * secure-sig: to mark the signature algorithm as secure for any use.

  * secure-hash: to mark the hash algorithm as secure for digital signature use (provides a more generic way to enable digital signatures for broken hash algorithms).

  * enabled-curve: to enable the specified elliptic curve.

  * enabled-version: to enable the specified TLS versions.

  * tls-enabled-cipher: to enable the specified ciphers for use in the TLS or DTLS protocols.

  * tls-enabled-mac: to enable the specified MAC algorithms for use in the TLS or DTLS protocols.

  * tls-enabled-group: to enable the specified group for use in the TLS or DTLS protocols.

  * tls-enabled-kx: to enable the specified key exchange algorithms for use in the TLS or DTLS protocols (applies to TLS1.2 or earlier).

The allowlisting mode can be enabled by adding override-mode = allowlist in the [global] section.

The following functions allow the applications to modify the setting.

gnutls_ecc_curve_set_enabled,gnutls_sign_set_secure,gnutls_sign_set_secure_for_certs,gnutls_digest_set_secure,gnutls_protocol_set_enabled

When the allowlisting mode is in effect, a @SYSTEM priority string is automatically constructed from the options in the [overrides] section.  For this reason, the above functions should be called before the @SYSTEM priority is used.

Examples
--------

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

     [overrides]
     insecure-hash = sha384
     insecure-sig = rsa-sha1

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

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

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

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

The following example demonstrates the use of the allowlisting mode. All the signature algorithms are disabled by default but RSA-SHA256. Note that the hash algorithm SHA256 also needs to be explicitly enabled.

     [global]
     override-mode = allowlist

     [overrides]
     secure-hash = sha256
     secure-sig = rsa-sha256

To enable a TLS ciphersuite in the allowlist mode requires a more verbose configuration, explicitly listing algorithm dependencies.  The following example enables TLS_AES_128_GCM_SHA256, using the SECP256R1 curve for signing and key exchange.

     [global]
     override-mode = allowlist

     [overrides]
     secure-hash = sha256
     enabled-curve = secp256r1
     secure-sig = ecdsa-secp256r1-sha256
     enabled-version = tls1.3
     tls-enabled-cipher = aes-128-gcm
     tls-enabled-mac = aead
     tls-enabled-group = secp256r1

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. 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.

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).

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 %PROFILE priority string (see Priority Strings and Selecting cryptographic key sizes).

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

     [overrides]

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

Overriding the default priority string
======================================

GnuTLS uses default priority string which is defined at compiled time. Usually it is set to 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.

     [overrides]
     default-priority-string = SECURE128:-VERS-TLS-ALL:+VERS-TLS1.3

Enabling/Disabling system/acceleration protocols
================================================

The following options can overwrite default behavior of protocols system-wide.

     [global]
     ktls = true

Enabling KTLS
-------------

When GnuTLS is build with -–enable-ktls configuration, KTLS is disabled by default. This can be enabled by setting ktls = true in [global] section.

Enabling/Disabling RSAES-PKCS1-v1_5
===================================

This option can be used to enable/disable RSA PKCS1 v1.5 encryption and decryption in GnuTLS. The RSAES-PKCS1-v1_5 is enabled by default.

Below example shows how to explicitely disable the RSAES-PKCS1-v1_5.

     [overrides]
     allow-rsa-pkcs1-encrypt = false