TLSv1.3 related changes to man pages

Add or update the documentation of the different man pages in relation to TLSv1.3 behaviour.

Reviewed-by: Tim Hudson <tjh@openssl.org>
Reviewed-by: Ben Kaduk <kaduk@mit.edu>
Reviewed-by: Paul Yang <yang.yang@baishancloud.com>
(Merged from https://github.com/openssl/openssl/pull/6939)

10 files changed, 78 insertions, 47 deletions

diff --git a/doc/man1/s_time.pod b/doc/man1/s_time.pod
index d17e13728e..c08e44a431 100644
--- a/doc/man1/s_time.pod
+++ b/doc/man1/s_time.pod
@@ -135,16 +135,16 @@ option enables various workarounds.
 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.
+take the first supported cipher in the list sent by the client. See
+L<ciphers(1)> 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
+take the first supported cipher in the list sent by the client. See
+L<ciphers(1)> for more information. The format for this list is a simple
 colon (":") separated list of TLSv1.3 ciphersuite names.
 
 =item B<-time length>
diff --git a/doc/man1/sess_id.pod b/doc/man1/sess_id.pod
index 0c0e7e8ae9..99aa85820c 100644
--- a/doc/man1/sess_id.pod
+++ b/doc/man1/sess_id.pod
@@ -99,7 +99,7 @@ Theses are described below in more detail.
 
 =item B<Protocol>
 
-This is the protocol in use TLSv1.2, TLSv1.1, TLSv1 or SSLv3.
+This is the protocol in use TLSv1.3, TLSv1.2, TLSv1.1, TLSv1 or SSLv3.
 
 =item B<Cipher>
 
diff --git a/doc/man3/SSL_CONF_cmd.pod b/doc/man3/SSL_CONF_cmd.pod
index 4edd49ca0b..b399bcf499 100644
--- a/doc/man3/SSL_CONF_cmd.pod
+++ b/doc/man3/SSL_CONF_cmd.pod
@@ -33,25 +33,36 @@ prefix for command line commands is B<-> and that is reflected below.
 
 =item B<-sigalgs>
 
-This sets the supported signature algorithms for TLS v1.2. For clients this
+This sets the supported signature algorithms for TLSv1.2 and TLSv1.3.
+For clients this
 value is used directly for the supported signature algorithms extension. For
 servers it is used to determine which signature algorithms to support.
 
 The B<value> argument should be a colon separated list of signature algorithms
-in order of decreasing preference of the form B<algorithm+hash>. B<algorithm>
+in order of decreasing preference of the form B<algorithm+hash> or
+B<signature_scheme>. B<algorithm>
 is one of B<RSA>, B<DSA> or B<ECDSA> and B<hash> is a supported algorithm
 OID short name such as B<SHA1>, B<SHA224>, B<SHA256>, B<SHA384> of B<SHA512>.
 Note: algorithm and hash names are case sensitive.
+B<signature_scheme> is one of the signature schemes defined in TLSv1.3,
+specified using the IETF name, e.g., B<ecdsa_secp256r1_sha256>, B<ed25519>,
+or B<rsa_pss_pss_sha256>.
 
 If this option is not set then all signature algorithms supported by the
 OpenSSL library are permissible.
 
+Note: algorithms which specify a PKCS#1 v1.5 signature scheme (either by
+using B<RSA> as the B<algorithm> or by using one of the B<rsa_pkcs1_*>
+identifiers) are ignored in TLSv1.3 and will not be negotiated.
+
 =item B<-client_sigalgs>
 
 This sets the supported signature algorithms associated with client
-authentication for TLS v1.2. For servers the value is used in the supported
-signature algorithms field of a certificate request. For clients it is
-used to determine which signature algorithm to with the client certificate.
+authentication for TLSv1.2 and TLSv1.3.
+For servers the value is used in the
+B<signature_algorithms> field of a B<CertificateRequest> message.
+For clients it is
+used to determine which signature algorithm to use with the client certificate.
 If a server does not request a certificate this option has no effect.
 
 The syntax of B<value> is identical to B<-sigalgs>. If not set then
@@ -61,22 +72,21 @@ the value set for B<-sigalgs> will be used instead.
 
 This sets the supported groups. For clients, the groups are
 sent using the supported groups extension. For servers, it is used
-to determine which group to use. This setting affects groups used for both
-signatures and key exchange, if applicable. It also affects the preferred
-key_share sent by a client in a TLSv1.3 compatible connection.
+to determine which group to use. This setting affects groups used for
+signatures (in TLSv1.2 and earlier) and key exchange. The first group listed
+will also be used for the B<key_share> sent by a client in a TLSv1.3
+B<ClientHello>.
 
 The B<value> argument is a colon separated list of groups. The group can be
 either the B<NIST> name (e.g. B<P-256>), some other commonly used name where
 applicable (e.g. B<X25519>) or an OpenSSL OID name (e.g B<prime256v1>). Group
 names are case sensitive. The list should be in order of preference with the
-most preferred group first. The first listed group will be the one used for a
-key_share by a TLSv1.3 client.
+most preferred group first.
 
 =item B<-curves>
 
 This is a synonym for the "-groups" command.
 
-
 =item B<-named_curve>
 
 This sets the temporary curve used for ephemeral ECDH modes. Only used by
@@ -99,6 +109,7 @@ associated with B<cctx>.
 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.
+See L<ciphers(1)> for more information.
 
 
 =item B<-cert>
@@ -124,7 +135,7 @@ operations are permitted.
 
 =item B<-record_padding>
 
-Attempts to pad TLS 1.3 records so that they are a multiple of B<value> in
+Attempts to pad TLSv1.3 records so that they are a multiple of B<value> in
 length on send. A B<value> of 0 or 1 turns off padding. Otherwise, the
 B<value> must be >1 or <=16384.
 
@@ -137,9 +148,9 @@ B<SSL_OP_NO_RENEGOTIATION>.
 
 Sets the minimum and maximum supported protocol.
 Currently supported protocol values are B<SSLv3>, B<TLSv1>,
-B<TLSv1.1>, B<TLSv1.2> for TLS and B<DTLSv1>, B<DTLSv1.2> for DTLS,
+B<TLSv1.1>, B<TLSv1.2>, B<TLSv1.3> for TLS and B<DTLSv1>, B<DTLSv1.2> for DTLS,
 and B<None> for no limit.
-If the either bound is not specified then only the other bound applies,
+If either bound is not specified then only the other bound applies,
 if specified.
 To restrict the supported protocol versions use these commands rather
 than the deprecated alternative commands below.
@@ -249,6 +260,7 @@ structure is associated with B<cctx>.
 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.
+See L<ciphers(1)> for more information.
 
 =item B<Certificate>
 
@@ -292,7 +304,7 @@ operations are permitted.
 
 =item B<RecordPadding>
 
-Attempts to pad TLS 1.3 records so that they are a multiple of B<value> in
+Attempts to pad TLSv1.3 records so that they are a multiple of B<value> in
 length on send. A B<value> of 0 or 1 turns off padding. Otherwise, the
 B<value> must be >1 or <=16384.
 
@@ -303,25 +315,37 @@ B<SSL_OP_NO_RENEGOTIATION>.
 
 =item B<SignatureAlgorithms>
 
-This sets the supported signature algorithms for TLS v1.2. For clients this
+This sets the supported signature algorithms for TLSv1.2 and TLSv1.3.
+For clients this
 value is used directly for the supported signature algorithms extension. For
 servers it is used to determine which signature algorithms to support.
 
 The B<value> argument should be a colon separated list of signature algorithms
-in order of decreasing preference of the form B<algorithm+hash>. B<algorithm>
+in order of decreasing preference of the form B<algorithm+hash> or
+B<signature_scheme>. B<algorithm>
 is one of B<RSA>, B<DSA> or B<ECDSA> and B<hash> is a supported algorithm
 OID short name such as B<SHA1>, B<SHA224>, B<SHA256>, B<SHA384> of B<SHA512>.
 Note: algorithm and hash names are case sensitive.
+B<signature_scheme> is one of the signature schemes defined in TLSv1.3,
+specified using the IETF name, e.g., B<ecdsa_secp256r1_sha256>, B<ed25519>,
+or B<rsa_pss_pss_sha256>.
 
 If this option is not set then all signature algorithms supported by the
 OpenSSL library are permissible.
 
+Note: algorithms which specify a PKCS#1 v1.5 signature scheme (either by
+using B<RSA> as the B<algorithm> or by using one of the B<rsa_pkcs1_*>
+identifiers) are ignored in TLSv1.3 and will not be negotiated.
+
 =item B<ClientSignatureAlgorithms>
 
 This sets the supported signature algorithms associated with client
-authentication for TLS v1.2. For servers the value is used in the supported
-signature algorithms field of a certificate request. For clients it is
-used to determine which signature algorithm to with the client certificate.
+authentication for TLSv1.2 and TLSv1.3.
+For servers the value is used in the
+B<signature_algorithms> field of a B<CertificateRequest> message.
+For clients it is
+used to determine which signature algorithm to use with the client certificate.
+If a server does not request a certificate this option has no effect.
 
 The syntax of B<value> is identical to B<SignatureAlgorithms>. If not set then
 the value set for B<SignatureAlgorithms> will be used instead.
@@ -330,16 +354,16 @@ the value set for B<SignatureAlgorithms> will be used instead.
 
 This sets the supported groups. For clients, the groups are
 sent using the supported groups extension. For servers, it is used
-to determine which group to use. This setting affects groups used for both
-signatures and key exchange, if applicable. It also affects the preferred
-key_share sent by a client in a TLSv1.3 compatible connection.
+to determine which group to use. This setting affects groups used for
+signatures (in TLSv1.2 and earlier) and key exchange. The first group listed
+will also be used for the B<key_share> sent by a client in a TLSv1.3
+B<ClientHello>.
 
 The B<value> argument is a colon separated list of groups. The group can be
 either the B<NIST> name (e.g. B<P-256>), some other commonly used name where
 applicable (e.g. B<X25519>) or an OpenSSL OID name (e.g B<prime256v1>). Group
 names are case sensitive. The list should be in order of preference with the
-most preferred group first. The first listed group will be the one used for a
-key_share by a TLSv1.3 client.
+most preferred group first.
 
 =item B<Curves>
 
@@ -350,7 +374,7 @@ This is a synonym for the "Groups" command.
 This sets the minimum supported SSL, TLS or DTLS version.
 
 Currently supported protocol values are B<SSLv3>, B<TLSv1>, B<TLSv1.1>,
-B<TLSv1.2>, B<DTLSv1> and B<DTLSv1.2>.
+B<TLSv1.2>, B<TLSv1.3>, B<DTLSv1> and B<DTLSv1.2>.
 The value B<None> will disable the limit.
 
 =item B<MaxProtocol>
@@ -358,7 +382,7 @@ The value B<None> will disable the limit.
 This sets the maximum supported SSL, TLS or DTLS version.
 
 Currently supported protocol values are B<SSLv3>, B<TLSv1>, B<TLSv1.1>,
-B<TLSv1.2>, B<DTLSv1> and B<DTLSv1.2>.
+B<TLSv1.2>, B<TLSv1.3>, B<DTLSv1> and B<DTLSv1.2>.
 The value B<None> will disable the limit.
 
 =item B<Protocol>
@@ -377,7 +401,7 @@ Only enabling some protocol versions does not disable the other protocol
 versions.
 
 Currently supported protocol values are B<SSLv3>, B<TLSv1>, B<TLSv1.1>,
-B<TLSv1.2>, B<DTLSv1> and B<DTLSv1.2>.
+B<TLSv1.2>, B<TLSv1.3>, B<DTLSv1> and B<DTLSv1.2>.
 The special value B<ALL> refers to all supported versions.
 
 This can't enable protocols that are disabled using B<MinProtocol>
diff --git a/doc/man3/SSL_CTX_new.pod b/doc/man3/SSL_CTX_new.pod
index 4bcbccaf9d..29be37b85a 100644
--- a/doc/man3/SSL_CTX_new.pod
+++ b/doc/man3/SSL_CTX_new.pod
@@ -92,7 +92,7 @@ B<method> can be of the following types:
 These are the general-purpose I<version-flexible> SSL/TLS methods.
 The actual protocol version used will be negotiated to the highest version
 mutually supported by the client and the server.
-The supported protocols are SSLv3, TLSv1, TLSv1.1 and TLSv1.2.
+The supported protocols are SSLv3, TLSv1, TLSv1.1, TLSv1.2 and TLSv1.3.
 Applications should use these methods, and avoid the version-specific
 methods described below.
 
@@ -153,11 +153,12 @@ L<SSL_set_min_proto_version(3)>, L<SSL_CTX_set_max_proto_version(3)> and
 L<SSL_set_max_proto_version(3)> functions.
 Using these functions it is possible to choose e.g. TLS_server_method()
 and be able to negotiate with all possible clients, but to only
-allow newer protocols like TLS 1.0, TLS 1.1 or TLS 1.2.
+allow newer protocols like TLS 1.0, TLS 1.1, TLS 1.2 or TLS 1.3.
 
 The list of protocols available can also be limited using the
 B<SSL_OP_NO_SSLv3>, B<SSL_OP_NO_TLSv1>, B<SSL_OP_NO_TLSv1_1>,
-B<SSL_OP_NO_TLSv1_3> and B<SSL_OP_NO_TLSv1_2> options of the
+B<SSL_OP_NO_TLSv1_3>, B<SSL_OP_NO_TLSv1_2> and B<SSL_OP_NO_TLSv1_3>
+options of the
 L<SSL_CTX_set_options(3)> or L<SSL_set_options(3)> functions, but this approach
 is not recommended. Clients should avoid creating "holes" in the set of
 protocols they support. When disabling a protocol, make sure that you also
diff --git a/doc/man3/SSL_CTX_set_cert_cb.pod b/doc/man3/SSL_CTX_set_cert_cb.pod
index fbe4f2ac24..da084cb1f4 100644
--- a/doc/man3/SSL_CTX_set_cert_cb.pod
+++ b/doc/man3/SSL_CTX_set_cert_cb.pod
@@ -51,9 +51,9 @@ can modify or delete the existing certificate.
 
 A more advanced callback might examine the handshake parameters and set
 whatever chain is appropriate. For example a legacy client supporting only
-TLS v1.0 might receive a certificate chain signed using SHA1 whereas a
-TLS v1.2 client which advertises support for SHA256 could receive a chain
-using SHA256.
+TLSv1.0 might receive a certificate chain signed using SHA1 whereas a
+TLSv1.2 or later client which advertises support for SHA256 could receive a
+chain using SHA256.
 
 Normal server sanity checks are performed on any certificates set
 by the callback. So if an EC chain is set for a curve the client does not
diff --git a/doc/man3/SSL_SESSION_get_protocol_version.pod b/doc/man3/SSL_SESSION_get_protocol_version.pod
index 22e40bd643..5d6bb32f59 100644
--- a/doc/man3/SSL_SESSION_get_protocol_version.pod
+++ b/doc/man3/SSL_SESSION_get_protocol_version.pod
@@ -27,7 +27,7 @@ up a session based PSK (see L<SSL_CTX_set_psk_use_session_callback(3)>).
 
 SSL_SESSION_get_protocol_version() returns a number indicating the protocol
 version used for the session; this number matches the constants I<e.g.>
-B<TLS1_VERSION> or B<TLS1_2_VERSION>.
+B<TLS1_VERSION>, B<TLS1_2_VERSION> or B<TLS1_3_VERSION>.
 
 Note that the SSL_SESSION_get_protocol_version() function
 does B<not> perform a null check on the provided session B<s> pointer.
diff --git a/doc/man3/SSL_check_chain.pod b/doc/man3/SSL_check_chain.pod
index 28c789e92e..dd9db40c79 100644
--- a/doc/man3/SSL_check_chain.pod
+++ b/doc/man3/SSL_check_chain.pod
@@ -72,9 +72,9 @@ The validity of a chain is determined by checking if it matches a supported
 signature algorithm, supported curves and in the case of client authentication
 certificate types and issuer names.
 
-Since the supported signature algorithms extension is only used in TLS 1.2
-and DTLS 1.2 the results for earlier versions of TLS and DTLS may not be
-very useful. Applications may wish to specify a different "legacy" chain
+Since the supported signature algorithms extension is only used in TLS 1.2,
+TLS 1.3 and DTLS 1.2 the results for earlier versions of TLS and DTLS may not
+be very useful. Applications may wish to specify a different "legacy" chain
 for earlier versions of TLS or DTLS.
 
 =head1 SEE ALSO
diff --git a/doc/man3/SSL_get_peer_signature_nid.pod b/doc/man3/SSL_get_peer_signature_nid.pod
index 66caa75a92..ac81b27fc7 100644
--- a/doc/man3/SSL_get_peer_signature_nid.pod
+++ b/doc/man3/SSL_get_peer_signature_nid.pod
@@ -20,7 +20,9 @@ by the peer to sign TLS messages. It is implemented as a macro.
 SSL_get_peer_signature_type_nid() sets B<*psigtype_nid> to the signature
 type used by the peer to sign TLS messages. Currently the signature type
 is the NID of the public key type used for signing except for PSS signing
-where it is B<EVP_PKEY_RSA_PSS>.
+where it is B<EVP_PKEY_RSA_PSS>. To differentiate between
+B<rsa_pss_rsae_*> and B<rsa_pss_pss_*> signatures, it's necessary to check
+the type of public key in the peer's certificate.
 
 =head1 RETURN VALUES
 
diff --git a/doc/man3/SSL_get_shared_sigalgs.pod b/doc/man3/SSL_get_shared_sigalgs.pod
index 1309882dc7..9de3f0946f 100644
--- a/doc/man3/SSL_get_shared_sigalgs.pod
+++ b/doc/man3/SSL_get_shared_sigalgs.pod
@@ -54,7 +54,8 @@ signature algorithms: after a client hello (for servers) or a certificate
 request (for clients). They can (for example) be called in the certificate
 callback.
 
-Only TLS 1.2 and DTLS 1.2 currently support signature algorithms. If these
+Only TLS 1.2, TLS 1.3 and DTLS 1.2 currently support signature algorithms.
+If these
 functions are called on an earlier version of TLS or DTLS zero is returned.
 
 The shared signature algorithms returned by SSL_get_shared_sigalgs() are
@@ -66,8 +67,9 @@ rsa(1) then B<*rhash> would be 4, B<*rsign> 1, B<*phash> NID_sha256, B<*psig>
 NID_rsaEncryption and B<*psighash> NID_sha256WithRSAEncryption.
 
 If a signature algorithm is not recognised the corresponding NIDs
-will be set to B<NID_undef>. This may be because the value is not supported
-or is not an appropriate combination (for example MD5 and DSA).
+will be set to B<NID_undef>. This may be because the value is not supported,
+is not an appropriate combination (for example MD5 and DSA) or the
+signature algorithm does not use a hash (for example Ed25519).
 
 =head1 SEE ALSO
 
diff --git a/doc/man7/ssl.pod b/doc/man7/ssl.pod
index c1e4924964..d439860b5b 100644
--- a/doc/man7/ssl.pod
+++ b/doc/man7/ssl.pod
@@ -128,10 +128,12 @@ See L<SSL_CTX_new(3)> for details.
 =item const SSL_METHOD *B<TLS_client_method>(void);
 
 Constructor for the I<version-flexible> SSL_METHOD structure for clients.
+Must be used to support the TLSv1.3 protocol.
 
 =item const SSL_METHOD *B<TLS_server_method>(void);
 
 Constructor for the I<version-flexible> SSL_METHOD structure for servers.
+Must be used to support the TLSv1.3 protocol.
 
 =item const SSL_METHOD *B<TLSv1_2_method>(void);