From: Frederik Wedel-Heinen Date: Thu, 12 Oct 2023 12:22:40 +0000 (+0200) Subject: Update documentation for DTLS1.3 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=5ae98099308ff3bb3fe24b145b7239964f269dcd;p=thirdparty%2Fopenssl.git Update documentation for DTLS1.3 Reviewed-by: Matt Caswell Reviewed-by: Tomas Mraz (Merged from https://github.com/openssl/openssl/pull/22363) --- diff --git a/doc/man1/openssl-s_client.pod.in b/doc/man1/openssl-s_client.pod.in index f79ef608d5b..cafa9718aec 100644 --- a/doc/man1/openssl-s_client.pod.in +++ b/doc/man1/openssl-s_client.pod.in @@ -365,7 +365,7 @@ See L for more information on the C scheme. A file containing a list of certificates whose subject names will be sent to the server in the B extension. Only supported -for TLS 1.3 +for TLS 1.3 and DTLS 1.3 =item B<-dane_tlsa_domain> I diff --git a/doc/man3/SSL_CIPHER_get_name.pod b/doc/man3/SSL_CIPHER_get_name.pod index 09b7280bdd5..cfd7ea5d503 100644 --- a/doc/man3/SSL_CIPHER_get_name.pod +++ b/doc/man3/SSL_CIPHER_get_name.pod @@ -74,7 +74,7 @@ different to the digest used to calculate the MAC for encrypted records. SSL_CIPHER_get_kx_nid() returns the key exchange NID corresponding to the method used by B. If there is no key exchange, then B is returned. -If any appropriate key exchange algorithm can be used (as in the case of TLS 1.3 +If any appropriate key exchange algorithm can be used (as in the case of (D)TLS 1.3 cipher suites) B is returned. Examples (not comprehensive): NID_kx_rsa @@ -85,7 +85,7 @@ cipher suites) B is returned. Examples (not comprehensive): SSL_CIPHER_get_auth_nid() returns the authentication NID corresponding to the method used by B. If there is no authentication, then B is returned. If any appropriate authentication algorithm can be used (as in the case of -TLS 1.3 cipher suites) B is returned. Examples (not comprehensive): +(D)TLS 1.3 cipher suites) B is returned. Examples (not comprehensive): NID_auth_rsa NID_auth_ecdsa diff --git a/doc/man3/SSL_CONF_cmd.pod b/doc/man3/SSL_CONF_cmd.pod index 32d10c3a5b3..5bd78b10ac0 100644 --- a/doc/man3/SSL_CONF_cmd.pod +++ b/doc/man3/SSL_CONF_cmd.pod @@ -351,7 +351,7 @@ if certificate operations are permitted. This option indicates a file containing a set of certificates in PEM form. The subject names of the certificates are sent to the peer in the -B extension for TLS 1.3 (in ClientHello or +B extension for (D)TLS 1.3 (in ClientHello or CertificateRequest) or in a certificate request for previous versions or TLS. diff --git a/doc/man3/SSL_CTX_set0_CA_list.pod b/doc/man3/SSL_CTX_set0_CA_list.pod index 64e8117f923..ce7ed0e6585 100644 --- a/doc/man3/SSL_CTX_set0_CA_list.pod +++ b/doc/man3/SSL_CTX_set0_CA_list.pod @@ -47,7 +47,7 @@ server to the client when requesting a client certificate. So any list of CA names set is never sent from client to server and the list of CA names retrieved by SSL_get0_peer_CA_list() is always B. -For TLS 1.3 the list of CA names is sent using the B +For (D)TLS 1.3 the list of CA names is sent using the B extension and may be sent by a client (in the ClientHello message) or by a server (when requesting a certificate). diff --git a/doc/man3/SSL_CTX_set1_sigalgs.pod b/doc/man3/SSL_CTX_set1_sigalgs.pod index c384065bfc7..468edebf9f6 100644 --- a/doc/man3/SSL_CTX_set1_sigalgs.pod +++ b/doc/man3/SSL_CTX_set1_sigalgs.pod @@ -32,7 +32,7 @@ SSL_CTX_set1_sigalgs_list() and SSL_set1_sigalgs_list() set the supported signature algorithms for B or B. The B parameter must be a null terminated string consisting of a colon separated list of elements, where each element is either a combination of a public key -algorithm and a digest separated by B<+>, or a TLS 1.3-style named +algorithm and a digest separated by B<+>, or a (D)TLS 1.3-style named SignatureScheme such as rsa_pss_pss_sha256. If a list entry is preceded with the C character, it will be ignored if an implementation is missing. @@ -80,7 +80,7 @@ The short or long name values for digests can be used in a string (for example "MD5", "SHA1", "SHA224", "SHA256", "SHA384", "SHA512") and the public key algorithm strings "RSA", "RSA-PSS", "DSA" or "ECDSA". -The TLS 1.3 signature scheme names (such as "rsa_pss_pss_sha256") can also +The (D)TLS 1.3 signature scheme names (such as "rsa_pss_pss_sha256") can also be used with the B<_list> forms of the API. The use of MD5 as a digest is strongly discouraged due to security weaknesses. diff --git a/doc/man3/SSL_CTX_set_min_proto_version.pod b/doc/man3/SSL_CTX_set_min_proto_version.pod index 9a2da37ab72..34b7a40cf3c 100644 --- a/doc/man3/SSL_CTX_set_min_proto_version.pod +++ b/doc/man3/SSL_CTX_set_min_proto_version.pod @@ -40,7 +40,7 @@ automatically use the lowest or highest version supported by the library. Currently supported versions are B, B, B, B, B for TLS and -B, B for DTLS. +B, B, B for DTLS. In the current version of OpenSSL only QUICv1 is supported in conjunction with TLSv1.3. Calling these functions on a QUIC object has no effect. diff --git a/doc/man3/SSL_CTX_set_num_tickets.pod b/doc/man3/SSL_CTX_set_num_tickets.pod index 0c7331bc6da..e81679e609a 100644 --- a/doc/man3/SSL_CTX_set_num_tickets.pod +++ b/doc/man3/SSL_CTX_set_num_tickets.pod @@ -46,7 +46,7 @@ To issue tickets after other events (such as application-layer changes), SSL_new_session_ticket() is used by a server application to request that a new ticket be sent when it is safe to do so. New tickets are only allowed to be sent in this manner after the initial handshake has completed, and only for -TLS 1.3 connections. By default, the ticket generation and transmission are +(D)TLS 1.3 connections. By default, the ticket generation and transmission are delayed until the server is starting a new write operation, so that it is bundled with other application data being written and properly aligned to a record boundary. If the connection was at a record boundary when diff --git a/doc/man3/SSL_CTX_set_options.pod b/doc/man3/SSL_CTX_set_options.pod index a6c922ecf92..dfe139065bc 100644 --- a/doc/man3/SSL_CTX_set_options.pod +++ b/doc/man3/SSL_CTX_set_options.pod @@ -296,10 +296,11 @@ When performing renegotiation as a server, always start a new session handshake). This option is not needed for clients. =item SSL_OP_NO_SSLv3, SSL_OP_NO_TLSv1, SSL_OP_NO_TLSv1_1, -SSL_OP_NO_TLSv1_2, SSL_OP_NO_TLSv1_3, SSL_OP_NO_DTLSv1, SSL_OP_NO_DTLSv1_2 +SSL_OP_NO_TLSv1_2, SSL_OP_NO_TLSv1_3, +SSL_OP_NO_DTLSv1, SSL_OP_NO_DTLSv1_2, SSL_OP_NO_DTLSv1_3 These options turn off the SSLv3, TLSv1, TLSv1.1, TLSv1.2 or TLSv1.3 protocol -versions with TLS or the DTLSv1, DTLSv1.2 versions with DTLS, +versions with TLS or the DTLSv1, DTLSv1.2, DTLSv1.3 versions with DTLS, respectively. As of OpenSSL 1.1.0, these options are deprecated, use L and diff --git a/doc/man3/SSL_check_chain.pod b/doc/man3/SSL_check_chain.pod index d00badbd753..e90ab0dd6fa 100644 --- a/doc/man3/SSL_check_chain.pod +++ b/doc/man3/SSL_check_chain.pod @@ -72,8 +72,8 @@ 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, -TLS 1.3 and DTLS 1.2 the results for earlier versions of TLS and DTLS may not +Since the supported signature algorithms extension is only used in (D)TLS 1.2 +and (D)TLS 1.3 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. diff --git a/doc/man3/SSL_export_keying_material.pod b/doc/man3/SSL_export_keying_material.pod index c7c5320295e..a0b54d70da2 100644 --- a/doc/man3/SSL_export_keying_material.pod +++ b/doc/man3/SSL_export_keying_material.pod @@ -31,7 +31,7 @@ accordance with RFC5705 (for TLSv1.2 and below) or RFC8446 (for TLSv1.3). SSL_export_keying_material() derives keying material using the F established in the handshake. -SSL_export_keying_material_early() is only usable with TLSv1.3, and derives +SSL_export_keying_material_early() is only usable with (D)TLSv1.3, and derives keying material using the F (as defined in the TLS 1.3 RFC). For the client, the F is only available when the client attempts to send 0-RTT data. For the server, it is diff --git a/doc/man3/SSL_get_shared_sigalgs.pod b/doc/man3/SSL_get_shared_sigalgs.pod index cb9ce025002..1dbf4226527 100644 --- a/doc/man3/SSL_get_shared_sigalgs.pod +++ b/doc/man3/SSL_get_shared_sigalgs.pod @@ -54,7 +54,7 @@ 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, TLS 1.3 and DTLS 1.2 currently support signature algorithms. +Only (D)TLS 1.2 and (D)TLS 1.3 currently support signature algorithms. If these functions are called on an earlier version of TLS or DTLS zero is returned. diff --git a/doc/man3/SSL_get_version.pod b/doc/man3/SSL_get_version.pod index b8a0f5e3b15..a6f5e7fb84b 100644 --- a/doc/man3/SSL_get_version.pod +++ b/doc/man3/SSL_get_version.pod @@ -125,6 +125,10 @@ The connection uses the DTLSv1 protocol The connection uses the DTLSv1.2 protocol +=item DTLS1_3_VERSION + +The connection uses the DTLSv1.3 protocol + =item OSSL_QUIC1_VERSION The connection uses the QUICv1 protocol.