Commit 9d2674cd authored by Matt Caswell's avatar Matt Caswell
Browse files

Add documentation for TLSv1.3 ciphersuite configuration 



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

doc/man1/ciphers.pod

+19 −7
Original line number Diff line number Diff line
@@ -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

then the default cipher list will be used. The format is described below.

A cipher list of TLSv1.2 and below ciphersuites to convert to a cipher

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_256_GCM_SHA384                     TLS13-AES-256-GCM-SHA384

 TLS_CHACHA20_POLY1305_SHA256               TLS13-CHACHA20-POLY1305-SHA256

 TLS_AES_128_CCM_SHA256                     TLS13-AES-128-CCM-SHA256

 TLS_AES_128_CCM_8_SHA256                   TLS13-AES-128-CCM-8-SHA256

 TLS_AES_128_GCM_SHA256                     TLS_AES_128_GCM_SHA256

 TLS_AES_256_GCM_SHA384                     TLS_AES_256_GCM_SHA384

 TLS_CHACHA20_POLY1305_SHA256               TLS_CHACHA20_POLY1305_SHA256

 TLS_AES_128_CCM_SHA256                     TLS_AES_128_CCM_SHA256

 TLS_AES_128_CCM_8_SHA256                   TLS_AES_128_CCM_8_SHA256



=head2 Older names used by OpenSSL

doc/man1/s_client.pod

+15 −4
Original line number Diff line number Diff line
@@ -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

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.

This allows the TLSv1.2 and below cipher list sent by the client to be modified.

This list will be combined with any TLSv1.3 ciphersuites that have been

configured. Although the server determines which ciphersuite is used it should

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

+16 −4
Original line number Diff line number Diff line
@@ -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

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 irrelevant. See

This allows the list of TLSv1.2 and below ciphersuites used by the server to be

modified. This list is combined with any TLSv1.3 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.



=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

+15 −4
Original line number Diff line number Diff line
@@ -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

the server determines which cipher suite is used it should take the first

supported cipher in the list sent by the client.

See the L<ciphers(1)> command for more information.

This allows the TLSv1.2 and below cipher list sent by the client to be modified.

This list will be combined with any TLSv1.3 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

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

+20 −5
Original line number Diff line number Diff line
@@ -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

currently not performed unless a B<SSL> or B<SSL_CTX> structure is

Sets the TLSv1.2 and below ciphersuite list to B<value>. This list will be

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

currently not performed unless an B<SSL> or B<SSL_CTX> structure is

associated with B<cctx>.

Sets the ciphersuite list for TLSv1.2 and below to B<value>. This list will be

combined with any configured TLSv1.3 ciphersuites. Note: syntax

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>