--- /dev/null
+=pod
+
+=head1 NAME
+
+SSL_set_max_early_data,
+SSL_CTX_set_max_early_data,
+SSL_get_max_early_data,
+SSL_CTX_get_max_early_data,
+SSL_SESSION_get_max_early_data,
+SSL_write_early,
+SSL_write_early_finish,
+SSL_read_early,
+SSL_get_early_data_status
+- functions for sending and receiving early data
+
+=head1 SYNOPSIS
+
+ #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_CTX *s);
+ uint32_t SSL_SESSION_get_max_early_data(const SSL_SESSION *s);
+
+ int SSL_write_early(SSL *s, const void *buf, size_t num, size_t *written);
+ int SSL_write_early_finish(SSL *s);
+
+ int SSL_read_early(SSL *s, void *buf, size_t num, size_t *readbytes);
+
+ int SSL_get_early_data_status(const SSL *s);
+
+=head1 DESCRIPTION
+
+These functions are used to send and recieve early data. 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.
+
+Early data has weaker security properties than other data sent over an SSL/TLS
+connection. In particular the data is not forward secret and the server has no
+guarantees that the same early data was not replayed across multiple
+connections. For this reason extreme care should be exercised when using early
+data.
+
+On the client side the function SSL_SESSION_get_max_early_data() can be used to
+determine whether 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.
+
+A client uses the function SSL_write_early() to send early data. This function
+works in the same way as the L<SSL_write_ex(3)> function, but with a few
+differences. Refer to the L<SSL_write_ex(3)> documentation for
+information on how to write bytes to the underlying connection, and how to
+handle any errors that may arise. This page will detail the differences between
+SSL_write_early() and L<SSL_write_ex(3)>.
+
+SSL_write_early() must be the first IO function called on a new connection, i.e.
+it must occur before any calls to L<SSL_write_ex(3)>, L<SSL_read_ex(3)>,
+L<SSL_connect(3)>, L<SSL_do_handshake(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
+SSL_SESSION_get_max_early_data().
+
+Once finished writing early data you must then call SSL_write_early_finish().
+This sends a message to the server signalling the end of early data.
+
+If either SSL_write_early() or SSL_write_early_finish() fail you should call
+L<SSL_get_error(3)> to determine the correct course of action, as for
+L<SSL_write_ex(3)>.
+
+Following an SSL_write_early_finish() call the connection to the server still
+needs to be completed. Complete the connection by calling a function such as
+L<SSL_connect(3)> or L<SSL_do_handshake(3)>. Alternatively you can call a
+"normal" read/write function such as L<SSL_read_ex(3)> or L<SSL_write_ex(3)>,
+which will transparently complete the connection and read/write the requested
+data.
+
+Only clients may call SSL_write_early() or SSL_write_early_finish().
+
+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 SSL_get_early_data_status(). This will return
+SSL_EARLY_DATA_ACCEPTED if the data was accepted, SSL_EARLY_DATA_REJECTED if it
+was rejected or SSL_EARLY_DATA_NOT_SENT if no early data was sent. This function
+may be called by either the client or the server.
+
+A server uses the SSL_read_early() function to receive early data on a
+connection. As for SSL_write_early() this must be the first IO function called
+on a connection, i.e. it must occur before any calls to L<SSL_write_ex(3)>,
+L<SSL_read_ex(3)>, L<SSL_accept(3)>, L<SSL_do_handshake(3)>, or other similar
+functions.
+
+SSL_read_early() works in the same way as L<SSL_read_ex(3)> except for the
+differences noted here. Refer to the L<SSL_read_ex(3)> documentation for full
+details.
+
+SSL_read_early() may return 3 possible values:
+
+=over 4
+
+=item SSL_READ_EARLY_ERROR
+
+This indicates an IO or some other error occured. This should be treated in the
+same way as a 0 return value from L<SSL_read_ex(3)>.
+
+=item SSL_READ_EARLY_SUCCESS
+
+This indicates that early data was successfully read. This should be treated in
+the same way as a 1 return value from L<SSL_read_ex(3)>. You should continue to
+call SSL_read_early() to read more data.
+
+=item SSL_READ_EARLY_FINISH
+
+This indicates that no more early data can be read. It may be returned on the
+first call to SSL_read_early() if the client has not sent any early data, or
+if the early data was rejected.
+
+=back
+
+Once SSL_read_early() returns SSL_READ_EARLY_FINISH the connection to the client
+still needs to be completed. Complete the connection by calling a function such
+as L<SSL_accept(3)> or L<SSL_do_handshake(3)>. Alternatively you can call a
+"normal" read/write function such as L<SSL_read_ex(3)> or L<SSL_write_ex(3)>,
+which will transparently complete the connection and read/write the requested
+data. Note that it is an error to attempt to complete the connection before
+SSL_read_early() has returned SSL_READ_EARLY_FINISH.
+
+Only servers may call SSL_read_early().
+
+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 this is approximately 16k. A server may override
+this default value by calling SSL_CTX_set_max_early_data() or
+SSL_set_max_early_data() to set it for the whole SSL_CTX or an individual SSL
+object respectively. Similarly the SSL_CTX_get_max_early_data() and
+SSL_get_max_early_data() functions can be used to obtain the current maximum
+early data settings for the SSL_CTX and SSL objects respectively.
+
+In the event that the current maximum early data setting for the server is
+different to that originally specified in a session that a client is resuming
+with then the lower of the two values will apply.
+
+=head1 RETURN VALUES
+
+SSL_write_early() and SSL_write_early_finish() return 1 for success or 0 for
+failure. In the event of a failure call L<SSL_get_error(3)> to determine the
+correct course of action.
+
+SSL_read_early() returns SSL_READ_EARLY_ERROR for failure,
+SSL_READ_EARLY_SUCCESS for success with more data to read and
+SSL_READ_EARLY_FINISH for no more to data be read. In the event of a failure
+call L<SSL_get_error(3)> to determine the correct course of action.
+
+SSL_get_max_early_data(), SSL_CTX_get_max_early_data() and
+SSL_SESSION_get_max_early_data() return the maximum number of early data bytes
+that may be sent.
+
+SSL_set_max_early_data() and SSL_CTX_set_max_early_data() return 1 for success
+or 0 for failure.
+
+SSL_get_early_data_status() returns SSL_EARLY_DATA_ACCEPTED if early data was
+accepted by the server, SSL_EARLY_DATA_REJECTED if early data was rejected by
+the server, or SSL_EARLY_DATA_NOT_SENT if no early data was sent.
+
+=head1 SEE ALSO
+
+L<SSL_get_error(3)>,
+L<SSL_write_ex(3)>,
+L<SSL_read_ex(3)>,
+L<SSL_connect(3)>,
+L<SSL_accept(3)>,
+L<SSL_do_handshake(3)>,
+L<ssl(7)>
+
+=head1 HISTORY
+
+All of the functions described above were added in OpenSSL 1.1.1.
+
+=head1 COPYRIGHT
+
+Copyright 2017 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (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>.
+
+=cut
projects / openssl.git / commitdiff