OpenSSL Cookbook  3rd Edition

Cipher suite keywords are the basic building blocks of cipher suite configuration. Each suite name (e.g., RC4-SHA) is a keyword that selects exactly one suite.¹ All other keywords select groups of suites according to some criteria. Keyword names are case-sensitive. In this section, I will provide an overview of all cipher suite keywords supported by OpenSSL, one group at a time.

Group keywords are shortcuts that select frequently used cipher suites. For example, HIGH will select only very strong cipher suites.

Digest keywords select suites that use a particular digest algorithm. For example, SHA256 selects all suites that rely on SHA256 for integrity validation.

Authentication keywords select suites based on the authentication method they use. Today, the RSA public key algorithm is still used by the majority of certificates, with ECDSA quickly catching up.

Key exchange keywords select suites based on the key exchange algorithm. When it comes to ephemeral Diffie-Hellman suites, OpenSSL is inconsistent in naming the suites and the keywords. In the suite names, ephemeral suites tend to have an E at the end of the key exchange algorithm (e.g., ECDHE-RSA-RC4-SHA and DHE-RSA-AES256-SHA), but in the keywords the E is at the beginning (e.g., EECDH and EDH). The preferred names today are DHE and ECDHE; the other keywords are supported for backward compatibility.

Cipher keywords select suites based on the cipher they use.

What remains is a number of suites that do not fit into any other category. The bulk of them are related to the GOST standards, which are relevant for the countries that are part of the Commonwealth of Independent States, formed after the breakup of the Soviet Union. The GOST suites are defined but require the GOST engine to be activated. The GOST engine is not part of the core OpenSSL since version 1.1.0.

In most cases, you’ll use keywords by themselves, but it’s also possible to combine them to select only suites that meet several requirements, by connecting two or more keywords with the + character. In the following example, we select suites that use the ECDHE key exchange in combination with AES-GCM:

$ openssl ciphers -v -s -tls1_2 'EECDH+AESGCM'
ECDHE-ECDSA-AES256-GCM-SHA384  TLSv1.2 Kx=ECDH Au=ECDSA Enc=AESGCM(256) Mac=AEAD
ECDHE-RSA-AES256-GCM-SHA384    TLSv1.2 Kx=ECDH Au=RSA   Enc=AESGCM(256) Mac=AEAD
ECDHE-ECDSA-AES128-GCM-SHA256  TLSv1.2 Kx=ECDH Au=ECDSA Enc=AESGCM(128) Mac=AEAD
ECDHE-RSA-AES128-GCM-SHA256    TLSv1.2 Kx=ECDH Au=RSA   Enc=AESGCM(128) Mac=AEAD

The key concept in building a cipher suite configuration is that of the current suite list. The list always starts empty, without any suites, but every keyword that you add to the configuration string will change the list in some way. By default, new suites are appended to the list. In the following example, the configuration starts with all suites that use the ECDHE key exchange, followed by all suites that use the DHE key exchange:

$ openssl ciphers -v 'ECDHE:DHE'

The colon character is commonly used to separate keywords, but spaces and commas are equally acceptable. The following command produces the same output as the previous example:

$ openssl ciphers -v 'ECDHE DHE'

Keyword modifiers are characters you can place at the beginning of each keyword in order to change the default action (adding to the list) to something else. The following actions are supported:

Append

Add suites to the end of the list. If any of the suites are already on the list, they will remain in their present position. This is the default action, which is invoked when there is no modifier in front of the keyword.

Delete (-)

Remove all matching suites from the list, potentially allowing some other keyword to reintroduce them later.

Permanently delete (!)

Remove all matching suites from the list and prevent them from being added later by another keyword. This modifier is useful for specifying all the suites you never want to use, making further selection easier and preventing mistakes.

Move to the end (+)

Move all matching suites to the end of the list. This works only on existing suites; it never adds new suites to the list. This modifier is useful if you want to keep some weaker suites enabled but prefer the stronger ones. For example, the string AES:+AES256 enables all AES suites but pushes the 256-bit ones to the end.

There are two types of errors you might experience while working on your configuration. The first is a result of a typo or an attempt to use a keyword that does not exist:

$ openssl ciphers -v '@HIGH'
Error in cipher list
140460843755168:error:140E6118:SSL routines:SSL_CIPHER_PROCESS_RULESTR:invalid command:ssl_ciph.c:1317:

The output is cryptic, but it does contain an error message.

Another possibility is that you end up with an empty list of cipher suites, in which case you might see something similar to the following:

$ openssl ciphers -v 'SHA512'
Error in cipher list
140202299557536:error:1410D0B9:SSL routines:SSL_CTX_set_cipher_list:no cipher match:ssl_lib.c:1312: