Next: Querying for disabled algorithms and protocols, Previous: Application-specific priority strings, Up: System-wide configuration of the library [Contents][Index]
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.
int gnutls_ecc_curve_set_enabled (gnutls_ecc_curve_t curve, unsigned int enabled)int gnutls_sign_set_secure (gnutls_sign_algorithm_t sign, unsigned int secure)int gnutls_sign_set_secure_for_certs (gnutls_sign_algorithm_t sign, unsigned int secure)int gnutls_digest_set_secure (gnutls_digest_algorithm_t dig, unsigned int secure)int gnutls_protocol_set_enabled (gnutls_protocol_t version, unsigned int 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.
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