Add documentation for TLSv1.3 ciphersuite configuration

Reviewed-by: Tim Hudson <tjh@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/5392)

doc/man1/ciphers.pod

@@ -22,6 +22,7 @@ B<openssl> B<ciphers>
 [B<-srp>]
 [B<-stdname>]
 [B<-convert name>]
+[B<-ciphersuites val>]
 [B<cipherlist>]
 
 =head1 DESCRIPTION
@@ -105,10 +106,21 @@ Precede each cipher suite by its standard name.
 
 Convert a standard cipher B<name> to its OpenSSL name.
 
+=item B<-ciphersuites val>
+
+Sets the list of TLSv1.3 ciphersuites. This list will be combined with any
+TLSv1.2 and below ciphersuites that have been configured. The format for this
+list is a simple colon (":") separated list of TLSv1.3 ciphersuite names. By
+default this value is:
+
+"TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256:TLS_AES_128_GCM_SHA256"
+
 =item B<cipherlist>
 
-A cipher list to convert to a cipher preference list. If it is not included
+A cipher list of TLSv1.2 and below ciphersuites to convert to a cipher
-then the default cipher list will be used. The format is described below.
+preference list. This list will be combined with any TLSv1.3 ciphersuites that
+have been configured. If it is not included then the default cipher list will be
+used. The format is described below.
 
 =back
 
@@ -705,11 +717,11 @@ Note: the CBC modes mentioned in this RFC are not supported.
 
 =head2 TLS v1.3 cipher suites
 
- TLS_AES_128_GCM_SHA256                     TLS13-AES-128-GCM-SHA256
+ TLS_AES_128_GCM_SHA256                     TLS_AES_128_GCM_SHA256
- TLS_AES_256_GCM_SHA384                     TLS13-AES-256-GCM-SHA384
+ TLS_AES_256_GCM_SHA384                     TLS_AES_256_GCM_SHA384
- TLS_CHACHA20_POLY1305_SHA256               TLS13-CHACHA20-POLY1305-SHA256
+ TLS_CHACHA20_POLY1305_SHA256               TLS_CHACHA20_POLY1305_SHA256
- TLS_AES_128_CCM_SHA256                     TLS13-AES-128-CCM-SHA256
+ TLS_AES_128_CCM_SHA256                     TLS_AES_128_CCM_SHA256
- TLS_AES_128_CCM_8_SHA256                   TLS13-AES-128-CCM-8-SHA256
+ TLS_AES_128_CCM_8_SHA256                   TLS_AES_128_CCM_8_SHA256
 
 =head2 Older names used by OpenSSL
 

doc/man1/s_client.pod

@@ -99,6 +99,7 @@ B<openssl> B<s_client>
 [B<-sigalgs sigalglist>]
 [B<-curves curvelist>]
 [B<-cipher cipherlist>]
+[B<-ciphersuites val>]
 [B<-serverpref>]
 [B<-starttls protocol>]
 [B<-xmpphost hostname>]
@@ -505,10 +506,20 @@ ultimately selected by the server. For a list of all curves, use:
 
 =item B<-cipher cipherlist>
 
-This allows the cipher list sent by the client to be modified. Although
+This allows the TLSv1.2 and below cipher list sent by the client to be modified.
-the server determines which cipher suite is used it should take the first
+This list will be combined with any TLSv1.3 ciphersuites that have been
-supported cipher in the list sent by the client. See the B<ciphers>
+configured. Although the server determines which ciphersuite is used it should
-command for more information.
+take the first supported cipher in the list sent by the client. See the
+B<ciphers> command for more information.
+
+=item B<-ciphersuites val>
+
+This allows the TLSv1.3 ciphersuites sent by the client to be modified. This
+list will be combined with any TLSv1.2 and below ciphersuites that have been
+configured. Although the server determines which cipher suite is used it should
+take the first supported cipher in the list sent by the client. See the
+B<ciphers> command for more information. The format for this list is a simple
+colon (":") separated list of TLSv1.3 ciphersuite names.
 
 =item B<-starttls protocol>
 

doc/man1/s_server.pod

@@ -113,6 +113,7 @@ B<openssl> B<s_server>
 [B<-curves val>]
 [B<-named_curve val>]
 [B<-cipher val>]
+[B<-ciphersuites val>]
 [B<-dhparam infile>]
 [B<-record_padding val>]
 [B<-debug_broken_protocol>]
@@ -533,12 +534,23 @@ For a list of all possible curves, use:
 
 =item B<-cipher val>
 
-This allows the cipher list used by the server to be modified.  When
+This allows the list of TLSv1.2 and below ciphersuites used by the server to be
-the client sends a list of supported ciphers the first client cipher
+modified. This list is combined with any TLSv1.3 ciphersuites that have been
-also included in the server list is used. Because the client specifies
+configured. When the client sends a list of supported ciphers the first client
-the preference order, the order of the server cipherlist irrelevant. See
+cipher also included in the server list is used. Because the client specifies
+the preference order, the order of the server cipherlist is irrelevant. See
 the B<ciphers> command for more information.
 
+=item B<-ciphersuites val>
+
+This allows the list of TLSv1.3 ciphersuites used by the server to be modified.
+This list is combined with any TLSv1.2 and below ciphersuites that have been
+configured. When the client sends a list of supported ciphers the first client
+cipher also included in the server list is used. Because the client specifies
+the preference order, the order of the server cipherlist is irrelevant. See
+the B<ciphers> command for more information. The format for this list is a
+simple colon (":") separated list of TLSv1.3 ciphersuite names.
+
 =item B<-dhparam infile>
 
 The DH parameter file to use. The ephemeral DH cipher suites generate keys

doc/man1/s_time.pod

@@ -25,6 +25,7 @@ B<openssl> B<s_time>
 [B<-ssl3>]
 [B<-bugs>]
 [B<-cipher cipherlist>]
+[B<-ciphersuites val>]
 
 =head1 DESCRIPTION
 
@@ -128,10 +129,20 @@ option enables various workarounds.
 
 =item B<-cipher cipherlist>
 
-This allows the cipher list sent by the client to be modified. Although
+This allows the TLSv1.2 and below cipher list sent by the client to be modified.
-the server determines which cipher suite is used it should take the first
+This list will be combined with any TLSv1.3 ciphersuites that have been
-supported cipher in the list sent by the client.
+configured. Although the server determines which cipher suite is used it should
-See the L<ciphers(1)> command for more information.
+take the first supported cipher in the list sent by the client. See the
+L<ciphers(1)> command for more information.
+
+=item B<-ciphersuites val>
+
+This allows the TLSv1.3 ciphersuites sent by the client to be modified. This
+list will be combined with any TLSv1.2 and below ciphersuites that have been
+configured. Although the server determines which cipher suite is used it should
+take the first supported cipher in the list sent by the client. See the
+B<ciphers> command for more information. The format for this list is a simple
+colon (":") separated list of TLSv1.3 ciphersuite names.
 
 =item B<-time length>
 

doc/man3/SSL_CONF_cmd.pod

@@ -89,10 +89,18 @@ can be either the B<NIST> name (e.g. B<P-256>) or an OpenSSL OID name
 
 =item B<-cipher>
 
-Sets the cipher suite list to B<value>. Note: syntax checking of B<value> is
+Sets the TLSv1.2 and below ciphersuite list to B<value>. This list will be
-currently not performed unless a B<SSL> or B<SSL_CTX> structure is
+combined with any configured TLSv1.3 ciphersuites. Note: syntax checking
+of B<value> is currently not performed unless a B<SSL> or B<SSL_CTX> structure is
 associated with B<cctx>.
 
+=item B<-ciphersuites>
+
+Sets the available ciphersuites for TLSv1.3 to value. This is a simple colon
+(":") separated list of TLSv1.3 ciphersuite names in order of preference. This
+list will be combined any configured TLSv1.2 and below ciphersuites.
+
+
 =item B<-cert>
 
 Attempts to use the file B<value> as the certificate for the appropriate
@@ -219,9 +227,16 @@ Note: the command prefix (if set) alters the recognised B<cmd> values.
 
 =item B<CipherString>
 
-Sets the cipher suite list to B<value>. Note: syntax checking of B<value> is
+Sets the ciphersuite list for TLSv1.2 and below to B<value>. This list will be
-currently not performed unless an B<SSL> or B<SSL_CTX> structure is
+combined with any configured TLSv1.3 ciphersuites. Note: syntax
-associated with B<cctx>.
+checking of B<value> is currently not performed unless an B<SSL> or B<SSL_CTX>
+structure is associated with B<cctx>.
+
+=item B<Ciphersuites>
+
+Sets the available ciphersuites for TLSv1.3 to B<value>. This is a simple colon
+(":") separated list of TLSv1.3 ciphersuite names in order of preference. This
+list will be combined any configured TLSv1.2 and below ciphersuites.
 
 =item B<Certificate>
 

doc/man3/SSL_CTX_set_cipher_list.pod

@@ -2,7 +2,11 @@
 
 =head1 NAME
 
-SSL_CTX_set_cipher_list, SSL_set_cipher_list - choose list of available SSL_CIPHERs
+SSL_CTX_set_cipher_list,
+SSL_set_cipher_list,
+SSL_CTX_set_ciphersuites,
+SSL_set_ciphersuites
+- choose list of available SSL_CIPHERs
 
 =head1 SYNOPSIS
 
@@ -11,18 +15,49 @@ SSL_CTX_set_cipher_list, SSL_set_cipher_list - choose list of available SSL_CIPH
  int SSL_CTX_set_cipher_list(SSL_CTX *ctx, const char *str);
  int SSL_set_cipher_list(SSL *ssl, const char *str);
 
+ int SSL_CTX_set_ciphersuites(SSL_CTX *ctx, const char *str);
+ int SSL_set_ciphersuites(SSL *s, const char *str);
+
 =head1 DESCRIPTION
 
-SSL_CTX_set_cipher_list() sets the list of available ciphers for B<ctx>
+SSL_CTX_set_cipher_list() sets the list of available ciphers (TLSv1.2 and below)
-using the control string B<str>. The format of the string is described
+for B<ctx> using the control string B<str>. The format of the string is described
 in L<ciphers(1)>. The list of ciphers is inherited by all
-B<ssl> objects created from B<ctx>.
+B<ssl> objects created from B<ctx>. This function does not impact TLSv1.3
+ciphersuites. Use SSL_CTX_set_ciphersuites() to configure those.
 
-SSL_set_cipher_list() sets the list of ciphers only for B<ssl>.
+SSL_set_cipher_list() sets the list of ciphers (TLSv1.2 and below) only for
+B<ssl>.
+
+SSL_CTX_set_ciphersuites() is used to configure the available TLSv1.3
+ciphersuites for B<ctx>. This is a simple colon (":") separated list of TLSv1.3
+ciphersuite names in order of perference. Valid TLSv1.3 ciphersuite names are:
+
+=over 4
+
+=item TLS_AES_128_GCM_SHA256
+
+=item TLS_AES_256_GCM_SHA384
+
+=item TLS_CHACHA20_POLY1305_SHA256
+
+=item TLS_AES_128_CCM_SHA256
+
+=item TLS_AES_128_CCM_8_SHA256
+
+=back
+
+An empty list is permissible. The default value for the this setting is:
+
+"TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256:TLS_AES_128_GCM_SHA256"
+
+SSL_set_ciphersuites() is the same as SSL_CTX_set_ciphersuites() except it
+configures the ciphersuites for B<ssl>.
 
 =head1 NOTES
 
-The control string B<str> should be universally usable and not depend
+The control string B<str> for SSL_CTX_set_cipher_list() and
+SSL_set_cipher_list() 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,
@@ -55,6 +90,9 @@ and the handshake will fail.
 SSL_CTX_set_cipher_list() and SSL_set_cipher_list() return 1 if any cipher
 could be selected and 0 on complete failure.
 
+SSL_CTX_set_ciphersuites() and SSL_set_ciphersuites() return 1 if the requested
+ciphersuite list was configured, and 0 otherwise.
+
 =head1 SEE ALSO
 
 L<ssl(7)>, L<SSL_get_ciphers(3)>,