diff --git a/doc/man3/SSL_read.pod b/doc/man3/SSL_read.pod index 0bfc2a4135..0c1f1dbf4c 100644 --- a/doc/man3/SSL_read.pod +++ b/doc/man3/SSL_read.pod @@ -93,6 +93,14 @@ are buffered bytes available for immediate retrieval. In this case the read function can be called without blocking or actually receiving new data from the underlying socket. +When used with a QUIC SSL object, calling an I/O function such as SSL_read() +allows internal network event processing to be performed. It is important that +this processing is performed regularly. If an application is not using thread +assisted mode, an application should ensure that an I/O function such as +SSL_read() is called regularly, or alternatively ensure that SSL_handle_events() +is called regularly. See L and L for more +information. + =head1 RETURN VALUES SSL_read_ex() and SSL_peek_ex() will return 1 for success or 0 for failure. diff --git a/doc/man3/SSL_shutdown.pod b/doc/man3/SSL_shutdown.pod index e297c23f79..b1a5c94fd9 100644 --- a/doc/man3/SSL_shutdown.pod +++ b/doc/man3/SSL_shutdown.pod @@ -21,155 +21,284 @@ SSL_shutdown, SSL_shutdown_ex - shut down a TLS/SSL or QUIC connection =head1 DESCRIPTION -SSL_shutdown() shuts down an active TLS/SSL connection. It sends the -close_notify shutdown alert to the peer. - -SSL_shutdown() tries to send the close_notify shutdown alert to the peer. -Whether the operation succeeds or not, the SSL_SENT_SHUTDOWN flag is set and -a currently open session is considered closed and good and will be kept in the -session cache for further reuse. - -Note that SSL_shutdown() must not be called if a previous fatal error has -occurred on a connection i.e. if SSL_get_error() has returned SSL_ERROR_SYSCALL -or SSL_ERROR_SSL. - -The shutdown procedure consists of two steps: sending of the close_notify -shutdown alert, and reception of the peer's close_notify shutdown alert. -The order of those two steps depends on the application. - -It is acceptable for an application to only send its shutdown alert and -then close the underlying connection without waiting for the peer's response. -This way resources can be saved, as the process can already terminate or -serve another connection. -This should only be done when it is known that the other side will not send more -data, otherwise there is a risk of a truncation attack. - -When a client only writes and never reads from the connection, and the server -has sent a session ticket to establish a session, the client might not be able -to resume the session because it did not received and process the session ticket -from the server. -In case the application wants to be able to resume the session, it is recommended to -do a complete shutdown procedure (bidirectional close_notify alerts). - -When the underlying connection shall be used for more communications, the -complete shutdown procedure must be performed, so that the peers stay -synchronized. - -SSL_shutdown() only closes the write direction. -It is not possible to call SSL_write() after calling SSL_shutdown(). -The read direction is closed by the peer. - -The behaviour of SSL_shutdown() additionally depends on the underlying BIO. -If the underlying BIO is B, SSL_shutdown() will only return once the -handshake step has been finished or an error occurred. - -If the underlying BIO is B, SSL_shutdown() will also return -when the underlying BIO could not satisfy the needs of SSL_shutdown() -to continue the handshake. In this case a call to SSL_get_error() with the -return value of SSL_shutdown() will yield B or -B. The calling process then must repeat the call after -taking appropriate action to satisfy the needs of SSL_shutdown(). -The action depends on the underlying BIO. When using a nonblocking socket, -nothing is to be done, but select() can be used to check for the required -condition. When using a buffering BIO, like a BIO pair, data must be written -into or retrieved out of the BIO before being able to continue. - -After SSL_shutdown() returned 0, it is possible to call SSL_shutdown() again -to wait for the peer's close_notify alert. -SSL_shutdown() will return 1 in that case. -However, it is recommended to wait for it using SSL_read() instead. - -SSL_shutdown() can be modified to only set the connection to "shutdown" -state but not actually send the close_notify alert messages, -see L. -When "quiet shutdown" is enabled, SSL_shutdown() will always succeed -and return 1. -Note that this is not standard compliant behaviour. -It should only be done when the peer has a way to make sure all -data has been received and doesn't wait for the close_notify alert -message, otherwise an unexpected EOF will be reported. - -There are implementations that do not send the required close_notify alert. -If there is a need to communicate with such an implementation, and it's clear -that all data has been received, do not wait for the peer's close_notify alert. -Waiting for the close_notify alert when the peer just closes the connection -will result in an error being generated. -The error can be ignored using the B. -For more information see L. +SSL_shutdown() shuts down an active connection represented by an SSL object. SSL_shutdown_ex() is an extended version of SSL_shutdown(). If non-NULL, I must point to a B structure and I must be set to C. The B structure must be zero-initialized. If I is NULL, the behaviour is the same as passing a -zero-initialised B structure. When used with a non-QUIC -SSL object, the arguments are ignored and the call functions identically to -SSL_shutdown(). +zero-initialised B structure. Currently, all extended +arguments relate to usage with QUIC, therefore this call functions identically +to SSL_shutdown() when not being used with QUIC. -When used with a QUIC connection SSL object, SSL_shutdown_ex() initiates a QUIC -immediate close. The I field can be used to specify a 62-bit -application error code to be signalled via QUIC. The value specified must be in -the range [0, 2**62-1], else this call fails. I may optionally -specify a zero-terminated reason string to be signalled to the peer. If a reason -is not specified, a zero-length string is used as the reason. The reason string -is copied and need not remain allocated after the call to the function returns. -Reason strings are bounded by the path MTU and may be silently truncated if they -are too long to fit in a QUIC packet. The arguments are only used on the first -call to SSL_shutdown_ex() for a given QUIC connection SSL object. +While the general operation of SSL_shutdown() is common between protocols, the +exact nature of how a shutdown is performed depends on the underlying protocol +being used. See the section below pertaining to each protocol for more +information. -When using QUIC, how an application uses SSL_shutdown() or SSL_shutdown_ex() has -implications for whether QUIC closes a connection in an RFC-compliant manner. -For discussion of these issues, and for discussion of the I argument, see -B below. +In general, calling SSL_shutdown() in nonblocking mode will initiate the +shutdown process and return 0 to indicate that the shutdown process has not yet +completed. Once the shutdown process has completed, subsequent calls to +SSL_shutdown() will return 1. See the RETURN VALUES section for more +information. -=head2 First to close the connection +SSL_shutdown() should not be called if a previous fatal error has occurred on a +connection; i.e., if L has returned B or +B. -When the application is the first party to send the close_notify -alert, SSL_shutdown() will only send the alert and then set the -SSL_SENT_SHUTDOWN flag (so that the session is considered good and will -be kept in the cache). -If successful, SSL_shutdown() will return 0. +=head1 TLS AND DTLS-SPECIFIC CONSIDERATIONS -If a unidirectional shutdown is enough (the underlying connection shall be -closed anyway), this first successful call to SSL_shutdown() is sufficient. +Shutdown for SSL/TLS and DTLS is implemented in terms of the SSL/TLS/DTLS +close_notify alert message. The shutdown process for SSL/TLS and DTLS +consists of two steps: -In order to complete the bidirectional shutdown handshake, the peer needs -to send back a close_notify alert. -The SSL_RECEIVED_SHUTDOWN flag will be set after receiving and processing -it. +=over 4 -The peer is still allowed to send data after receiving the close_notify -event. -When it is done sending data, it will send the close_notify alert. -SSL_read() should be called until all data is received. -SSL_read() will indicate the end of the peer data by returning <= 0 -and SSL_get_error() returning SSL_ERROR_ZERO_RETURN. +=item * -=head2 Peer closes the connection +A close_notify shutdown alert message is sent to the peer. -If the peer already sent the close_notify alert B it was -already processed implicitly inside another function -(L), the SSL_RECEIVED_SHUTDOWN flag is set. -SSL_read() will return <= 0 in that case, and SSL_get_error() will return -SSL_ERROR_ZERO_RETURN. -SSL_shutdown() will send the close_notify alert, set the SSL_SENT_SHUTDOWN -flag. -If successful, SSL_shutdown() will return 1. +=item * -Whether SSL_RECEIVED_SHUTDOWN is already set can be checked using the -SSL_get_shutdown() (see also L call. +A close_notify shutdown alert message is received from the peer. + +=back + +These steps can occur in either order depending on whether the connection +shutdown process was first initiated by the local application or by the peer. + +=head2 Locally-Initiated Shutdown + +Calling SSL_shutdown() on a SSL/TLS or DTLS SSL object initiates the shutdown +process and causes OpenSSL to try to send a close_notify shutdown alert to the +peer. The shutdown process will then be considered completed once the peer +responds in turn with a close_notify shutdown alert message. + +Calling SSL_shutdown() only closes the write direction of the connection; the +read direction is closed by the peer. Once SSL_shutdown() is called, +L can no longer be used, but L may still be used +until the peer decides to close the connection in turn. The peer might +continue sending data for some period of time before handling the local +application's shutdown indication. + +SSL_shutdown() does not affect an underlying network connection such as a TCP +connection, which remains open. + +=head2 Remotely-Initiated Shutdown + +If the peer was the first to initiate the shutdown process by sending a +close_notify alert message, an application will be notified of this as an EOF +condition when calling +L (i.e., L will fail and L will +return B), after all application data sent by the peer +prior to initiating the shutdown has been read. An application should handle +this condition by calling SSL_shutdown() to respond with a close_notify alert in +turn, completing the shutdown process, though it may choose to write additional +application data using L before doing so. If an application does +not call SSL_shutdown() in this case, a close_notify alert will not be sent and +the behaviour will not be fully standards compliant. + +=head2 Shutdown Lifecycle + +Regardless of whether a shutdown was initiated locally or by the peer, if the +underlying BIO is blocking, a call to SSL_shutdown() will return firstly once a +close_notify alert message is written to the peer (returning 0), and upon a +second and subsequent call, once a corresponding message is received from the +peer (returning 1 and completing the shutdown process). Calls to SSL_shutdown() +with a blocking underlying BIO will also return if an error occurs. + +If the underlying BIO is nonblocking and the shutdown process is not yet +complete (for example, because a close_notify alert message has not yet been +received from the peer, or because a close_notify alert message needs to be sent +but would currently block), SSL_shutdown() returns 0 to indicate that the +shutdown process is still ongoing; in this case, a call to L +will yield B or B. + +An application can then detect completion of the shutdown process by calling +SSL_shutdown() again repeatedly until it returns 1, indicating that the shutdown +process is complete (with a close_notify alert having both been sent and +received). + +However, the preferred method of waiting for the shutdown to complete is to use +L until L indicates EOF by returning +B. This ensures any data received immediately before the +peer's close_notify alert is still provided to the application. It also ensures +any final handshake-layer messages received are processed (for example, messages +issuing new session tickets). + +If this approach is not used, the second call to SSL_shutdown() (to complete the +shutdown by confirming receipt of the peer's close_notify message) will fail if +it is called when the application has not read all pending application data +sent by the peer using L. + +When calling SSL_shutdown(), the B flag is set once an +attempt is made to send a close_notify alert, regardless of whether the attempt +was successful. The B flag is set once a close_notify +alert is received, which may occur during any call which processes incoming data +from the network, such as L or SSL_shutdown(). These flags +may be checked using L. + +=head2 Fast Shutdown + +Alternatively, it is acceptable for an application to call SSL_shutdown() once +(such that it returns 0) and then close the underlying connection without +waiting for the peer's response. This allows for a more rapid shutdown process +if the application does not wish to wait for the peer. + +This alternative "fast shutdown" approach should only be done if it is known +that the peer will not send more data, otherwise there is a risk of an +application exposing itself to a truncation attack. The full SSL_shutdown() +process, in which both parties send close_notify alerts and SSL_shutdown() +returns 1, provides a cryptographically authenticated indication of the end of a +connection. + +This approach of a single SSL_shutdown() call without waiting is preferable to +simply calling L or L as calling SSL_shutdown() +beforehand makes an SSL session eligible for subsequent reuse and notifies the +peer of connection shutdown. + +The fast shutdown approach can only be used if there is no intention to reuse +the underlying connection (e.g. a TCP connection) for further communication; in +this case, the full shutdown process must be performed to ensure +synchronisation. + +=head2 Effects on Session Reuse + +Calling SSL_shutdown() sets the SSL_SENT_SHUTDOWN flag (see +L), regardless of whether the transmission of the +close_notify alert was successful or not. This makes the SSL session eligible +for reuse; the SSL session is considered properly closed and can be reused for +future connections. + +=head2 Quiet Shutdown + +SSL_shutdown() can be modified to set the connection to the "shutdown" +state without actually sending a close_notify alert message; see +L. When "quiet shutdown" is enabled, +SSL_shutdown() will always succeed and return 1 immediately. + +This is not standards-compliant behaviour. It should only be done when the +application protocol in use enables the peer to ensure that all data has been +received, such that it doesn't need to wait for a close_notify alert, otherwise +application data may be truncated unexpectedly. + +=head2 Non-Compliant Peers + +There are SSL/TLS implementations that never send the required close_notify +alert message but simply close the underlying transport (e.g. a TCP connection) +instead. This will ordinarily result in an error being generated. + +If compatibility with such peers is desired, the option +B can be set. For more information, see +L. + +Note that use of this option means that the EOF condition for application data +does not receive cryptographic protection, and therefore renders an application +potentially vulnerable to truncation attacks. Thus, this option must only be +used in conjunction with an application protocol which indicates unambiguously +when all data has been received. + +An alternative approach is to simply avoid calling L if it is known +that no more data is going to be sent. This requires an application protocol +which indicates unambiguously when all data has been sent. + +=head2 Session Ticket Handling + +If a client application only writes to a SSL/TLS or DTLS connection and never +reads, OpenSSL may never process new SSL/TLS session tickets sent by the server. +This is because OpenSSL ordinarily processes handshake messages received from a +peer during calls to L by the application. + +Therefore, client applications which only write and do not read but which wish +to benefit from session resumption are advised to perform a complete shutdown +procedure by calling SSL_shutdown() until it returns 1, as described above. This +will ensure there is an opportunity for SSL/TLS session ticket messages to be +received and processed by OpenSSL. =head1 QUIC-SPECIFIC SHUTDOWN CONSIDERATIONS -When using QUIC, SSL_shutdown() or SSL_shutdown_ex() causes any data written to -a stream which has not yet been sent to the peer to be written before the -shutdown process is considered complete. An exception to this is streams which -terminated in a non-normal fashion, for example due to a stream reset; only -streams which are non-terminated or which terminated in a normal fashion have -their pending send buffers flushed in this manner. This behaviour can be skipped -by setting the B flag; in this case, data -remaining in stream send buffers may not be transmitted to the peer. This flag -may be used when a non-normal application condition has occurred and the -delivery of data written to streams via L is no longer relevant. +When used with a QUIC connection SSL object, SSL_shutdown() initiates a QUIC +immediate close using QUIC B frames. + +SSL_shutdown() cannot be used on QUIC stream SSL objects. To conclude a stream +normally, see L; to perform a non-normal stream +termination, see L. + +SSL_shutdown_ex() may be used instead of SSL_shutdown() by an application to +provide additional information to the peer on the reason why a connection is +being shut down. The information which can be provided is as follows: + +=over 4 + +=item I + +An optional 62-bit application error code to be signalled to the peer. The value +must be in the range [0, 2**62-1], else the call to SSL_shutdown_ex() fails. If +not provided, an error code of 0 is used by default. + +=item I + +An optional zero-terminated (UTF-8) reason string to be signalled to the peer. +The application is responsible for providing a valid UTF-8 string and OpenSSL +will not validate the string. If a reason is not provided, or SSL_shutdown() is +used, a zero-length string is used as the reason. If provided, the reason string +is copied and stored inside the QUIC connection SSL object and need not remain +allocated after the call to SSL_shutdown_ex() returns. Reason strings are +bounded by the path MTU and may be silently truncated if they are too long to +fit in a QUIC packet. + +Reason strings are intended for human diagnostic purposes only, and should not +be used for application signalling. + +=back + +The arguments to SSL_shutdown_ex() are used only on the first call to +SSL_shutdown_ex() (or SSL_shutdown()) for a given QUIC connection SSL object. +These arguments are ignored on subsequent calls. + +These functions do not affect an underlying network BIO or the resource it +represents; for example, a UDP datagram provided to a QUIC connection as the +network BIO will remain open. + +Note that when using QUIC, an application must call SSL_shutdown() if it wants +to ensure that all transmitted data was received by the peer. This is unlike a +TLS/TCP connection, where reliable transmission of buffered data is the +responsibility of the operating system. If an application calls SSL_free() on a +QUIC connection SSL object or exits before completing the shutdown process using +SSL_shutdown(), data which was written by the application using SSL_write(), but +could not yet be transmitted, or which was sent but lost in the network, may not +be received by the peer. + +When using QUIC, calling SSL_shutdown() allows internal network event processing +to be performed. It is important that this processing is performed regularly, +whether during connection usage or during shutdown. If an application is not +using thread assisted mode, an application conducting shutdown should either +ensure that SSL_shutdown() is called regularly, or alternatively ensure that +SSL_handle_events() is called regularly. See L and +L for more information. + +=head2 Application Data Drainage Behaviour + +When using QUIC, SSL_shutdown() or SSL_shutdown_ex() ordinarily waits until all +data written to a stream by an application has been acknowledged by the peer. In +other words, the shutdown process waits until all data written by the +application has been sent to the peer, and until the receipt of all such data is +acknowledged by the peer. Only once this process is completed is the shutdown +considered complete. + +An exception to this is streams which terminated in a non-normal fashion, for +example due to a stream reset; only streams which are non-terminated at the time +SSL_shutdown() is called, or which terminated in a normal fashion, have their +pending send buffers flushed in this manner. + +This behaviour of flushing streams during the shutdown process can be skipped by +setting the B flag in a call to +SSL_shutdown_ex(); in this case, data remaining in stream send buffers may not +be transmitted to the peer. This flag may be used when a non-normal application +condition has occurred and the delivery of data written to streams via +L is no longer relevant. + +=head2 Shutdown Mode Aspects of how QUIC handles connection closure must be taken into account by applications. Ordinarily, QUIC expects a connection to continue to be serviced @@ -255,7 +384,8 @@ Call L with the return value B to find out the reason. It can occur if an action is needed to continue the operation for nonblocking BIOs. -It can also occur when not all data was read using SSL_read(). +It can also occur when not all data was read using SSL_read(), or if called +on a QUIC stream SSL object. This value is also returned when called on QUIC stream SSL objects. diff --git a/doc/man3/SSL_write.pod b/doc/man3/SSL_write.pod index e03cce2ad6..b8a7dcbbc7 100644 --- a/doc/man3/SSL_write.pod +++ b/doc/man3/SSL_write.pod @@ -66,6 +66,14 @@ operation is considered completed. The bytes are sent and a new write call with a new buffer (with the already sent bytes removed) must be started. A partial write is performed with the size of a message block, which is 16kB. +When used with a QUIC SSL object, calling an I/O function such as SSL_write() +allows internal network event processing to be performed. It is important that +this processing is performed regularly. If an application is not using thread +assisted mode, an application should ensure that an I/O function such as +SSL_write() is called regularly, or alternatively ensure that SSL_handle_events() +is called regularly. See L and L for more +information. + =head1 WARNINGS When a write function call has to be repeated because L