Protocol names are printable ASCII strings, for example "http/1.1" or
"spdy/3".
-=item B<-max_early_data>
+=item B<-max_early_data arg>
Change the default maximum early data bytes that are specified for new sessions
and any incoming early data (when used in conjunction with the B<-early_data>
-flag). The default value is approximately 16k.
+flag). The default value is approximately 16k. The argument must be an integer
+greater than or equal to 0.
=item B<-early_data>
+++ /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_data,
-SSL_read_early_data,
-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_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);
-
-=head1 DESCRIPTION
-
-These functions are used to send and recieve 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.
-
-Early data has weaker security properties than other data sent over an SSL/TLS
-connection. In particular the data does not have forward secrecy and there are
-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.
-
-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.
-
-A server or client can determine whether the full handshake has been completed
-or not by calling L<SSL_is_init_finished(3)>.
-
-On the client side, the function SSL_SESSION_get_max_early_data() 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.
-
-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
-page describes the differences between SSL_write_early_data() and
-L<SSL_write_ex(3)>.
-
-When called by a client, SSL_write_early_data() 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 the initial
-SSL_write_early_data() call has completed successfully the client may interleave
-calls to L<SSL_read_ex(3)> and L<SSL_read(3)> with calls to
-SSL_write_early_data() as required.
-
-If SSL_write_early_data() fails you should call L<SSL_get_error(3)> to determine
-the correct course of action, as for L<SSL_write_ex(3)>.
-
-When the client no longer wishes to send any more early data then it should
-complete the handshake by calling a function such as L<SSL_connect(3)> or
-L<SSL_do_handshake(3)>. Alternatively you can call a standard write function
-such as L<SSL_write_ex(3)>, which will transparently complete the connection and
-write the requested data.
-
-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_data() function to receive early data on a
-connection. As for SSL_write_early_data() 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_data() is similar to L<SSL_read_ex(3)> with the following
-differences. Refer to L<SSL_read_ex(3)> for full details.
-
-SSL_read_early_data() may return 3 possible values:
-
-=over 4
-
-=item SSL_READ_EARLY_DATA_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_DATA_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_data() to read more data.
-
-=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 SSL_read_early_data() if the client has not sent any early data,
-or if the early data was rejected.
-
-=back
-
-Once the initial SSL_read_early_data() call has completed successfully (i.e. it
-has returned SSL_READ_EARLY_DATA_SUCCESS or SSL_READ_EARLY_DATA_FINISH) then the
-server may choose to write data immediately to the unauthenticated client using
-SSL_write_early_data(). If SSL_read_early_data() returned
-SSL_READ_EARLY_DATA_FINISH then in some situations (e.g. if the client only
-supports TLSv1.2) the handshake may have already been completed and calls
-to SSL_write_early_data() are not allowed. Call L<SSL_is_init_finished(3)> to
-determine whether the handshake has completed or not. If the handshake is still
-in progress then the server may interleave calls to SSL_write_early_data() with
-calls to SSL_read_early_data() as required.
-
-Servers must not call L<SSL_read_ex(3)>, L<SSL_read(3)>, L<SSL_write_ex(3)> or
-L<SSL_write(3)> until SSL_read_early_data() has returned with
-SSL_READ_EARLY_DATA_FINISH. Once it has done so 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
-standard read function such as L<SSL_read_ex(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 SSL_read_early_data() has returned
-SSL_READ_EARLY_DATA_FINISH.
-
-Only servers may call SSL_read_early_data().
-
-Calls to SSL_read_early_data() may, in certain circumstances, complete the
-connection immediately without further need to call a function such as
-L<SSL_accept(3)>. This can happen if the client is using a protocol version less
-than TLSv1.3. Applications can test for this by calling
-L<SSL_is_init_finished(3)>. Alternatively, applications may choose to call
-L<SSL_accept(3)> anway. Such a call will successfully return immediately with no
-further action taken.
-
-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_data() returns 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_data() returns SSL_READ_EARLY_DATA_ERROR for failure,
-SSL_READ_EARLY_DATA_SUCCESS for success with more data to read and
-SSL_READ_EARLY_DATA_FINISH for success with 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
--- /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_data,
+SSL_read_early_data,
+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_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);
+
+=head1 DESCRIPTION
+
+These functions are used to send and recieve 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.
+
+Early data has weaker security properties than other data sent over an SSL/TLS
+connection. In particular the data does not have forward secrecy and there are
+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. For specific details, consult the TLS 1.3 specification.
+
+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.
+
+A server or client can determine whether the full handshake has been completed
+or not by calling L<SSL_is_init_finished(3)>.
+
+On the client side, the function SSL_SESSION_get_max_early_data() 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.
+
+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
+page describes the differences between SSL_write_early_data() and
+L<SSL_write_ex(3)>.
+
+When called by a client, SSL_write_early_data() 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 the initial
+SSL_write_early_data() call has completed successfully the client may interleave
+calls to L<SSL_read_ex(3)> and L<SSL_read(3)> with calls to
+SSL_write_early_data() as required.
+
+If SSL_write_early_data() fails you should call L<SSL_get_error(3)> to determine
+the correct course of action, as for L<SSL_write_ex(3)>.
+
+When the client no longer wishes to send any more early data then it should
+complete the handshake by calling a function such as L<SSL_connect(3)> or
+L<SSL_do_handshake(3)>. Alternatively you can call a standard write function
+such as L<SSL_write_ex(3)>, which will transparently complete the connection and
+write the requested data.
+
+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_data() function to receive early data on a
+connection. As for SSL_write_early_data() 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_data() is similar to L<SSL_read_ex(3)> with the following
+differences. Refer to L<SSL_read_ex(3)> for full details.
+
+SSL_read_early_data() may return 3 possible values:
+
+=over 4
+
+=item SSL_READ_EARLY_DATA_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_DATA_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_data() to read more data.
+
+=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 SSL_read_early_data() if the client has not sent any early data,
+or if the early data was rejected.
+
+=back
+
+Once the initial SSL_read_early_data() call has completed successfully (i.e. it
+has returned SSL_READ_EARLY_DATA_SUCCESS or SSL_READ_EARLY_DATA_FINISH) then the
+server may choose to write data immediately to the unauthenticated client using
+SSL_write_early_data(). If SSL_read_early_data() returned
+SSL_READ_EARLY_DATA_FINISH then in some situations (e.g. if the client only
+supports TLSv1.2) the handshake may have already been completed and calls
+to SSL_write_early_data() are not allowed. Call L<SSL_is_init_finished(3)> to
+determine whether the handshake has completed or not. If the handshake is still
+in progress then the server may interleave calls to SSL_write_early_data() with
+calls to SSL_read_early_data() as required.
+
+Servers must not call L<SSL_read_ex(3)>, L<SSL_read(3)>, L<SSL_write_ex(3)> or
+L<SSL_write(3)> until SSL_read_early_data() has returned with
+SSL_READ_EARLY_DATA_FINISH. Once it has done so 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
+standard read function such as L<SSL_read_ex(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 SSL_read_early_data() has returned
+SSL_READ_EARLY_DATA_FINISH.
+
+Only servers may call SSL_read_early_data().
+
+Calls to SSL_read_early_data() may, in certain circumstances, complete the
+connection immediately without further need to call a function such as
+L<SSL_accept(3)>. This can happen if the client is using a protocol version less
+than TLSv1.3. Applications can test for this by calling
+L<SSL_is_init_finished(3)>. Alternatively, applications may choose to call
+L<SSL_accept(3)> anway. Such a call will successfully return immediately with no
+further action taken.
+
+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_data() returns 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_data() returns SSL_READ_EARLY_DATA_ERROR for failure,
+SSL_READ_EARLY_DATA_SUCCESS for success with more data to read and
+SSL_READ_EARLY_DATA_FINISH for success with 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 / oweals / openssl.git / commitdiff