[openssl-commits] [openssl] master update
yang.yang at baishancloud.com
yang.yang at baishancloud.com
Sat Sep 1 00:46:29 UTC 2018
The branch master has been updated
via 322755cc2a91d08b66826b38a7b8c20f68cd8890 (commit)
from 13da3ad00c80e1da816ca27f6c15b0ecee1bb0b8 (commit)
- Log -----------------------------------------------------------------
commit 322755cc2a91d08b66826b38a7b8c20f68cd8890
Author: Hubert Kario <hkario at redhat.com>
Date: Sat Sep 1 08:40:51 2018 +0800
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 at openssl.org>
Reviewed-by: Ben Kaduk <kaduk at mit.edu>
Reviewed-by: Paul Yang <yang.yang at baishancloud.com>
(Merged from https://github.com/openssl/openssl/pull/6939)
-----------------------------------------------------------------------
Summary of changes:
doc/man1/s_time.pod | 8 +--
doc/man1/sess_id.pod | 2 +-
doc/man3/SSL_CONF_cmd.pod | 80 +++++++++++++++++----------
doc/man3/SSL_CTX_new.pod | 7 ++-
doc/man3/SSL_CTX_set_cert_cb.pod | 6 +-
doc/man3/SSL_SESSION_get_protocol_version.pod | 2 +-
doc/man3/SSL_check_chain.pod | 6 +-
doc/man3/SSL_get_peer_signature_nid.pod | 4 +-
doc/man3/SSL_get_shared_sigalgs.pod | 8 ++-
doc/man7/ssl.pod | 2 +
10 files changed, 78 insertions(+), 47 deletions(-)
diff --git a/doc/man1/s_time.pod b/doc/man1/s_time.pod
index d17e137..c08e44a 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 0c0e7e8..99aa858 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 4edd49c..b399bcf 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 4bcbcca..29be37b 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 fbe4f2a..da084cb 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 22e40bd..5d6bb32 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 28c789e..dd9db40 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 66caa75..ac81b27 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 1309882..9de3f09 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 c1e4924..d439860 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);
More information about the openssl-commits
mailing list