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

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.

Note that the finite field groups (indicated by the FFDHE prefix) and DHE key exchange methods are generally slower²⁰ than their elliptic curves counterpart (ECDHE).

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

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"