Add new cipherlist-setting APIs that reject nonsense.
The new APIs are SSL_CTX_set_strict_cipher_list() and
SSL_set_strict_cipher_list(). They have two motivations:
First, typos in cipher lists can go undetected for a long time, and
can have surprising consequences when silently ignored.
Second, there is a tendency to use superstition in the construction of
cipher lists, for example by "turning off" things that do not actually
exist. This leads to the corrosive belief that DEFAULT and ALL ought
not to be trusted. This belief is false.
Change-Id: I42909b69186e0b4cf45457e5c0bc968f6bbf231a
Reviewed-on: https://boringssl-review.googlesource.com/13925
Commit-Queue: Matt Braithwaite <mab@google.com>
Reviewed-by: Matt Braithwaite <mab@google.com>
diff --git a/include/openssl/ssl.h b/include/openssl/ssl.h
index 23e5e9b..e38e23c 100644
--- a/include/openssl/ssl.h
+++ b/include/openssl/ssl.h
@@ -1313,7 +1313,9 @@
* |TLSv1_2| matches ciphers new in TLS 1.2. This is confusing and should not
* be used.
*
- * Unknown rules silently match nothing.
+ * Unknown rules are silently ignored by legacy APIs, and rejected by APIs with
+ * "strict" in the name, which should be preferred. Cipher lists can be long and
+ * it's easy to commit typos.
*
* The special |@STRENGTH| directive will sort all enabled ciphers by strength.
*
@@ -1342,12 +1344,29 @@
* substituted when a cipher string starts with 'DEFAULT'. */
#define SSL_DEFAULT_CIPHER_LIST "ALL"
+/* SSL_CTX_set_strict_cipher_list configures the cipher list for |ctx|,
+ * evaluating |str| as a cipher string and returning error if |str| contains
+ * anything meaningless. It returns one on success and zero on failure. */
+OPENSSL_EXPORT int SSL_CTX_set_strict_cipher_list(SSL_CTX *ctx,
+ const char *str);
+
/* SSL_CTX_set_cipher_list configures the cipher list for |ctx|, evaluating
- * |str| as a cipher string. It returns one on success and zero on failure. */
+ * |str| as a cipher string. It returns one on success and zero on failure.
+ *
+ * Prefer to use |SSL_CTX_set_strict_cipher_list|. This function tolerates
+ * garbage inputs, unless an empty cipher list results. */
OPENSSL_EXPORT int SSL_CTX_set_cipher_list(SSL_CTX *ctx, const char *str);
+/* SSL_set_strict_cipher_list configures the cipher list for |ssl|, evaluating
+ * |str| as a cipher string and returning error if |str| contains anything
+ * meaningless. It returns one on success and zero on failure. */
+OPENSSL_EXPORT int SSL_set_strict_cipher_list(SSL *ssl, const char *str);
+
/* SSL_set_cipher_list configures the cipher list for |ssl|, evaluating |str| as
- * a cipher string. It returns one on success and zero on failure. */
+ * a cipher string. It returns one on success and zero on failure.
+ *
+ * Prefer to use |SSL_set_strict_cipher_list|. This function tolerates garbage
+ * inputs, unless an empty cipher list results. */
OPENSSL_EXPORT int SSL_set_cipher_list(SSL *ssl, const char *str);
/* SSL_get_ciphers returns the cipher list for |ssl|, in order of preference. */
