From 322755cc2a91d08b66826b38a7b8c20f68cd8890 Mon Sep 17 00:00:00 2001 From: Hubert Kario Date: Sat, 1 Sep 2018 08:40:51 +0800 Subject: 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 Reviewed-by: Ben Kaduk Reviewed-by: Paul Yang (Merged from https://github.com/openssl/openssl/pull/6939) --- 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(-) (limited to 'doc') 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 command for more information. +take the first supported cipher in the list sent by the client. See +L 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 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 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 -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 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 argument should be a colon separated list of signature algorithms -in order of decreasing preference of the form B. B +in order of decreasing preference of the form B or +B. B is one of B, B or B and B is a supported algorithm OID short name such as B, B, B, B of B. Note: algorithm and hash names are case sensitive. +B is one of the signature schemes defined in TLSv1.3, +specified using the IETF name, e.g., B, B, +or B. 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 as the B or by using one of the B +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 field of a B 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 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 sent by a client in a TLSv1.3 +B. The B argument is a colon separated list of groups. The group can be either the B name (e.g. B), some other commonly used name where applicable (e.g. B) or an OpenSSL OID name (e.g B). 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. 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 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 in +Attempts to pad TLSv1.3 records so that they are a multiple of B in length on send. A B of 0 or 1 turns off padding. Otherwise, the B must be >1 or <=16384. @@ -137,9 +148,9 @@ B. Sets the minimum and maximum supported protocol. Currently supported protocol values are B, B, -B, B for TLS and B, B for DTLS, +B, B, B for TLS and B, B for DTLS, and B 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. Sets the available ciphersuites for TLSv1.3 to B. 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 for more information. =item B @@ -292,7 +304,7 @@ operations are permitted. =item B -Attempts to pad TLS 1.3 records so that they are a multiple of B in +Attempts to pad TLSv1.3 records so that they are a multiple of B in length on send. A B of 0 or 1 turns off padding. Otherwise, the B must be >1 or <=16384. @@ -303,25 +315,37 @@ B. =item B -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 argument should be a colon separated list of signature algorithms -in order of decreasing preference of the form B. B +in order of decreasing preference of the form B or +B. B is one of B, B or B and B is a supported algorithm OID short name such as B, B, B, B of B. Note: algorithm and hash names are case sensitive. +B is one of the signature schemes defined in TLSv1.3, +specified using the IETF name, e.g., B, B, +or B. 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 as the B or by using one of the B +identifiers) are ignored in TLSv1.3 and will not be negotiated. + =item B 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 field of a B 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 is identical to B. If not set then the value set for B will be used instead. @@ -330,16 +354,16 @@ the value set for B 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 sent by a client in a TLSv1.3 +B. The B argument is a colon separated list of groups. The group can be either the B name (e.g. B), some other commonly used name where applicable (e.g. B) or an OpenSSL OID name (e.g B). 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 @@ -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, B, B, -B, B and B. +B, B, B and B. The value B will disable the limit. =item B @@ -358,7 +382,7 @@ The value B will disable the limit. This sets the maximum supported SSL, TLS or DTLS version. Currently supported protocol values are B, B, B, -B, B and B. +B, B, B and B. The value B will disable the limit. =item B @@ -377,7 +401,7 @@ Only enabling some protocol versions does not disable the other protocol versions. Currently supported protocol values are B, B, B, -B, B and B. +B, B, B and B. The special value B refers to all supported versions. This can't enable protocols that are disabled using B 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 can be of the following types: These are the general-purpose I 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, L and L 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, B, B, -B and B options of the +B, B and B +options of the L or L 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_SESSION_get_protocol_version() returns a number indicating the protocol version used for the session; this number matches the constants I -B or B. +B, B or B. Note that the SSL_SESSION_get_protocol_version() function does B perform a null check on the provided session B 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. +where it is B. To differentiate between +B and B 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. 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. 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 for details. =item const SSL_METHOD *B(void); Constructor for the I SSL_METHOD structure for clients. +Must be used to support the TLSv1.3 protocol. =item const SSL_METHOD *B(void); Constructor for the I SSL_METHOD structure for servers. +Must be used to support the TLSv1.3 protocol. =item const SSL_METHOD *B(void); -- cgit v1.2.3