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>

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