Next: , Previous: , 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).

KeywordDescription
@KEYWORDMeans 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 such as @KEYWORD1,@KEYWORD2, and the first valid keyword will be used.

PERFORMANCEAll 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).
NORMALMeans 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.

LEGACYThis 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).
PFSMeans 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.
SECURE128Means 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).
SECURE192Means 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).
SECURE256Currently 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).
SUITEB128Means all the NSA Suite B cryptography (RFC5430) ciphersuites with an 128 bit security level, as well as the enabling of the corresponding verification profile.
SUITEB192Means all the NSA Suite B cryptography (RFC5430) ciphersuites with an 192 bit security level, as well as the enabling of the corresponding verification profile.
NONEMeans 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.

TypeKeywords
CiphersExamples 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 exchangeRSA, 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.
MACMD5, 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 algorithmsCOMP-NULL, COMP-DEFLATE. Catch all is COMP-ALL.
TLS versionsVERS-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 algorithmsSIGN-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.
GroupsGROUP-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 typesCertificate 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.

GenericThe 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 slower20 than their elliptic curves counterpart (ECDHE).

The available special keywords are shown in Table 6.5 and Table 6.6.

KeywordDescription
%COMPATwill 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).
%DUMBFWwill 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_EXTENSIONSwill 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_EXTENSIONSwill prevent randomizing the order of ClientHello extensions. By default, those extensions are randomized to make fingerprinting harder.
%NO_STATUS_REQUESTwill prevent sending of the TLS status_request extension in client side.
%NO_TICKETSwill prevent the advertizing of the TLS session ticket extension.
%NO_TICKETS_TLS12will prevent the advertizing of the TLS session ticket extension in TLS 1.2. This is implied by the PFS keyword.
%NO_SESSION_HASHwill prevent the advertizing the TLS extended master secret (session hash) extension.
%FORCE_SESSION_HASHnegotiate 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_PRECEDENCEThe ciphersuite will be selected according to server priorities and not the client’s.
%SSL3_RECORD_VERSIONwill 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_VERSIONwill use the latest TLS version record version in client hello.

Table 6.5: Special priority string keywords.

KeywordDescription
%STATELESS_COMPRESSIONignored; no longer used.
%DISABLE_WILDCARDSwill disable matching wildcards when comparing hostnames in certificates.
%NO_ETMwill disable the encrypt-then-mac TLS extension (RFC7366). This is implied by the %COMPAT keyword.
%FORCE_ETMnegotiate CBC ciphersuites only when both sides of the connection support encrypt-then-mac TLS extension (RFC7366).
%DISABLE_SAFE_RENEGOTIATIONwill completely disable safe renegotiation. Do not use unless you know what you are doing.
%UNSAFE_RENEGOTIATIONwill 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_RENEGOTIATIONwill 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_RENEGOTIATIONwill 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_SCSVwill 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_MODEwill disable TLS 1.3 middlebox compatibility mode (RFC8446, Appendix D.4) for non-compliant middleboxes.
%VERIFY_ALLOW_BROKENwill allow signatures with known to be broken algorithms (such as MD5 or SHA1) in certificate chains.
%VERIFY_ALLOW_SIGN_RSA_MD5will allow RSA-MD5 signatures in certificate chains.
%VERIFY_ALLOW_SIGN_WITH_SHA1will allow signatures with SHA1 hash algorithm in certificate chains.
%VERIFY_DISABLE_CRL_CHECKSwill disable CRL or OCSP checks in the verification of the certificate chain.
%VERIFY_ALLOW_X509_V1_CA_CRTwill 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: , Previous: , Up: How to use GnuTLS in applications   [Contents][Index]