wbrawner/openssl
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

TLSv1.3 related changes to man pages

Browse source 
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)
This commit is contained in:
Hubert Kario 2018-09-01 08:40:51 +08:00 committed by Paul Yang
parent 13da3ad00c
commit 322755cc2a
10 changed files with 78 additions and 47 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

8
doc/man1/s_time.pod
View file

@ -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>

2
doc/man1/sess_id.pod
View file

@ -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>

80
doc/man3/SSL_CONF_cmd.pod
View file

@ -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>

7
doc/man3/SSL_CTX_new.pod
View file

@ -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

6
doc/man3/SSL_CTX_set_cert_cb.pod
View file

@ -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

2
doc/man3/SSL_SESSION_get_protocol_version.pod
View file

@ -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.

6
doc/man3/SSL_check_chain.pod
View file

@ -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

4
doc/man3/SSL_get_peer_signature_nid.pod
View file

@ -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

8
doc/man3/SSL_get_shared_sigalgs.pod
View file

@ -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

2
doc/man7/ssl.pod
View file

@ -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);