MFC: r356963

Install man5 and man7 for OpenSSL.

1 files changed, 480 insertions, 0 deletions

diff --git a/secure/lib/libcrypto/man/man3/SSL_read_early_data.3 b/secure/lib/libcrypto/man/man3/SSL_read_early_data.3
new file mode 100644
index 000000000000..d2c487130cb1
--- /dev/null
+++ b/secure/lib/libcrypto/man/man3/SSL_read_early_data.3
@@ -0,0 +1,480 @@
+.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.39)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" Set up some character translations and predefined strings.  \*(-- will
+.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
+.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
+.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
+.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
+.\" nothing in troff, for use with C<>.
+.tr \(*W-
+.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
+.ie n \{\
+.    ds -- \(*W-
+.    ds PI pi
+.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
+.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
+.    ds L" ""
+.    ds R" ""
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds -- \|\(em\|
+.    ds PI \(*p
+.    ds L" ``
+.    ds R" ''
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\"
+.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
+.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
+.    \" fudge factors for nroff and troff
+.if n \{\
+.    ds #H 0
+.    ds #V .8m
+.    ds #F .3m
+.    ds #[ \f1
+.    ds #] \fP
+.\}
+.if t \{\
+.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
+.    ds #V .6m
+.    ds #F 0
+.    ds #[ \&
+.    ds #] \&
+.\}
+.    \" simple accents for nroff and troff
+.if n \{\
+.    ds ' \&
+.    ds ` \&
+.    ds ^ \&
+.    ds , \&
+.    ds ~ ~
+.    ds /
+.\}
+.if t \{\
+.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
+.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
+.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
+.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
+.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
+.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
+.\}
+.    \" troff and (daisy-wheel) nroff accents
+.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
+.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
+.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
+.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
+.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
+.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
+.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
+.ds ae a\h'-(\w'a'u*4/10)'e
+.ds Ae A\h'-(\w'A'u*4/10)'E
+.    \" corrections for vroff
+.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
+.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
+.    \" for low resolution devices (crt and lpr)
+.if \n(.H>23 .if \n(.V>19 \
+\{\
+.    ds : e
+.    ds 8 ss
+.    ds o a
+.    ds d- d\h'-1'\(ga
+.    ds D- D\h'-1'\(hy
+.    ds th \o'bp'
+.    ds Th \o'LP'
+.    ds ae ae
+.    ds Ae AE
+.\}
+.rm #[ #] #H #V #F C
+.\" ========================================================================
+.\"
+.IX Title "SSL_READ_EARLY_DATA 3"
+.TH SSL_READ_EARLY_DATA 3 "2019-09-10" "1.1.1d" "OpenSSL"
+.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
+.\" way too many mistakes in technical documents.
+.if n .ad l
+.nh
+.SH "NAME"
+SSL_set_max_early_data, SSL_CTX_set_max_early_data, SSL_get_max_early_data, SSL_CTX_get_max_early_data, SSL_set_recv_max_early_data, SSL_CTX_set_recv_max_early_data, SSL_get_recv_max_early_data, SSL_CTX_get_recv_max_early_data, SSL_SESSION_get_max_early_data, SSL_SESSION_set_max_early_data, SSL_write_early_data, SSL_read_early_data, SSL_get_early_data_status, SSL_allow_early_data_cb_fn, SSL_CTX_set_allow_early_data_cb, SSL_set_allow_early_data_cb \&\- functions for sending and receiving early data
+.SH "SYNOPSIS"
+.IX Header "SYNOPSIS"
+.Vb 1
+\& #include <openssl/ssl.h>
+\&
+\& int SSL_CTX_set_max_early_data(SSL_CTX *ctx, uint32_t max_early_data);
+\& uint32_t SSL_CTX_get_max_early_data(const SSL_CTX *ctx);
+\& int SSL_set_max_early_data(SSL *s, uint32_t max_early_data);
+\& uint32_t SSL_get_max_early_data(const SSL *s);
+\&
+\& int SSL_CTX_set_recv_max_early_data(SSL_CTX *ctx, uint32_t recv_max_early_data);
+\& uint32_t SSL_CTX_get_recv_max_early_data(const SSL_CTX *ctx);
+\& int SSL_set_recv_max_early_data(SSL *s, uint32_t recv_max_early_data);
+\& uint32_t SSL_get_recv_max_early_data(const SSL *s);
+\&
+\& uint32_t SSL_SESSION_get_max_early_data(const SSL_SESSION *s);
+\& int SSL_SESSION_set_max_early_data(SSL_SESSION *s, uint32_t max_early_data);
+\&
+\& int SSL_write_early_data(SSL *s, const void *buf, size_t num, size_t *written);
+\&
+\& int SSL_read_early_data(SSL *s, void *buf, size_t num, size_t *readbytes);
+\&
+\& int SSL_get_early_data_status(const SSL *s);
+\&
+\&
+\& typedef int (*SSL_allow_early_data_cb_fn)(SSL *s, void *arg);
+\&
+\& void SSL_CTX_set_allow_early_data_cb(SSL_CTX *ctx,
+\&                                      SSL_allow_early_data_cb_fn cb,
+\&                                      void *arg);
+\& void SSL_set_allow_early_data_cb(SSL *s,
+\&                                  SSL_allow_early_data_cb_fn cb,
+\&                                  void *arg);
+.Ve
+.SH "DESCRIPTION"
+.IX Header "DESCRIPTION"
+These functions are used to send and receive early data where TLSv1.3 has been
+negotiated. Early data can be sent by the client immediately after its initial
+ClientHello without having to wait for the server to complete the handshake.
+Early data can only be sent if a session has previously been established with
+the server, and the server is known to support it. Additionally these functions
+can be used to send data from the server to the client when the client has not
+yet completed the authentication stage of the handshake.
+.PP
+Early data has weaker security properties than other data sent over an \s-1SSL/TLS\s0
+connection. In particular the data does not have forward secrecy. There are also
+additional considerations around replay attacks (see \*(L"\s-1REPLAY PROTECTION\*(R"\s0
+below). For these reasons extreme care should be exercised when using early
+data. For specific details, consult the \s-1TLS 1.3\s0 specification.
+.PP
+When a server receives early data it may opt to immediately respond by sending
+application data back to the client. Data sent by the server at this stage is
+done before the full handshake has been completed. Specifically the client's
+authentication messages have not yet been received, i.e. the client is
+unauthenticated at this point and care should be taken when using this
+capability.
+.PP
+A server or client can determine whether the full handshake has been completed
+or not by calling \fBSSL_is_init_finished\fR\|(3).
+.PP
+On the client side, the function \fBSSL_SESSION_get_max_early_data()\fR can be used to
+determine if a session established with a server can be used to send early data.
+If the session cannot be used then this function will return 0. Otherwise it
+will return the maximum number of early data bytes that can be sent.
+.PP
+The function \fBSSL_SESSION_set_max_early_data()\fR sets the maximum number of early
+data bytes that can be sent for a session. This would typically be used when
+creating a \s-1PSK\s0 session file (see \fBSSL_CTX_set_psk_use_session_callback\fR\|(3)). If
+using a ticket based \s-1PSK\s0 then this is set automatically to the value provided by
+the server.
+.PP
+A client uses the function \fBSSL_write_early_data()\fR to send early data. This
+function is similar to the \fBSSL_write_ex\fR\|(3) function, but with the following
+differences. See \fBSSL_write_ex\fR\|(3) for information on how to write bytes to
+the underlying connection, and how to handle any errors that may arise. This
+page describes the differences between \fBSSL_write_early_data()\fR and
+\&\fBSSL_write_ex\fR\|(3).
+.PP
+When called by a client, \fBSSL_write_early_data()\fR must be the first \s-1IO\s0 function
+called on a new connection, i.e. it must occur before any calls to
+\&\fBSSL_write_ex\fR\|(3), \fBSSL_read_ex\fR\|(3), \fBSSL_connect\fR\|(3), \fBSSL_do_handshake\fR\|(3)
+or other similar functions. It may be called multiple times to stream data to
+the server, but the total number of bytes written must not exceed the value
+returned from \fBSSL_SESSION_get_max_early_data()\fR. Once the initial
+\&\fBSSL_write_early_data()\fR call has completed successfully the client may interleave
+calls to \fBSSL_read_ex\fR\|(3) and \fBSSL_read\fR\|(3) with calls to
+\&\fBSSL_write_early_data()\fR as required.
+.PP
+If \fBSSL_write_early_data()\fR fails you should call \fBSSL_get_error\fR\|(3) to determine
+the correct course of action, as for \fBSSL_write_ex\fR\|(3).
+.PP
+When the client no longer wishes to send any more early data then it should
+complete the handshake by calling a function such as \fBSSL_connect\fR\|(3) or
+\&\fBSSL_do_handshake\fR\|(3). Alternatively you can call a standard write function
+such as \fBSSL_write_ex\fR\|(3), which will transparently complete the connection and
+write the requested data.
+.PP
+A server may choose to ignore early data that has been sent to it. Once the
+connection has been completed you can determine whether the server accepted or
+rejected the early data by calling \fBSSL_get_early_data_status()\fR. This will return
+\&\s-1SSL_EARLY_DATA_ACCEPTED\s0 if the data was accepted, \s-1SSL_EARLY_DATA_REJECTED\s0 if it
+was rejected or \s-1SSL_EARLY_DATA_NOT_SENT\s0 if no early data was sent. This function
+may be called by either the client or the server.
+.PP
+A server uses the \fBSSL_read_early_data()\fR function to receive early data on a
+connection for which early data has been enabled using
+\&\fBSSL_CTX_set_max_early_data()\fR or \fBSSL_set_max_early_data()\fR. As for
+\&\fBSSL_write_early_data()\fR, this must be the first \s-1IO\s0 function
+called on a connection, i.e. it must occur before any calls to
+\&\fBSSL_write_ex\fR\|(3), \fBSSL_read_ex\fR\|(3), \fBSSL_accept\fR\|(3), \fBSSL_do_handshake\fR\|(3),
+or other similar functions.
+.PP
+\&\fBSSL_read_early_data()\fR is similar to \fBSSL_read_ex\fR\|(3) with the following
+differences. Refer to \fBSSL_read_ex\fR\|(3) for full details.
+.PP
+\&\fBSSL_read_early_data()\fR may return 3 possible values:
+.IP "\s-1SSL_READ_EARLY_DATA_ERROR\s0" 4
+.IX Item "SSL_READ_EARLY_DATA_ERROR"
+This indicates an \s-1IO\s0 or some other error occurred. This should be treated in the
+same way as a 0 return value from \fBSSL_read_ex\fR\|(3).
+.IP "\s-1SSL_READ_EARLY_DATA_SUCCESS\s0" 4
+.IX Item "SSL_READ_EARLY_DATA_SUCCESS"
+This indicates that early data was successfully read. This should be treated in
+the same way as a 1 return value from \fBSSL_read_ex\fR\|(3). You should continue to
+call \fBSSL_read_early_data()\fR to read more data.
+.IP "\s-1SSL_READ_EARLY_DATA_FINISH\s0" 4
+.IX Item "SSL_READ_EARLY_DATA_FINISH"
+This indicates that no more early data can be read. It may be returned on the
+first call to \fBSSL_read_early_data()\fR if the client has not sent any early data,
+or if the early data was rejected.
+.PP
+Once the initial \fBSSL_read_early_data()\fR call has completed successfully (i.e. it
+has returned \s-1SSL_READ_EARLY_DATA_SUCCESS\s0 or \s-1SSL_READ_EARLY_DATA_FINISH\s0) then the
+server may choose to write data immediately to the unauthenticated client using
+\&\fBSSL_write_early_data()\fR. If \fBSSL_read_early_data()\fR returned
+\&\s-1SSL_READ_EARLY_DATA_FINISH\s0 then in some situations (e.g. if the client only
+supports TLSv1.2) the handshake may have already been completed and calls
+to \fBSSL_write_early_data()\fR are not allowed. Call \fBSSL_is_init_finished\fR\|(3) to
+determine whether the handshake has completed or not. If the handshake is still
+in progress then the server may interleave calls to \fBSSL_write_early_data()\fR with
+calls to \fBSSL_read_early_data()\fR as required.
+.PP
+Servers must not call \fBSSL_read_ex\fR\|(3), \fBSSL_read\fR\|(3), \fBSSL_write_ex\fR\|(3) or
+\&\fBSSL_write\fR\|(3)  until \fBSSL_read_early_data()\fR has returned with
+\&\s-1SSL_READ_EARLY_DATA_FINISH.\s0 Once it has done so the connection to the client
+still needs to be completed. Complete the connection by calling a function such
+as \fBSSL_accept\fR\|(3) or \fBSSL_do_handshake\fR\|(3). Alternatively you can call a
+standard read function such as \fBSSL_read_ex\fR\|(3), which will transparently
+complete the connection and read the requested data. Note that it is an error to
+attempt to complete the connection before \fBSSL_read_early_data()\fR has returned
+\&\s-1SSL_READ_EARLY_DATA_FINISH.\s0
+.PP
+Only servers may call \fBSSL_read_early_data()\fR.
+.PP
+Calls to \fBSSL_read_early_data()\fR may, in certain circumstances, complete the
+connection immediately without further need to call a function such as
+\&\fBSSL_accept\fR\|(3). This can happen if the client is using a protocol version less
+than TLSv1.3. Applications can test for this by calling
+\&\fBSSL_is_init_finished\fR\|(3). Alternatively, applications may choose to call
+\&\fBSSL_accept\fR\|(3) anyway. Such a call will successfully return immediately with no
+further action taken.
+.PP
+When a session is created between a server and a client the server will specify
+the maximum amount of any early data that it will accept on any future
+connection attempt. By default the server does not accept early data; a
+server may indicate support for early data by calling
+\&\fBSSL_CTX_set_max_early_data()\fR or
+\&\fBSSL_set_max_early_data()\fR to set it for the whole \s-1SSL_CTX\s0 or an individual \s-1SSL\s0
+object respectively. The \fBmax_early_data\fR parameter specifies the maximum
+amount of early data in bytes that is permitted to be sent on a single
+connection. Similarly the \fBSSL_CTX_get_max_early_data()\fR and
+\&\fBSSL_get_max_early_data()\fR functions can be used to obtain the current maximum
+early data settings for the \s-1SSL_CTX\s0 and \s-1SSL\s0 objects respectively. Generally a
+server application will either use both of \fBSSL_read_early_data()\fR and
+\&\fBSSL_CTX_set_max_early_data()\fR (or \fBSSL_set_max_early_data()\fR), 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
+automatically enabled (see \*(L"\s-1REPLAY PROTECTION\*(R"\s0 below).
+.PP
+If the server rejects the early data sent by a client then it will skip over
+the data that is sent. The maximum amount of received early data that is skipped
+is controlled by the recv_max_early_data setting. If a client sends more than
+this then the connection will abort. This value can be set by calling
+\&\fBSSL_CTX_set_recv_max_early_data()\fR or \fBSSL_set_recv_max_early_data()\fR. The current
+value for this setting can be obtained by calling
+\&\fBSSL_CTX_get_recv_max_early_data()\fR or \fBSSL_get_recv_max_early_data()\fR. The default
+value for this setting is 16,384 bytes.
+.PP
+The recv_max_early_data value also has an impact on early data that is accepted.
+The amount of data that is accepted will always be the lower of the
+max_early_data for the session and the recv_max_early_data setting for the
+server. If a client sends more data than this then the connection will abort.
+.PP
+The configured value for max_early_data on a server may change over time as
+required. However clients may have tickets containing the previously configured
+max_early_data value. The recv_max_early_data should always be equal to or
+higher than any recently configured max_early_data value in order to avoid
+aborted connections. The recv_max_early_data should never be set to less than
+the current configured max_early_data value.
+.PP
+Some server applications may wish to have more control over whether early data
+is accepted or not, for example to mitigate replay risks (see \*(L"\s-1REPLAY PROTECTION\*(R"\s0
+below) or to decline early_data when the server is heavily loaded. The functions
+\&\fBSSL_CTX_set_allow_early_data_cb()\fR and \fBSSL_set_allow_early_data_cb()\fR set a
+callback which is called at a point in the handshake immediately before a
+decision is made to accept or reject early data. The callback is provided with a
+pointer to the user data argument that was provided when the callback was first
+set. Returning 1 from the callback will allow early data and returning 0 will
+reject it. Note that the OpenSSL library may reject early data for other reasons
+in which case this callback will not get called. Notably, the built-in replay
+protection feature will still be used even if a callback is present unless it
+has been explicitly disabled using the \s-1SSL_OP_NO_ANTI_REPLAY\s0 option. See
+\&\*(L"\s-1REPLAY PROTECTION\*(R"\s0 below.
+.SH "NOTES"
+.IX Header "NOTES"
+The whole purpose of early data is to enable a client to start sending data to
+the server before a full round trip of network traffic has occurred. Application
+developers should ensure they consider optimisation of the underlying \s-1TCP\s0 socket
+to obtain a performant solution. For example Nagle's algorithm is commonly used
+by operating systems in an attempt to avoid lots of small \s-1TCP\s0 packets. In many
+scenarios this is beneficial for performance, but it does not work well with the
+early data solution as implemented in OpenSSL. In Nagle's algorithm the \s-1OS\s0 will
+buffer outgoing \s-1TCP\s0 data if a \s-1TCP\s0 packet has already been sent which we have not
+yet received an \s-1ACK\s0 for from the peer. The buffered data will only be
+transmitted if enough data to fill an entire \s-1TCP\s0 packet is accumulated, or if
+the \s-1ACK\s0 is received from the peer. The initial ClientHello will be sent in the
+first \s-1TCP\s0 packet along with any data from the first call to
+\&\fBSSL_write_early_data()\fR. If the amount of data written will exceed the size of a
+single \s-1TCP\s0 packet, or if there are more calls to \fBSSL_write_early_data()\fR then
+that additional data will be sent in subsequent \s-1TCP\s0 packets which will be
+buffered by the \s-1OS\s0 and not sent until an \s-1ACK\s0 is received for the first packet
+containing the ClientHello. This means the early data is not actually
+sent until a complete round trip with the server has occurred which defeats the
+objective of early data.
+.PP
+In many operating systems the \s-1TCP_NODELAY\s0 socket option is available to disable
+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.
+.PP
+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
+\&\fBSSL_CTX_set_recv_max_early_data()\fR. 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 \s-1SSL/TLS\s0
+connection again but without sending early data. Note that it is inadvisable to
+retry with a lower maximum protocol version.
+.SH "REPLAY PROTECTION"
+.IX Header "REPLAY PROTECTION"
+When early data is in use the \s-1TLS\s0 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
+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
+was submitted will be ignored). Note that single use tickets are enforced even
+if a client does not send any early data.
+.PP
+The replay protection mechanism relies on the internal OpenSSL server session
+cache (see \fBSSL_CTX_set_session_cache_mode\fR\|(3)). When replay protection is
+being used the server will operate as if the \s-1SSL_OP_NO_TICKET\s0 option had been
+selected (see \fBSSL_CTX_set_options\fR\|(3)). Sessions will be added to the cache
+whenever a session ticket is issued. When a client attempts to resume the
+session, OpenSSL will check for its presence in the internal cache. If it exists
+then the resumption is allowed and the session is removed from the cache. If it
+does not exist then the resumption is not allowed and a full handshake will
+occur.
+.PP
+Note that some applications may maintain an external cache of sessions (see
+\&\fBSSL_CTX_sess_set_new_cb\fR\|(3) and similar functions). It is the application's
+responsibility to ensure that any sessions in the external cache are also
+populated in the internal cache and that once removed from the internal cache
+they are similarly removed from the external cache. Failing to do this could
+result in an application becoming vulnerable to replay attacks. Note that
+OpenSSL will lock the internal cache while a session is removed but that lock is
+not held when the remove session callback (see \fBSSL_CTX_sess_set_remove_cb\fR\|(3))
+is called. This could result in a small amount of time where the session has
+been removed from the internal cache but is still available in the external
+cache. Applications should be designed with this in mind in order to minimise
+the possibility of replay attacks.
+.PP
+The OpenSSL replay protection does not apply to external Pre Shared Keys (PSKs)
+(e.g. see \fBSSL_CTX_set_psk_find_session_callback\fR\|(3)). Therefore extreme caution
+should be applied when combining external PSKs with early data.
+.PP
+Some applications may mitigate the replay risks in other ways. For those
+applications it is possible to turn off the built-in replay protection feature
+using the \fB\s-1SSL_OP_NO_ANTI_REPLAY\s0\fR option. See \fBSSL_CTX_set_options\fR\|(3) for
+details. Applications can also set a callback to make decisions about accepting
+early data or not. See \fBSSL_CTX_set_allow_early_data_cb()\fR above for details.
+.SH "RETURN VALUES"
+.IX Header "RETURN VALUES"
+\&\fBSSL_write_early_data()\fR returns 1 for success or 0 for failure. In the event of a
+failure call \fBSSL_get_error\fR\|(3) to determine the correct course of action.
+.PP
+\&\fBSSL_read_early_data()\fR returns \s-1SSL_READ_EARLY_DATA_ERROR\s0 for failure,
+\&\s-1SSL_READ_EARLY_DATA_SUCCESS\s0 for success with more data to read and
+\&\s-1SSL_READ_EARLY_DATA_FINISH\s0 for success with no more to data be read. In the
+event of a failure call \fBSSL_get_error\fR\|(3) to determine the correct course of
+action.
+.PP
+\&\fBSSL_get_max_early_data()\fR, \fBSSL_CTX_get_max_early_data()\fR and
+\&\fBSSL_SESSION_get_max_early_data()\fR return the maximum number of early data bytes
+that may be sent.
+.PP
+\&\fBSSL_set_max_early_data()\fR, \fBSSL_CTX_set_max_early_data()\fR and
+\&\fBSSL_SESSION_set_max_early_data()\fR return 1 for success or 0 for failure.
+.PP
+\&\fBSSL_get_early_data_status()\fR returns \s-1SSL_EARLY_DATA_ACCEPTED\s0 if early data was
+accepted by the server, \s-1SSL_EARLY_DATA_REJECTED\s0 if early data was rejected by
+the server, or \s-1SSL_EARLY_DATA_NOT_SENT\s0 if no early data was sent.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+\&\fBSSL_get_error\fR\|(3),
+\&\fBSSL_write_ex\fR\|(3),
+\&\fBSSL_read_ex\fR\|(3),
+\&\fBSSL_connect\fR\|(3),
+\&\fBSSL_accept\fR\|(3),
+\&\fBSSL_do_handshake\fR\|(3),
+\&\fBSSL_CTX_set_psk_use_session_callback\fR\|(3),
+\&\fBssl\fR\|(7)
+.SH "HISTORY"
+.IX Header "HISTORY"
+All of the functions described above were added in OpenSSL 1.1.1.
+.SH "COPYRIGHT"
+.IX Header "COPYRIGHT"
+Copyright 2017\-2019 The OpenSSL Project Authors. All Rights Reserved.
+.PP
+Licensed under the OpenSSL license (the \*(L"License\*(R").  You may not use
+this file except in compliance with the License.  You can obtain a copy
+in the file \s-1LICENSE\s0 in the source distribution or at
+<https://www.openssl.org/source/license.html>.