Priority Strings (GnuTLS 3.8.10)

Priority Strings (GnuTLS 3.8.10)
Next:
Selecting cryptographic key sizes
, Previous:
Handling alerts
, Up:
How to use GnuTLS in applications
Contents
][
Index
6.10 Priority strings
How to use Priority Strings
The GnuTLS priority strings specify the TLS session’s handshake
algorithms and options in a compact, easy-to-use format. These
strings are intended as a user-specified override of the library defaults.
That is, we recommend applications using the default settings
(c.f.
gnutls_set_default_priority
or
gnutls_set_default_priority_append
), and provide the user
with access to priority strings for overriding the default behavior,
on configuration files, or other UI. Following such a principle,
makes the GnuTLS library as the default settings provider. That is
necessary and a good practice, because TLS protocol hardening and
phasing out of legacy algorithms, is easier to coordinate when happens
in a single library.
int
gnutls_set_default_priority
(gnutls_session_t
session
int
gnutls_set_default_priority_append
(gnutls_session_t
session
, const char *
add_prio
, const char **
err_pos
, unsigned
flags
int
gnutls_priority_set_direct
(gnutls_session_t
session
, const char *
priorities
, const char **
err_pos
The priority string translation to the internal GnuTLS form requires
processing and the generated internal form also occupies some memory.
For that, it is recommended to do that processing once in server side,
and share the generated data across sessions. The following functions
allow the generation of a "priority cache" and the sharing of it across
sessions.
int
gnutls_priority_init2
(gnutls_priority_t *
priority_cache
, const char *
priorities
, const char **
err_pos
, unsigned
flags
int
gnutls_priority_init
(gnutls_priority_t *
priority_cache
, const char *
priorities
, const char **
err_pos
int
gnutls_priority_set
(gnutls_session_t
session
, gnutls_priority_t
priority
void
gnutls_priority_deinit
(gnutls_priority_t
priority_cache
Using Priority Strings
A priority string string may contain a single initial keyword such as in
Table 6.3
and may be followed by additional algorithm or
special keywords. Note that their description is intentionally avoiding
specific algorithm details, as the priority strings are not constant between
gnutls versions (they are periodically updated to account for cryptographic
advances while providing compatibility with old clients and servers).
Keyword
Description
@KEYWORD
Means that a compile-time specified system configuration file (see
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
format ’KEYWORD=VALUE’, e.g., ’SYSTEM=NORMAL:+ARCFOUR-128’.
Since version 3.5.1 it is allowed to specify fallback keywords by
separating them with a comma, such as @KEYWORD1,KEYWORD2, and the
first valid keyword will be used.
PERFORMANCE
All the known to be secure ciphersuites are enabled,
limited to 128 bit ciphers and sorted by terms of speed
performance. The message authenticity security level is of 64 bits or more,
and the certificate verification profile is set to GNUTLS_PROFILE_LOW (80-bits).
NORMAL
Means all the known to be secure ciphersuites. The ciphers are sorted by security
margin, although the 256-bit ciphers are included as a fallback only.
The message authenticity security level is of 64 bits or more,
and the certificate verification profile is set to GNUTLS_PROFILE_LOW (80-bits).
This priority string implicitly enables ECDHE and DHE. The ECDHE ciphersuites
are placed first in the priority order, but due to compatibility
issues with the DHE ciphersuites they are placed last in the priority order,
after the plain RSA ciphersuites.
LEGACY
This sets the NORMAL settings that were used for GnuTLS 3.2.x or earlier. There is
no verification profile set, and the allowed DH primes are considered
weak today (but are often used by misconfigured servers).
PFS
Means all the known to be secure ciphersuites that support perfect forward
secrecy (ECDHE and DHE). The ciphers are sorted by security
margin, although the 256-bit ciphers are included as a fallback only.
The message authenticity security level is of 80 bits or more,
and the certificate verification profile is set to GNUTLS_PROFILE_LOW (80-bits).
This option is available since 3.2.4 or later.
SECURE128
Means all known to be secure ciphersuites that offer a
security level 128-bit or more.
The message authenticity security level is of 80 bits or more,
and the certificate verification profile is set to GNUTLS_PROFILE_LOW (80-bits).
SECURE192
Means all the known to be secure ciphersuites that offer a
security level 192-bit or more.
The message authenticity security level is of 128 bits or more,
and the certificate verification profile is set to GNUTLS_PROFILE_HIGH (128-bits).
SECURE256
Currently alias for SECURE192. This option, will enable ciphers which use a
256-bit key but, due to limitations of the TLS protocol, the overall security
level will be 192-bits (the security level depends on more factors than cipher key size).
SUITEB128
Means all the NSA Suite B cryptography (RFC5430) ciphersuites
with an 128 bit security level, as well as the enabling of the corresponding
verification profile.
SUITEB192
Means all the NSA Suite B cryptography (RFC5430) ciphersuites
with an 192 bit security level, as well as the enabling of the corresponding
verification profile.
NONE
Means nothing is enabled. This disables even protocol versions.
It should be followed by the algorithms to be enabled. Note that
using this option to build a priority string gives detailed control
into the resulting settings, however with new revisions of the TLS protocol
new priority items are routinely added, and such strings are not
forward compatible with new protocols. As such, we
advice against using that option for applications targeting multiple versions
of the GnuTLS library, and recommend using the defaults (see above) or
adjusting the defaults via
gnutls_set_default_priority_append
Table 6.3:
Supported initial keywords.
Unless the initial keyword is "NONE" the defaults (in preference
order) are for TLS protocols TLS 1.2, TLS1.1, TLS1.0;
for certificate types X.509.
In key exchange algorithms when in NORMAL or SECURE levels the
perfect forward secrecy algorithms take precedence of the other
protocols. In all cases all the supported key exchange algorithms
are enabled.
Note that the SECURE levels distinguish between overall security level and
message authenticity security level. That is because the message
authenticity security level requires the adversary to break
the algorithms at real-time during the protocol run, whilst
the overall security level refers to off-line adversaries
(e.g. adversaries breaking the ciphertext years after it was captured).
The NONE keyword, if used, must followed by keywords specifying
the algorithms and protocols to be enabled. The other initial keywords
do not require, but may be followed by such keywords. All level keywords
can be combined, and for example a level of "SECURE256:+SECURE128" is
allowed.
The order with which every algorithm or protocol
is specified is significant. Algorithms specified before others
will take precedence. The supported in the GnuTLS version corresponding
to this document algorithms and protocols are shown in
Table 6.4
to list the supported algorithms in your currently using version use
gnutls-cli -l
To avoid collisions in order to specify a protocol version
with "VERS-", signature algorithms with "SIGN-" and certificate types with "CTYPE-".
All other algorithms don’t need a prefix. Each specified keyword (except
for
special keywords
) can be prefixed with any of the following
characters.
’!’ or ’-’
appended with an algorithm will remove this algorithm.
"+"
appended with an algorithm will add this algorithm.
Type
Keywords
Ciphers
Examples are AES-128-GCM, AES-256-GCM, AES-256-CBC, GOST28147-TC26Z-CNT; see also
Table 3.1
for more options. Catch all name is CIPHER-ALL which will add
all the algorithms from NORMAL priority. The shortcut for secure GOST
algorithms is CIPHER-GOST-ALL.
Key exchange
RSA, RSA-PSK, RSA-EXPORT, DHE-RSA, DHE-DSS, SRP, SRP-RSA, SRP-DSS,
PSK, DHE-PSK, ECDHE-PSK, ECDHE-RSA, ECDHE-ECDSA, VKO-GOST-12, ANON-ECDH, ANON-DH.
Catch all name is KX-ALL which will add all the algorithms from NORMAL
priority. Under TLS1.3, the DHE-PSK and ECDHE-PSK strings are equivalent
and instruct for a Diffie-Hellman key exchange using the enabled groups. The
shortcut for secure GOST algorithms is KX-GOST-ALL.
MAC
MD5, SHA1, SHA256, SHA384, GOST28147-TC26Z-IMIT, AEAD (used with
GCM ciphers only). All algorithms from NORMAL priority can be accessed with
MAC-ALL. The shortcut for secure GOST algorithms is MAC-GOST-ALL.
Compression algorithms
COMP-NULL, COMP-DEFLATE. Catch all is COMP-ALL.
TLS versions
VERS-TLS1.0, VERS-TLS1.1, VERS-TLS1.2, VERS-TLS1.3,
VERS-DTLS0.9, VERS-DTLS1.0, VERS-DTLS1.2.
Catch all are VERS-ALL, and will enable
all protocols from NORMAL priority. To distinguish between TLS and DTLS
versions you can use VERS-TLS-ALL and VERS-DTLS-ALL.
Signature algorithms
SIGN-RSA-SHA1, SIGN-RSA-SHA224,
SIGN-RSA-SHA256, SIGN-RSA-SHA384, SIGN-RSA-SHA512, SIGN-DSA-SHA1,
SIGN-DSA-SHA224, SIGN-DSA-SHA256, SIGN-RSA-MD5, SIGN-ECDSA-SHA1,
SIGN-ECDSA-SHA224, SIGN-ECDSA-SHA256, SIGN-ECDSA-SHA384, SIGN-ECDSA-SHA512,
SIGN-EdDSA-Ed25519, SIGN-EdDSA-Ed448,
SIGN-RSA-PSS-SHA256, SIGN-RSA-PSS-SHA384, SIGN-RSA-PSS-SHA512,
SIGN-GOSTR341001, SIGN-GOSTR341012-256, SIGN-GOSTR341012-512.
Catch all which enables all algorithms from NORMAL priority is SIGN-ALL.
Shortcut which enables secure GOST algorithms is SIGN-GOST-ALL.
This option is only considered for TLS 1.2 and later.
Groups
GROUP-SECP192R1, GROUP-SECP224R1, GROUP-SECP256R1, GROUP-SECP384R1,
GROUP-SECP521R1, GROUP-X25519, GROUP-X448, GROUP-GC256B, GROUP-GC512A,
GROUP-FFDHE2048, GROUP-FFDHE3072, GROUP-FFDHE4096, GROUP-FFDHE6144, and
GROUP-FFDHE8192.
Groups include both elliptic curve groups, e.g., SECP256R1, as well as
finite field groups such as FFDHE2048. Catch all which enables all groups
from NORMAL priority is GROUP-ALL. The helper keywords GROUP-DH-ALL,
GROUP-GOST-ALL and GROUP-EC-ALL are also available, restricting the groups
to finite fields (DH), GOST curves and generic elliptic curves.
Elliptic curves (legacy)
CURVE-SECP192R1, CURVE-SECP224R1, CURVE-SECP256R1, CURVE-SECP384R1,
CURVE-SECP521R1, CURVE-X25519, and CURVE-X448.
Catch all which enables all curves from NORMAL priority is CURVE-ALL. Note
that the CURVE keyword is kept for backwards compatibility only, for new
applications see the GROUP keyword above.
Certificate types
Certificate types can be given in a symmetric fashion (i.e. the same for
both client and server) or, as of GnuTLS 3.6.4, in an asymmetric fashion
(i.e. different for the client than for the server). Alternative certificate
types must be explicitly enabled via flags in
gnutls_init
The currently supported types are CTYPE-X509, CTYPE-RAWPK which apply both to
client and server; catch all is CTYPE-ALL. The types CTYPE-CLI-X509, CTYPE-SRV-X509,
CTYPE-CLI-RAWPK, CTYPE-SRV-RAWPK can be used to specialize on client or server;
catch all is CTYPE-CLI-ALL and CTYPE-SRV-ALL. The type ’X509’ is aliased to ’X.509’
for legacy reasons.
Generic
The keyword GOST is a shortcut for secure GOST algorithms (MACs, ciphers,
KXes, groups and signatures). For example the following string will enable all
TLS 1.2 GOST ciphersuites: ’NONE:+VERS-TLS1.2:+GOST’.
Table 6.4:
The supported algorithm keywords in priority strings.
Note that the finite field groups (indicated by the FFDHE prefix) and DHE key
exchange methods are generally slower
20
than their elliptic curves counterpart
(ECDHE).
The available special keywords are shown in
Table 6.5
and
Table 6.6
Keyword
Description
%COMPAT
will enable compatibility mode. It might mean that violations
of the protocols are allowed as long as maximum compatibility with
problematic clients and servers is achieved. More specifically this
string will tolerate packets over the maximum allowed TLS record,
and add a padding to TLS Client Hello packet to prevent it being in the
256-512 range which is known to be causing issues with a commonly used
firewall (see the %DUMBFW option).
%DUMBFW
will add a private extension with bogus data that make the client
hello exceed 512 bytes. This avoids a black hole behavior in some
firewalls. This is the [
RFC7685
] client hello padding extension, also enabled
with %COMPAT.
%NO_EXTENSIONS
will prevent the sending of any TLS extensions in client side. Note
that TLS 1.2 requires extensions to be used, as well as safe
renegotiation thus this option must be used with care. When this option
is set no versions later than TLS1.2 can be negotiated.
%NO_SHUFFLE_EXTENSIONS
will prevent randomizing the order of ClientHello extensions. By
default, those extensions are randomized to make fingerprinting harder.
%NO_STATUS_REQUEST
will prevent sending of the TLS status_request extension in client side.
%NO_TICKETS
will prevent the advertizing of the TLS session ticket extension.
%NO_TICKETS_TLS12
will prevent the advertizing of the TLS session ticket extension in TLS 1.2.
This is implied by the PFS keyword.
%NO_SESSION_HASH
will prevent the advertizing the TLS extended master secret (session hash)
extension.
%FORCE_SESSION_HASH
negotiate the TLS extended master secret (session hash) extension.
Specifying both %NO_SESSION_HASH and %FORCE_SESSION_HASH is not
supported, and the behavior is undefined.
%SERVER_PRECEDENCE
The ciphersuite will be selected according to server priorities
and not the client’s.
%SSL3_RECORD_VERSION
will use SSL3.0 record version in client hello.
By default GnuTLS will set the minimum supported version as the
client hello record version (do not confuse that version with the
proposed handshake version at the client hello).
%LATEST_RECORD_VERSION
will use the latest TLS version record version in client hello.
Table 6.5:
Special priority string keywords.
Keyword
Description
%STATELESS_COMPRESSION
ignored; no longer used.
%DISABLE_WILDCARDS
will disable matching wildcards when comparing hostnames
in certificates.
%NO_ETM
will disable the encrypt-then-mac TLS extension (RFC7366). This is
implied by the %COMPAT keyword.
%FORCE_ETM
negotiate CBC ciphersuites only when both sides of the connection support
encrypt-then-mac TLS extension (RFC7366).
%DISABLE_SAFE_RENEGOTIATION
will completely disable safe renegotiation. Do not use unless you
know what you are doing.
%UNSAFE_RENEGOTIATION
will allow handshakes and re-handshakes
without the safe renegotiation extension. Note that for clients
this mode is insecure (you may be under attack), and for servers it
will allow insecure clients to connect (which could be fooled by an
attacker). Do not use unless you know what you are doing and want
maximum compatibility.
%PARTIAL_RENEGOTIATION
will allow initial handshakes to proceed,
but not re-handshakes. This leaves the client vulnerable to attack,
and servers will be compatible with non-upgraded clients for
initial handshakes. This is currently the default for clients and
servers, for compatibility reasons.
%SAFE_RENEGOTIATION
will enforce safe renegotiation. Clients and
servers will refuse to talk to an insecure peer. Currently this
causes interoperability problems, but is required for full protection.
%FALLBACK_SCSV
will enable the use of the fallback signaling cipher suite value in the
client hello. Note that this should be set only by applications that
try to reconnect with a downgraded protocol version. See RFC7507 for
details.
%DISABLE_TLS13_COMPAT_MODE
will disable TLS 1.3 middlebox compatibility mode (RFC8446, Appendix
D.4) for non-compliant middleboxes.
%VERIFY_ALLOW_BROKEN
will allow signatures with known to be broken algorithms (such as MD5 or
SHA1) in certificate chains.
%VERIFY_ALLOW_SIGN_RSA_MD5
will allow RSA-MD5 signatures in certificate chains.
%VERIFY_ALLOW_SIGN_WITH_SHA1
will allow signatures with SHA1 hash algorithm in certificate chains.
%VERIFY_DISABLE_CRL_CHECKS
will disable CRL or OCSP checks in the verification of the certificate chain.
%VERIFY_ALLOW_X509_V1_CA_CRT
will allow V1 CAs in chains.
%PROFILE_(LOW|LEGACY|MEDIUM|HIGH|ULTRA|FUTURE)
require a certificate verification profile the corresponds to the specified
security level, see
Table 6.7
for the mappings to values.
%PROFILE_(SUITEB128|SUITEB192)
require a certificate verification profile the corresponds to SUITEB. Note
that an initial keyword that enables SUITEB automatically sets the profile.
Table 6.6:
More priority string keywords.
Finally the ciphersuites enabled by any priority string can be
listed using the
gnutls-cli
application (see
gnutls-cli Invocation
),
or by using the priority functions as in
Listing the ciphersuites in a priority string
Example priority strings are:
The system imposed security level:
"SYSTEM"

The default priority without the HMAC-MD5:
"NORMAL:-MD5"

Specifying RSA with AES-128-CBC:
"NONE:+VERS-TLS-ALL:+MAC-ALL:+RSA:+AES-128-CBC:+SIGN-ALL:+COMP-NULL"

Specifying the defaults plus ARCFOUR-128:
"NORMAL:+ARCFOUR-128"

Enabling the 128-bit secure ciphers, while disabling TLS 1.0:
"SECURE128:-VERS-TLS1.0"

Enabling the 128-bit and 192-bit secure ciphers, while disabling all TLS versions
except TLS 1.2:
"SECURE128:+SECURE192:-VERS-ALL:+VERS-TLS1.2"
Footnotes
(20)
It depends on the group in use. Groups with
less bits are always faster, but the number of bits ties with the security
parameter. See
Selecting cryptographic key sizes
for the acceptable security levels.
Next:
Selecting cryptographic key sizes
, Previous:
Handling alerts
, Up:
How to use GnuTLS in applications
Contents
][
Index