config: added ability to override and mark algorithms as disabled

This allows the system administrator or the distributor to use
the gnutls configuration file to mark hashes, signature algorithms,
TLS versions, curves, groups, ciphers KX, and MAC algorithms as
insecure (the last four only in the context of a TLS session).
It also allows to set a minimum profile which the applications
cannot fall below.

The options intentionally do not allow marking algorithms as
secure so that the configuration file cannot be used as an attack
vector. This change also makes sure that unsupported and disabled protocols
during compile time (e.g., SSL3.0), do not get listed by gnutls-cli.

The configuration file feature can be disabled at compile time
with an empty --with-system-priority-file.

This patch it introduces the function gnutls_get_system_config_file()
allowing applications to check whether a configuration file
was used.

Resolves: #587

Signed-off-by: Nikos Mavrogiannopoulos <nmav@redhat.com>

4 files changed, 163 insertions, 2 deletions

diff --git a/doc/Makefile.am b/doc/Makefile.am
index 773ab6dc7f..9452126ad4 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -151,7 +151,7 @@ gnutls_TEXINFOS = gnutls.texi fdl-1.3.texi				\
 	cha-library.texi cha-preface.texi cha-programs.texi		\
 	sec-tls-app.texi cha-errors.texi cha-support.texi		\
 	cha-shared-key.texi cha-gtls-examples.texi cha-upgrade.texi	\
-	cha-tokens.texi cha-crypto.texi cha-auth.texi
+	cha-tokens.texi cha-crypto.texi cha-auth.texi cha-config.texi
 
 AUTOGENED_DOC = invoke-gnutls-cli.texi invoke-gnutls-cli-debug.texi \
 	invoke-gnutls-serv.texi invoke-certtool.texi invoke-srptool.texi \
diff --git a/doc/cha-config.texi b/doc/cha-config.texi
new file mode 100644
index 0000000000..3cc568a607
--- /dev/null
+++ b/doc/cha-config.texi
@@ -0,0 +1,158 @@
+@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 overriden 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::
+@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
diff --git a/doc/cha-gtls-app.texi b/doc/cha-gtls-app.texi
index e08cbb24f1..66875af222 100644
--- a/doc/cha-gtls-app.texi
+++ b/doc/cha-gtls-app.texi
@@ -1293,7 +1293,7 @@ advances while providing compatibility with old clients and servers).
 @multitable @columnfractions .20 .70
 @headitem Keyword @tab Description
 @item @@KEYWORD @tab
-Means that a compile-time specified system configuration file@footnote{The default is @code{/etc/gnutls/default-priorities}.} 
+Means that a compile-time specified system configuration file (see @ref{System-wide configuration of the library})
 will be used to expand the provided keyword. That is used to impose system-specific policies.
 It may be followed by additional options that will be appended to the
 system string (e.g., "@@SYSTEM:+SRP"). The system file should have the
diff --git a/doc/gnutls.texi b/doc/gnutls.texi
index 7b963d6f67..5c4daa79ae 100644
--- a/doc/gnutls.texi
+++ b/doc/gnutls.texi
@@ -153,6 +153,7 @@ Documentation License''.
 * Hardware security modules and abstract key types::
 * How to use GnuTLS in applications::
 * GnuTLS application examples::
+* System-wide configuration of the library::
 * Using GnuTLS as a cryptographic library::
 * Other included programs::
 * Internal architecture of GnuTLS::
@@ -182,6 +183,8 @@ Documentation License''.
 
 @include cha-gtls-examples.texi
 
+@include cha-config.texi
+
 @include cha-crypto.texi
 
 @include cha-programs.texi