Next: Selecting cryptographic key sizes, Previous: Handling alerts, Up: How to use GnuTLS in applications [Contents][Index]
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)
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||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 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.|
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
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.
appended with an algorithm will remove this algorithm.
appended with an algorithm will add this algorithm.
|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’.|
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.
|%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_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.|
|%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.|
|%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 completely. 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.|
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"
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]