diff options
author | Daiki Ueno <ueno@gnu.org> | 2021-05-06 12:41:40 +0200 |
---|---|---|
committer | Daiki Ueno <ueno@gnu.org> | 2021-11-29 13:21:53 +0100 |
commit | 0ecce7191dfd78387f2994253d37ed1df50d563d (patch) | |
tree | fb1d66e9329cdad3ef617c02b96c77aca1c8dd3e /doc | |
parent | ee3af8d6e863bd958cbe7468f9cbe09d803f4e92 (diff) | |
download | gnutls-0ecce7191dfd78387f2994253d37ed1df50d563d.tar.gz |
priority: support allowlisting in configuration file
This adds a new mode of interpreting the [overrides] section. If
"override-mode" is set to "allowlisting" in the [global] section, all
the algorithms (hashes, signature algorithms, curves, and versions)
are initially marked as insecure/disabled. Then the user can enable
them by specifying allowlisting keywords such as "secure-hash" in the
[overrides] section.
Signed-off-by: Daiki Ueno <ueno@gnu.org>
Co-authored-by: Alexander Sosedkin <asosedkin@redhat.com>
Diffstat (limited to 'doc')
-rw-r--r-- | doc/Makefile.am | 10 | ||||
-rw-r--r-- | doc/cha-config.texi | 82 | ||||
-rw-r--r-- | doc/manpages/Makefile.am | 5 |
3 files changed, 95 insertions, 2 deletions
diff --git a/doc/Makefile.am b/doc/Makefile.am index 562a85fa87..4f25bf0d5e 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -974,6 +974,8 @@ FUNCS += functions/gnutls_digest_get_oid FUNCS += functions/gnutls_digest_get_oid.short FUNCS += functions/gnutls_digest_list FUNCS += functions/gnutls_digest_list.short +FUNCS += functions/gnutls_digest_set_secure +FUNCS += functions/gnutls_digest_set_secure.short FUNCS += functions/gnutls_dtls_cookie_send FUNCS += functions/gnutls_dtls_cookie_send.short FUNCS += functions/gnutls_dtls_cookie_verify @@ -1010,6 +1012,8 @@ FUNCS += functions/gnutls_ecc_curve_get_size FUNCS += functions/gnutls_ecc_curve_get_size.short FUNCS += functions/gnutls_ecc_curve_list FUNCS += functions/gnutls_ecc_curve_list.short +FUNCS += functions/gnutls_ecc_curve_set_enabled +FUNCS += functions/gnutls_ecc_curve_set_enabled.short FUNCS += functions/gnutls_encode_ber_digest_info FUNCS += functions/gnutls_encode_ber_digest_info.short FUNCS += functions/gnutls_encode_gost_rs_value @@ -1730,6 +1734,8 @@ FUNCS += functions/gnutls_protocol_get_version FUNCS += functions/gnutls_protocol_get_version.short FUNCS += functions/gnutls_protocol_list FUNCS += functions/gnutls_protocol_list.short +FUNCS += functions/gnutls_protocol_set_enabled +FUNCS += functions/gnutls_protocol_set_enabled.short FUNCS += functions/gnutls_psk_allocate_client_credentials FUNCS += functions/gnutls_psk_allocate_client_credentials.short FUNCS += functions/gnutls_psk_allocate_server_credentials @@ -2024,6 +2030,10 @@ FUNCS += functions/gnutls_sign_is_secure2 FUNCS += functions/gnutls_sign_is_secure2.short FUNCS += functions/gnutls_sign_list FUNCS += functions/gnutls_sign_list.short +FUNCS += functions/gnutls_sign_set_secure +FUNCS += functions/gnutls_sign_set_secure.short +FUNCS += functions/gnutls_sign_set_secure_for_certs +FUNCS += functions/gnutls_sign_set_secure_for_certs.short FUNCS += functions/gnutls_sign_supports_pk_algorithm FUNCS += functions/gnutls_sign_supports_pk_algorithm.short FUNCS += functions/gnutls_srp_allocate_client_credentials diff --git a/doc/cha-config.texi b/doc/cha-config.texi index c0f7048fc2..62def65796 100644 --- a/doc/cha-config.texi +++ b/doc/cha-config.texi @@ -74,6 +74,7 @@ configuration file and can be @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-curve}: to disable the specified elliptic curve. @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. @@ -82,10 +83,54 @@ configuration file and can be @end itemize Each of the options can be repeated multiple times when multiple values need -to be disabled. +to be disabled or enabled. 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}. +'PK-signatures', 'Protocols', 'Ciphers', and 'MACs' fields of the output of @code{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 @code{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 @code{[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. + +@itemize +@item @code{secure-sig-for-cert}: to mark the signature algorithm as secure when used in certificates. +@item @code{secure-sig}: to mark the signature algorithm as secure for any use. +@item @code{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). +@item @code{enabled-curve}: to enable the specified elliptic curve. +@item @code{enabled-version}: to enable the specified TLS versions. +@item @code{tls-enabled-cipher}: to enable the specified ciphers for use in the TLS or DTLS protocols. +@item @code{tls-enabled-mac}: to enable the specified MAC algorithms for use in the TLS or DTLS protocols. +@item @code{tls-enabled-group}: to enable the specified group for use in the TLS or DTLS protocols. +@item @code{tls-enabled-kx}: to enable the specified key exchange algorithms for use in the TLS or DTLS protocols (applies to TLS1.2 or earlier). +@end itemize + +The allowlisting mode can be enabled by adding @code{override-mode = +allowlist} in the @code{[global]} section. + +The following functions allow the applications to modify the setting. + +@showfuncE{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 @code{@@SYSTEM} priority +string is automatically constructed from the options in the +@code{[overrides]} section. For this reason, the above functions +should be called before the @code{@@SYSTEM} priority is used. @subsection Examples @@ -120,6 +165,39 @@ tls-disabled-mac = sha1 tls-disabled-group = group-ffdhe8192 @end example +The following example demonstrates the use of the allowlisting +mode. All the signature algorithms are disabled by default but +@code{RSA-SHA256}. Note that the hash algorithm @code{SHA256} also +needs to be explicitly enabled. + +@example +[global] +override-mode = allowlist + +[overrides] +secure-hash = sha256 +secure-sig = rsa-sha256 +@end example + +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. + +@example +[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 +@end example + @node Querying for disabled algorithms and protocols @section Querying for disabled algorithms and protocols diff --git a/doc/manpages/Makefile.am b/doc/manpages/Makefile.am index cee5a9644a..4f39adf0cc 100644 --- a/doc/manpages/Makefile.am +++ b/doc/manpages/Makefile.am @@ -289,6 +289,7 @@ APIMANS += gnutls_digest_get_id.3 APIMANS += gnutls_digest_get_name.3 APIMANS += gnutls_digest_get_oid.3 APIMANS += gnutls_digest_list.3 +APIMANS += gnutls_digest_set_secure.3 APIMANS += gnutls_dtls_cookie_send.3 APIMANS += gnutls_dtls_cookie_verify.3 APIMANS += gnutls_dtls_get_data_mtu.3 @@ -307,6 +308,7 @@ APIMANS += gnutls_ecc_curve_get_oid.3 APIMANS += gnutls_ecc_curve_get_pk.3 APIMANS += gnutls_ecc_curve_get_size.3 APIMANS += gnutls_ecc_curve_list.3 +APIMANS += gnutls_ecc_curve_set_enabled.3 APIMANS += gnutls_encode_ber_digest_info.3 APIMANS += gnutls_encode_gost_rs_value.3 APIMANS += gnutls_encode_rs_value.3 @@ -667,6 +669,7 @@ APIMANS += gnutls_protocol_get_id.3 APIMANS += gnutls_protocol_get_name.3 APIMANS += gnutls_protocol_get_version.3 APIMANS += gnutls_protocol_list.3 +APIMANS += gnutls_protocol_set_enabled.3 APIMANS += gnutls_psk_allocate_client_credentials.3 APIMANS += gnutls_psk_allocate_server_credentials.3 APIMANS += gnutls_psk_client_get_hint.3 @@ -814,6 +817,8 @@ APIMANS += gnutls_sign_get_pk_algorithm.3 APIMANS += gnutls_sign_is_secure.3 APIMANS += gnutls_sign_is_secure2.3 APIMANS += gnutls_sign_list.3 +APIMANS += gnutls_sign_set_secure.3 +APIMANS += gnutls_sign_set_secure_for_certs.3 APIMANS += gnutls_sign_supports_pk_algorithm.3 APIMANS += gnutls_srp_allocate_client_credentials.3 APIMANS += gnutls_srp_allocate_server_credentials.3 |