|
Packit Service |
991b93 |
@node System-wide configuration of the library
|
|
Packit Service |
991b93 |
@chapter System-wide configuration of the library
|
|
Packit Service |
991b93 |
@cindex System-wide configuration
|
|
Packit Service |
991b93 |
|
|
Packit Service |
991b93 |
@acronym{GnuTLS} 3.6.9 introduced a system-wide configuration of the library
|
|
Packit Service |
991b93 |
which can be used to disable or mark algorithms and protocols as insecure
|
|
Packit Service |
991b93 |
system-wide, overriding the library defaults. The format of this
|
|
Packit Service |
991b93 |
configuration file is of an INI file, with the hash ('#') allowed for
|
|
Packit Service |
991b93 |
commenting. It intentionally does not allow switching algorithms or protocols
|
|
Packit Service |
991b93 |
which were disabled or marked as insecure during compile time to the secure
|
|
Packit Service |
991b93 |
set. This is to prevent the feature from being used to attack the system.
|
|
Packit Service |
991b93 |
Unknown options or sections in the configuration file are skipped unless
|
|
Packit Service |
991b93 |
the environment variable @code{GNUTLS_SYSTEM_PRIORITY_FAIL_ON_INVALID} is
|
|
Packit Service |
991b93 |
set to 1, where it would cause the library to exit on unknown options.
|
|
Packit Service |
991b93 |
|
|
Packit Service |
991b93 |
The location of the default configuration file is @code{/etc/gnutls/config},
|
|
Packit Service |
991b93 |
but its actual location may be overriden during compile time or at run-time
|
|
Packit Service |
991b93 |
using the @code{GNUTLS_SYSTEM_PRIORITY_FILE} environment variable. The file
|
|
Packit Service |
991b93 |
used can be queried using @funcref{gnutls_get_system_config_file}.
|
|
Packit Service |
991b93 |
|
|
Packit Service |
991b93 |
@showfuncdesc{gnutls_get_system_config_file}
|
|
Packit Service |
991b93 |
|
|
Packit Service |
991b93 |
@menu
|
|
Packit Service |
991b93 |
* Application-specific priority strings::
|
|
Packit Service |
991b93 |
* Disabling algorithms and protocols::
|
|
Packit Service |
991b93 |
* Querying for disabled algorithms and protocols::
|
|
Packit Service |
991b93 |
* Overriding the parameter verification profile::
|
|
Packit Service |
991b93 |
* Overriding the default priority string::
|
|
Packit Service |
991b93 |
@end menu
|
|
Packit Service |
991b93 |
|
|
Packit Service |
991b93 |
@node Application-specific priority strings
|
|
Packit Service |
991b93 |
@section Application-specific priority strings
|
|
Packit Service |
991b93 |
|
|
Packit Service |
991b93 |
It is possible to specify custom cipher priority strings, in addition to the
|
|
Packit Service |
991b93 |
default priority strings (@code{NORMAL}, @code{PERFORMANCE}, etc.). These can
|
|
Packit Service |
991b93 |
be used either by individual applications, or even as the default option if
|
|
Packit Service |
991b93 |
the library is compiled with the configuration option
|
|
Packit Service |
991b93 |
@code{--with-default-priority-string}. In the latter case the defined
|
|
Packit Service |
991b93 |
priority string will be used for applications using @funcref{gnutls_set_default_priority}
|
|
Packit Service |
991b93 |
or @funcref{gnutls_set_default_priority_append}.
|
|
Packit Service |
991b93 |
|
|
Packit Service |
991b93 |
The priority strings can be specified in the global section of the
|
|
Packit Service |
991b93 |
configuration file, or in the section named @code{[priorities]}.
|
|
Packit Service |
991b93 |
The format is '@code{KEYWORD = VALUE}', e.g.,
|
|
Packit Service |
991b93 |
|
|
Packit Service |
991b93 |
When used they may be followed by additional options that will be appended to the
|
|
Packit Service |
991b93 |
system string (e.g., '@code{@@EXAMPLE-PRIORITY:+SRP}'). '@code{EXAMPLE-PRIORITY=NORMAL:+ARCFOUR-128}'.
|
|
Packit Service |
991b93 |
Since version 3.5.1 applications are allowed to specify fallback keywords such as
|
|
Packit Service |
991b93 |
@@KEYWORD1,@@KEYWORD2, and the first valid keyword will be used.
|
|
Packit Service |
991b93 |
|
|
Packit Service |
991b93 |
The following example configuration defines a priority string called @code{@@SYSTEM}.
|
|
Packit Service |
991b93 |
When set, its full settings can be queried using @code{gnutls-cli --priority @@SYSTEM --list}.
|
|
Packit Service |
991b93 |
|
|
Packit Service |
991b93 |
@example
|
|
Packit Service |
991b93 |
[priorities]
|
|
Packit Service |
991b93 |
SYSTEM = NORMAL:-AES-128-CBC:-AES-256-CBC
|
|
Packit Service |
991b93 |
@end example
|
|
Packit Service |
991b93 |
|
|
Packit Service |
991b93 |
|
|
Packit Service |
991b93 |
@node Disabling algorithms and protocols
|
|
Packit Service |
991b93 |
@section Disabling algorithms and protocols
|
|
Packit Service |
991b93 |
|
|
Packit Service |
991b93 |
The approach above works well to create consistent system-wide settings
|
|
Packit Service |
991b93 |
for cooperative GnuTLS applications. When an application however does not
|
|
Packit Service |
991b93 |
use the @funcref{gnutls_set_default_priority} or @funcref{gnutls_set_default_priority_append}
|
|
Packit Service |
991b93 |
functions, the method is not sufficient to prevent applications from using
|
|
Packit Service |
991b93 |
protocols or algorithms forbidden by a local policy.
|
|
Packit Service |
991b93 |
The override method described below enables the deprecation of algorithms and
|
|
Packit Service |
991b93 |
protocols system-wide for all applications.
|
|
Packit Service |
991b93 |
|
|
Packit Service |
991b93 |
The available options must be set in the @code{[overrides]} section of the
|
|
Packit Service |
991b93 |
configuration file and can be
|
|
Packit Service |
991b93 |
@itemize
|
|
Packit Service |
991b93 |
@item @code{insecure-sig-for-cert}: to mark the signature algorithm as insecure when used in certificates.
|
|
Packit Service |
991b93 |
@item @code{insecure-sig}: to mark the signature algorithm as insecure for any use.
|
|
Packit Service |
991b93 |
@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).
|
|
Packit Service |
991b93 |
@item @code{disabled-version}: to disable the specified TLS versions.
|
|
Packit Service |
991b93 |
@item @code{tls-disabled-cipher}: to disable the specified ciphers for use in the TLS or DTLS protocols.
|
|
Packit Service |
991b93 |
@item @code{tls-disabled-mac}: to disable the specified MAC algorithms for use in the TLS or DTLS protocols.
|
|
Packit Service |
991b93 |
@item @code{tls-disabled-group}: to disable the specified group for use in the TLS or DTLS protocols.
|
|
Packit Service |
991b93 |
@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).
|
|
Packit Service |
991b93 |
@end itemize
|
|
Packit Service |
991b93 |
|
|
Packit Service |
991b93 |
Each of the options can be repeated multiple times when multiple values need
|
|
Packit Service |
991b93 |
to be disabled.
|
|
Packit Service |
991b93 |
|
|
Packit Service |
991b93 |
The valid values for the options above can be found in the 'Protocols', 'Digests'
|
|
Packit Service |
991b93 |
'PK-signatures', 'Protocols', 'Ciphrers', and 'MACs' fields of the output of @code{gnutls-cli --list}.
|
|
Packit Service |
991b93 |
|
|
Packit Service |
991b93 |
@subsection Examples
|
|
Packit Service |
991b93 |
|
|
Packit Service |
991b93 |
The following example marks as insecure all digital signature algorithms
|
|
Packit Service |
991b93 |
which depend on SHA384, as well as the RSA-SHA1 signature algorithm.
|
|
Packit Service |
991b93 |
|
|
Packit Service |
991b93 |
@example
|
|
Packit Service |
991b93 |
[overrides]
|
|
Packit Service |
991b93 |
insecure-hash = sha384
|
|
Packit Service |
991b93 |
insecure-sig = rsa-sha1
|
|
Packit Service |
991b93 |
@end example
|
|
Packit Service |
991b93 |
|
|
Packit Service |
991b93 |
The following example marks RSA-SHA256 as insecure for use in certificates
|
|
Packit Service |
991b93 |
and disables the TLS1.0 and TLS1.1 protocols.
|
|
Packit Service |
991b93 |
|
|
Packit Service |
991b93 |
@example
|
|
Packit Service |
991b93 |
[overrides]
|
|
Packit Service |
991b93 |
insecure-sig-for-cert = rsa-sha256
|
|
Packit Service |
991b93 |
disabled-version = tls1.0
|
|
Packit Service |
991b93 |
disabled-version = tls1.1
|
|
Packit Service |
991b93 |
@end example
|
|
Packit Service |
991b93 |
|
|
Packit Service |
991b93 |
The following example disables the @code{AES-128-CBC} and @code{AES-256-CBC}
|
|
Packit Service |
991b93 |
ciphers, the @code{HMAC-SHA1} MAC algorithm and the @code{GROUP-FFDHE8192}
|
|
Packit Service |
991b93 |
group for TLS and DTLS protocols.
|
|
Packit Service |
991b93 |
|
|
Packit Service |
991b93 |
@example
|
|
Packit Service |
991b93 |
[overrides]
|
|
Packit Service |
991b93 |
tls-disabled-cipher = aes-128-cbc
|
|
Packit Service |
991b93 |
tls-disabled-cipher = aes-256-cbc
|
|
Packit Service |
991b93 |
tls-disabled-mac = sha1
|
|
Packit Service |
991b93 |
tls-disabled-group = group-ffdhe8192
|
|
Packit Service |
991b93 |
@end example
|
|
Packit Service |
991b93 |
|
|
Packit Service |
991b93 |
@node Querying for disabled algorithms and protocols
|
|
Packit Service |
991b93 |
@section Querying for disabled algorithms and protocols
|
|
Packit Service |
991b93 |
|
|
Packit Service |
991b93 |
When necessary applications can query whether a particular algorithm
|
|
Packit Service |
991b93 |
or protocol has been marked as insecure or disabled system-wide.
|
|
Packit Service |
991b93 |
Digital signatures can be queried using the following algorithms.
|
|
Packit Service |
991b93 |
@showfuncB{gnutls_sign_is_secure,gnutls_sign_is_secure2}
|
|
Packit Service |
991b93 |
|
|
Packit Service |
991b93 |
Any disabled protocol versions or elliptic curves will not show up in the
|
|
Packit Service |
991b93 |
lists provided by the following functions.
|
|
Packit Service |
991b93 |
|
|
Packit Service |
991b93 |
@showfuncC{gnutls_protocol_list,gnutls_group_list,gnutls_ecc_curve_list}
|
|
Packit Service |
991b93 |
|
|
Packit Service |
991b93 |
It is not possible to query for insecure hash algorithms directly
|
|
Packit Service |
991b93 |
(only indirectly through the signature API).
|
|
Packit Service |
991b93 |
|
|
Packit Service |
991b93 |
|
|
Packit Service |
991b93 |
@node Overriding the parameter verification profile
|
|
Packit Service |
991b93 |
@section Overriding the parameter verification profile
|
|
Packit Service |
991b93 |
|
|
Packit Service |
991b93 |
When verifying a certificate or TLS session parameters, GnuTLS uses a set
|
|
Packit Service |
991b93 |
of profiles associated with the session to determine whether the parameters
|
|
Packit Service |
991b93 |
seen in the session are acceptable. For example, whether the RSA public key
|
|
Packit Service |
991b93 |
size as seen on the wire, or the Diffie-Hellman parameters for the session.
|
|
Packit Service |
991b93 |
These profiles are normally set using the @code{%PROFILE} priority string
|
|
Packit Service |
991b93 |
(see @ref{Priority Strings} and @ref{Selecting cryptographic key sizes}).
|
|
Packit Service |
991b93 |
|
|
Packit Service |
991b93 |
It is possible to set the low bar profile that applications cannot override
|
|
Packit Service |
991b93 |
using the following.
|
|
Packit Service |
991b93 |
|
|
Packit Service |
991b93 |
@example
|
|
Packit Service |
991b93 |
[overrides]
|
|
Packit Service |
991b93 |
|
|
Packit Service |
991b93 |
# do not allow applications use the LOW or VERY-WEAK profiles.
|
|
Packit Service |
991b93 |
min-verification-profile = legacy
|
|
Packit Service |
991b93 |
|
|
Packit Service |
991b93 |
@end example
|
|
Packit Service |
991b93 |
|
|
Packit Service |
991b93 |
@node Overriding the default priority string
|
|
Packit Service |
991b93 |
@section Overriding the default priority string
|
|
Packit Service |
991b93 |
|
|
Packit Service |
991b93 |
GnuTLS uses default priority string which is defined at compiled
|
|
Packit Service |
991b93 |
time. Usually it is set to @code{NORMAL}. This override allows to set
|
|
Packit Service |
991b93 |
the default priority string to something more appropriate for a given
|
|
Packit Service |
991b93 |
deployment.
|
|
Packit Service |
991b93 |
|
|
Packit Service |
991b93 |
Below example sets a more specific default priority string.
|
|
Packit Service |
991b93 |
@example
|
|
Packit Service |
991b93 |
[overrides]
|
|
Packit Service |
991b93 |
default-priority-string = SECURE128:-VERS-TLS-ALL:+VERS-TLS1.3
|
|
Packit Service |
991b93 |
|
|
Packit Service |
991b93 |
@end example
|