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. That 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).
int gnutls_priority_set_direct (gnutls_session_t session, const char * priorities, const char ** err_pos)
int gnutls_priority_set (gnutls_session_t session, gnutls_priority_t priority)
Keyword | Description |
---|---|
@KEYWORD | Means that a compile-time specified system configuration file17 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’. |
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 protocols and compression methods. It should be followed by the algorithms to be enabled. |
Unless the initial keyword is "NONE" the defaults (in preference order) are for TLS protocols TLS 1.2, TLS1.1, TLS1.0; for compression NULL; 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 algorithms and protocols are shown in Table 6.4. To avoid collisions in order to specify a compression algorithm in the priority string you have to prefix it with "COMP-", protocol versions 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.
Type | Keywords |
---|---|
Ciphers | AES-128-CBC, AES-256-CBC, AES-128-GCM, CAMELLIA-128-CBC, CAMELLIA-256-CBC, ARCFOUR-128, 3DES-CBC. Catch all name is CIPHER-ALL which will add all the algorithms from NORMAL priority. |
Key exchange | RSA, DHE-RSA, DHE-DSS, SRP, SRP-RSA, SRP-DSS,
PSK, DHE-PSK, ECDHE-RSA, ANON-ECDH, ANON-DH. The
Catch all name is KX-ALL which will add all the algorithms from NORMAL
priority.
Add |
MAC | MD5, SHA1, SHA256, SHA384, AEAD (used with GCM ciphers only). All algorithms from NORMAL priority can be accessed with MAC-ALL. |
Compression algorithms | COMP-NULL, COMP-DEFLATE. Catch all is COMP-ALL. |
TLS versions | VERS-TLS1.0, VERS-TLS1.1, VERS-TLS1.2, VERS-DTLS1.0, VERS-DTLS1.2. Catch all are VERS-ALL, 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. Catch all is SIGN-ALL. This is only valid for TLS 1.2 and later. |
Elliptic curves | CURVE-SECP192R1, CURVE-SECP224R1, CURVE-SECP256R1, CURVE-SECP384R1, CURVE-SECP521R1. Catch all is CURVE-ALL. |
Certificate type | CTYPE-OPENPGP, CTYPE-X509. Catch all is CTYPE-ALL. |
Note that the DHE key exchange methods are generally slower18 than their elliptic curves counterpart (ECDHE). Moreover the plain Diffie-Hellman key exchange requires parameters to be generated and associated with a credentials structure by the server (see Parameter generation).
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 would disable TLS record random padding, 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. |
%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 a non-standard TLS extension, use with care. |
%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. |
%NO_TICKETS | will prevent the advertizing of the TLS session ticket extension. 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. This is the default. |
%LATEST_RECORD_VERSION | will use the latest TLS version record version in client hello. |
Keyword | Description |
---|---|
%STATELESS_COMPRESSION | will disable keeping state across records when compressing. This may help to mitigate attacks when compression is used but an attacker is in control of input data. This has to be used only when the data that are possibly controlled by an attacker are placed in separate records. |
%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. |
%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. |
%VERIFY_ALLOW_SIGN_RSA_MD5 | will allow RSA-MD5 signatures 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) | 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 and enabling compression: "SECURE128:-VERS-TLS1.0:+COMP-DEFLATE" Enabling the 128-bit and 192-bit secure ciphers, while disabling all TLS versions except TLS 1.2: "SECURE128:+SECURE192:-VERS-TLS-ALL:+VERS-TLS1.2"
The default is /etc/gnutls/default-priorities
.
It depends on the group used. Primes with lesser bits are always faster, but also easier to break. 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]