Write documentation for the control string parameter from scratch,

collecting the information by inspecting the source code.

1 files changed, 273 insertions, 30 deletions

diff --git a/lib/libssl/man/SSL_CTX_set_cipher_list.3 b/lib/libssl/man/SSL_CTX_set_cipher_list.3
index 59bcfb5fc5a..a64826e5782 100644
--- a/lib/libssl/man/SSL_CTX_set_cipher_list.3
+++ b/lib/libssl/man/SSL_CTX_set_cipher_list.3
@@ -1,7 +1,24 @@
-.\"	$OpenBSD: SSL_CTX_set_cipher_list.3,v 1.6 2018/03/27 17:35:50 schwarze Exp $
-.\"	OpenSSL b97fdb57 Nov 11 09:33:09 2016 +0100
+.\" $OpenBSD: SSL_CTX_set_cipher_list.3,v 1.7 2018/04/10 21:37:20 schwarze Exp $
+.\" full merge up to: OpenSSL b97fdb57 Nov 11 09:33:09 2016 +0100
 .\"
-.\" This file was written by Lutz Jaenicke <jaenicke@openssl.org>.
+.\" This file is a derived work.
+.\" The changes are covered by the following Copyright and license:
+.\"
+.\" Copyright (c) 2018 Ingo Schwarze <schwarze@openbsd.org>
+.\"
+.\" Permission to use, copy, modify, and distribute this software for any
+.\" purpose with or without fee is hereby granted, provided that the above
+.\" copyright notice and this permission notice appear in all copies.
+.\"
+.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+.\"
+.\" The original file was written by Lutz Jaenicke <jaenicke@openssl.org>.
 .\" Copyright (c) 2000, 2001, 2013 The OpenSSL Project.  All rights reserved.
 .\"
 .\" Redistribution and use in source and binary forms, with or without
@@ -48,7 +65,7 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: March 27 2018 $
+.Dd $Mdocdate: April 10 2018 $
 .Dt SSL_CTX_SET_CIPHER_LIST 3
 .Os
 .Sh NAME
@@ -58,43 +75,268 @@
 .Sh SYNOPSIS
 .In openssl/ssl.h
 .Ft int
-.Fn SSL_CTX_set_cipher_list "SSL_CTX *ctx" "const char *str"
+.Fn SSL_CTX_set_cipher_list "SSL_CTX *ctx" "const char *control"
 .Ft int
-.Fn SSL_set_cipher_list "SSL *ssl" "const char *str"
+.Fn SSL_set_cipher_list "SSL *ssl" "const char *control"
 .Sh DESCRIPTION
 .Fn SSL_CTX_set_cipher_list
-sets the list of available ciphers for
+sets the list of available cipher suites for
 .Fa ctx
-using the control string
-.Fa str .
-The format of the string is described
-in
-.Xr openssl 1 .
-The list of ciphers is inherited by all
+using the
+.Fa control
+string.
+The list of cipher suites is inherited by all
 .Fa ssl
 objects created from
 .Fa ctx .
 .Pp
 .Fn SSL_set_cipher_list
-sets the list of ciphers only for
+sets the list of cipher suites only for
 .Fa ssl .
 .Pp
-The control string
-.Fa str
-should be universally usable and not depend on details of the library
-configuration (ciphers compiled in).
-Thus no syntax checking takes place.
-Items that are not recognized, because the corresponding ciphers are not
-compiled in or because they are mistyped, are simply ignored.
-Failure is only flagged if no ciphers could be collected at all.
+The control string consists of one or more control words
+separated by colon characters
+.Pq Ql \&: .
+Space
+.Pq Ql \ \& ,
+semicolon
+.Pq Ql \&; ,
+and comma
+.Pq Ql \&,
+characters can also be used as separators.
+Each control words selects a set of cipher suites
+and can take one of the following optional prefix characters:
+.Bl -tag -width Ds
+.It \&No prefix:
+Those of the selected cipher suites that have not been made available
+yet are added to the end of the list of available cipher suites,
+preserving their order.
+.It Prefixed minus sign Pq Ql \- :
+Those of the selected cipher suites that have been made available
+earlier are moved back from the list of available cipher suites to
+the beginning of the list of unavailable cipher suites,
+also preserving their order.
+.It Prefixed plus sign Pq Ql + :
+Those of the selected cipher suites have been made available earlier
+are moved to end of the list of available cipher suites, reducing
+their priority, but preserving the order among themselves.
+.It Prefixed exclamation mark Pq Ql \&! :
+The selected cipher suites are permanently deleted, no matter whether
+they had earlier been made available or not, and can no longer
+be added or re-added by later words.
+.El
+.Pp
+The following special words can only be used without a prefix:
+.Bl -tag -width Ds
+.It Cm DEFAULT
+An alias for
+.Sm off
+.Cm ALL No :! Cm aNULL No :! Cm eNULL .
+.Sm on
+It can only be used as the first word.
+.It Cm @STRENGTH
+Sort the list by decreasing encryption strength,
+preserving the order of cipher suites that have the same strength.
+It is usally given as the last word.
+.El
+.Pp
+The following words can be used to select groups of cipher suites,
+with or without a prefix character.
+If two or more of these words are joined with plus signs
+.Pq Ql +
+to form a longer word, only the intersection of the specified sets
+is selected.
+.Bl -tag -width Ds
+.It Cm ADH
+Cipher suites using ephemeral DH for key exchange
+without doing any server authentication.
+Equivalent to
+.Cm kEDH Ns + Ns Cm aNULL .
+.It Cm aDSS
+Cipher suites using DSS server authentication.
+LibreSSL does not provide any such cipher suites.
+.It Cm AEAD
+Cipher suites using Authenticated Encryption with Additional Data.
+.It Cm AECDH
+Cipher suites using ephemeral ECDH for key exchange
+without doing any server authentication.
+Equivalent to
+.Cm kEECDH Ns + Ns Cm aNULL .
+.It Cm aECDSA
+Cipher suites using ECDSA server authentication.
+.It Cm AES
+Cipher suites using AES or AESGCM for symmetric encryption.
+.It Cm AES128
+Cipher suites using AES(128) or AESGCM(128) for symmetric encryption.
+.It Cm AES256
+Cipher suites using AES(256) or AESGCM(256) for symmetric encryption.
+.It Cm AESGCM
+Cipher suites using AESGCM for symmetric encryption.
+.It Cm aGOST
+An alias for
+.Cm aGOST01 .
+.It Cm aGOST01
+Cipher suites using GOST R 34.10-2001 server authentication.
+.It Cm ALL
+All cipher suites except those selected by
+.Cm eNULL .
+.It Cm aNULL
+Cipher suites that don't do any server authentication.
+Not enabled by
+.Cm DEFAULT .
+Beware of man-in-the-middle attacks.
+.It Cm aRSA
+Cipher suites using RSA server authentication.
+.It Cm CAMELLIA
+Cipher suites using Camellia for symmetric encryption.
+.It Cm CAMELLIA128
+Cipher suites using Camellia(128) for symmetric encryption.
+.It Cm CAMELLIA256
+Cipher suites using Camellia(256) for symmetric encryption.
+.It Cm CHACHA20
+Cipher suites using ChaCha20-Poly1305 for symmetric encryption.
+.It Cm COMPLEMENTOFALL
+Cipher suites that are not included in
+.Cm ALL .
+Currently an alias for
+.Cm eNULL .
+.It Cm COMPLEMENTOFDEFAULT
+Cipher suites that are included in
+.Cm ALL ,
+but not included in
+.Cm DEFAULT .
+Currently similar to
+.Cm aNULL Ns :! Ns Cm eNULL
+except for the order of the cipher suites which are
+.Em not
+selected.
+.It Cm DES
+Cipher suites using single DES for symmetric encryption.
+.It Cm 3DES
+Cipher suites using triple DES for symmetric encryption.
+.It Cm DH
+An alias for
+.Cm kEDH .
+.It Cm DHE
+Cipher suites using ephemeral DH for key exchange,
+but excluding those that don't do any server authentication.
+Similar to
+.Cm kEDH Ns :! Ns Cm aNULL
+except for the order of the cipher suites which are
+.Em not
+selected.
+.It Cm DSS
+An alias for
+.Cm aDSS .
+.It Cm ECDH
+An alias for
+.Cm kEECHD .
+.It Cm ECDHE
+Cipher suites using ephemeral ECDH for key exchange,
+but excluding those that don't do any server authentication.
+Similar to
+.Cm kEECDH Ns :! Ns Cm aNULL
+except for the order of the cipher suites which are
+.Em not
+selected.
+.It Cm ECDSA
+An alias for
+.Cm aECDSA .
+.It Cm EDH
+An alias for
+.Cm DHE .
+.It Cm EECHD
+An alias for
+.Cm ECDHE .
+.It Cm eNULL
+Cipher suites that do not use any encryption.
+Not enabled by
+.Cm DEFAULT ,
+and not even included in
+.Cm ALL .
+.It Cm GOST89MAC
+Cipher suites using GOST 28147-89 for message authentication
+instead of HMAC.
+.It Cm GOST94
+Cipher suites using HMAC based on GOST R 34.11-94
+for message authentication.
+.It Cm HIGH
+Cipher suites of high strength.
+Currently, these are cipher suites using
+.Cm CHACHA20 ,
+.Cm AES ,
+.Cm CAMELLIA ,
+or GOST-28178-89-CNT symmetric encryption.
+.It Cm IDEA
+Cipher suites using IDEA for symmetric encryption.
+LibreSSL does not provide any such cipher suites.
+.It Cm kEDH
+Cipher suites using ephemeral DH for key exchange.
+.It Cm kEECDH
+Cipher suites using ephemeral ECDH for key exchange.
+.It Cm kGOST
+Cipher suites using VKO 34.10 key exchange, specified in RFC 4357.
+.It Cm kRSA
+Cipher suites using RSA key exchange.
+.It Cm LOW
+Cipher suites of low strength.
+Currently, these are cipher suites using
+.Cm DES
+or
+.Cm RC4
+symmetric encryption.
+.It Cm MD5
+Cipher suites using MD5 for message authentication.
+.It Cm MEDIUM
+Cipher suites of medium strength.
+Currently, these are cipher suites using
+.Cm 3DES
+symmetric encryption.
+.It Cm NULL
+An alias for
+.Cm eNULL .
+.It Cm RC4
+Cipher suites using RC4 for symmetric encryption.
+.It Cm RSA
+Cipher suites using RSA for both key exchange and server authentication.
+Equivalent to
+.Cm kRSA Ns + Ns Cm aRSA .
+.It Cm SHA
+An alias for
+.Cm SHA1 .
+.It Cm SHA1
+Cipher suites using SHA1 for message authentication.
+.It Cm SHA256
+Cipher suites using SHA256 for message authentication.
+.It Cm SHA384
+Cipher suites using SHA384 for message authentication.
+.It Cm SSLv3
+An alias for
+.Cm TLSv1 .
+.It Cm STREEBOG256
+Cipher suites using STREEBOG256 for message authentication.
+.It Cm TLSv1
+Cipher suites usable with any TLS protocol.
+.It Cm TLSv1.2
+Cipher suites for the TLSv1.2 protocol.
+.El
+.Pp
+The full words returned by the
+.Xr openssl 1
+.Cm ciphers
+command can be used to select individual cipher suites.
+.Pp
+Unknown words are silently ignored, selecting no cipher suites.
+Failure is only flagged if the
+.Fa control
+string contains invalid bytes
+or if no matching cipher suites are available at all.
 .Pp
-It should be noted that inclusion of a cipher to be used into the list is a
-necessary condition.
-On the client side, the inclusion into the list is also sufficient.
-On the server side, additional restrictions apply.
-All ciphers have additional requirements.
+On the client side, including a cipher suite into the list of
+available cipher suites is sufficient for using it.
+On the server side, all cipher suites have additional requirements.
 ADH ciphers don't need a certificate, but DH-parameters must have been set.
-All other ciphers need a corresponding certificate and key.
+All other cipher suites need a corresponding certificate and key.
 .Pp
 A RSA cipher can only be chosen when a RSA certificate is available.
 RSA ciphers using DHE need a certificate and key and additional DH-parameters
@@ -105,7 +347,8 @@ A DSA cipher can only be chosen when a DSA certificate is available.
 DSA ciphers always use DH key exchange and therefore need DH-parameters (see
 .Xr SSL_CTX_set_tmp_dh_callback 3 ) .
 .Pp
-When these conditions are not met for any cipher in the list (for example, a
+When these conditions are not met
+for any cipher suite in the list (for example, a
 client only supports export RSA ciphers with an asymmetric key length of 512
 bits and the server is not configured to use temporary RSA keys), the
 .Dq no shared cipher
@@ -115,7 +358,7 @@ error is generated and the handshake will fail.
 .Fn SSL_CTX_set_cipher_list
 and
 .Fn SSL_set_cipher_list
-return 1 if any cipher could be selected and 0 on complete failure.
+return 1 if any cipher suite could be selected and 0 on complete failure.
 .Sh SEE ALSO
 .Xr ssl 3 ,
 .Xr SSL_CTX_set1_groups 3 ,