From: Matt Caswell Date: Fri, 24 Feb 2017 15:38:38 +0000 (+0000) Subject: Add documentation for the early data functions X-Git-Tag: OpenSSL_1_1_1-pre1~2144 X-Git-Url: https://git.openssl.org/?p=openssl.git;a=commitdiff_plain;h=fd6c102520e3829a10fb273eaa62bbccf793e22b Add documentation for the early data functions Reviewed-by: Rich Salz (Merged from https://github.com/openssl/openssl/pull/2737) --- diff --git a/doc/man3/SSL_read_early.pod b/doc/man3/SSL_read_early.pod new file mode 100644 index 0000000000..3c35ba9d0e --- /dev/null +++ b/doc/man3/SSL_read_early.pod @@ -0,0 +1,190 @@ +=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 + + 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 function, but with a few +differences. Refer to the L 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_early() must be the first IO function called on a new connection, i.e. +it must occur before any calls to L, L, +L, L 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 to determine the correct course of action, as for +L. + +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 or L. Alternatively you can call a +"normal" read/write function such as L or L, +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, +L, L, L, or other similar +functions. + +SSL_read_early() works in the same way as L except for the +differences noted here. Refer to the L 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. + +=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. 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 or L. Alternatively you can call a +"normal" read/write function such as L or L, +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 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 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, +L, +L, +L, +L, +L, +L + +=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. + +=cut