Constify various mostly X509-related parameter types in crypto/ and apps/

[oweals/openssl.git] / doc / man3 / SSL_read_early_data.pod

diff --git a/doc/man3/SSL_read_early_data.pod b/doc/man3/SSL_read_early_data.pod
index 27c127d397a4ab17b9f888e8a4d2a29cd32b64a5..4f1593638c4b1d5137ca972b995e80af3eb27427 100644 (file)
--- a/doc/man3/SSL_read_early_data.pod
+++ b/doc/man3/SSL_read_early_data.pod
@@ -65,7 +65,7 @@ yet completed the authentication stage of the handshake.
 
 Early data has weaker security properties than other data sent over an SSL/TLS
 connection. In particular the data does not have forward secrecy. There are also
 
 Early data has weaker security properties than other data sent over an SSL/TLS
 connection. In particular the data does not have forward secrecy. There are also

-additional considerations around replay attacks (see L<REPLAY PROTECTION>
+additional considerations around replay attacks (see L</REPLAY PROTECTION>

 below). For these reasons extreme care should be exercised when using early
 data. For specific details, consult the TLS 1.3 specification.
 
 below). For these reasons extreme care should be exercised when using early
 data. For specific details, consult the TLS 1.3 specification.
 


@@ -93,7 +93,7 @@ the server.
 A client uses the function SSL_write_early_data() to send early data. This
 function is similar to the L<SSL_write_ex(3)> function, but with the following
 differences. See L<SSL_write_ex(3)> for information on how to write bytes to
 A client uses the function SSL_write_early_data() to send early data. This
 function is similar to the L<SSL_write_ex(3)> function, but with the following
 differences. See L<SSL_write_ex(3)> for information on how to write bytes to

-the underlying connection, and how to handle any errors that may arise. This 
+the underlying connection, and how to handle any errors that may arise. This

 page describes the differences between SSL_write_early_data() and
 L<SSL_write_ex(3)>.
 
 page describes the differences between SSL_write_early_data() and
 L<SSL_write_ex(3)>.
 


@@ -202,7 +202,7 @@ early data settings for the SSL_CTX and SSL objects respectively. Generally a
 server application will either use both of SSL_read_early_data() and
 SSL_CTX_set_max_early_data() (or SSL_set_max_early_data()), or neither of them,
 since there is no practical benefit from using only one of them. If the maximum
 server application will either use both of SSL_read_early_data() and
 SSL_CTX_set_max_early_data() (or SSL_set_max_early_data()), or neither of them,
 since there is no practical benefit from using only one of them. If the maximum

-early data setting for a server is non-zero then replay protection is
+early data setting for a server is nonzero then replay protection is

 automatically enabled (see L</REPLAY PROTECTION> below).
 
 If the server rejects the early data sent by a client then it will skip over
 automatically enabled (see L</REPLAY PROTECTION> below).
 
 If the server rejects the early data sent by a client then it will skip over


@@ -267,12 +267,25 @@ Nagle's algorithm. If an application opts to disable Nagle's algorithm
 consideration should be given to turning it back on again after the handshake is
 complete if appropriate.
 
 consideration should be given to turning it back on again after the handshake is
 complete if appropriate.
 

+In rare circumstances, it may be possible for a client to have a session that
+reports a max early data value greater than 0, but where the server does not
+support this. For example, this can occur if a server has had its configuration
+changed to accept a lower max early data value such as by calling
+SSL_CTX_set_recv_max_early_data(). Another example is if a server used to
+support TLSv1.3 but was later downgraded to TLSv1.2. Sending early data to such
+a server will cause the connection to abort. Clients that encounter an aborted
+connection while sending early data may want to retry the connection without
+sending early data as this does not happen automatically. A client will have to
+establish a new transport layer connection to the server and attempt the SSL/TLS
+connection again but without sending early data. Note that it is inadvisable to
+retry with a lower maximum protocol version.
+

 =head1 REPLAY PROTECTION
 
 When early data is in use the TLS protocol provides no security guarantees that
 the same early data was not replayed across multiple connections. As a
 mitigation for this issue OpenSSL automatically enables replay protection if the
 =head1 REPLAY PROTECTION
 
 When early data is in use the TLS protocol provides no security guarantees that
 the same early data was not replayed across multiple connections. As a
 mitigation for this issue OpenSSL automatically enables replay protection if the

-server is configured with a non-zero max early data value. With replay
+server is configured with a nonzero max early data value. With replay

 protection enabled sessions are forced to be single use only. If a client
 attempts to reuse a session ticket more than once, then the second and
 subsequent attempts will fall back to a full handshake (and any early data that
 protection enabled sessions are forced to be single use only. If a client
 attempts to reuse a session ticket more than once, then the second and
 subsequent attempts will fall back to a full handshake (and any early data that


@@ -353,7 +366,7 @@ All of the functions described above were added in OpenSSL 1.1.1.
 
 Copyright 2017-2018 The OpenSSL Project Authors. All Rights Reserved.
 
 
 Copyright 2017-2018 The OpenSSL Project Authors. All Rights Reserved.
 

-Licensed under the OpenSSL license (the "License").  You may not use
+Licensed under the Apache License 2.0 (the "License").  You may not use

 this file except in compliance with the License.  You can obtain a copy
 in the file LICENSE in the source distribution or at
 L<https://www.openssl.org/source/license.html>.
 this file except in compliance with the License.  You can obtain a copy
 in the file LICENSE in the source distribution or at
 L<https://www.openssl.org/source/license.html>.