SSL_SHUTDOWN(3ossl)

📦 version 3.5.0, in opensuse-leap 16.0

💖 NAME 💖

okay bestie, welcome to the OpenSSL manual page SSL_SHUTDOWN(3ossl) — it’s all about SSL_shutdown and SSL_shutdown_ex, aka how to shut down a TLS/SSL or QUIC connection. Yes, the manual name is folded in right here, we’re not copy-pasting the header line like some kind of boring little manpage gremlin. 💅

✨ SYNOPSIS ✨

#include <openssl/ssl.h>

int SSL_shutdown(SSL *ssl);

typedef struct ssl_shutdown_ex_args_st {
    uint64_t    quic_error_code;
    const char  *quic_reason;
} SSL_SHUTDOWN_EX_ARGS;

__owur int SSL_shutdown_ex(SSL *ssl, uint64_t flags,
                           const SSL_SHUTDOWN_EX_ARGS *args,
                           size_t args_len);

🦋 DESCRIPTION 🦋

So SSL_shutdown() shuts down an active connection represented by an SSL object. And bestie, listen: ssl MUST NOT be NULL. That is a hard no. 🫶

SSL_shutdown_ex() is the extended version of SSL_shutdown(). If args is non-NULL, it must point to a SSL_SHUTDOWN_EX_ARGS structure, and args_len must be set to sizeof(SSL_SHUTDOWN_EX_ARGS). The SSL_SHUTDOWN_EX_ARGS structure must be zero-initialized. If args is NULL, the behaviour is the same as passing a zero-initialised SSL_SHUTDOWN_EX_ARGS structure. Currently, all extended arguments relate to usage with QUIC, therefore this call functions identically to SSL_shutdown() when not being used with QUIC. ✨

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. 🌈

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. 👑

Important warning, no cap: SSL_shutdown() should not be called if a previous fatal error has occurred on a connection; i.e., if SSL_get_error(3) has returned SSL_ERROR_SYSCALL or SSL_ERROR_SSL. Do not do it. 🙈

🎀 TLS AND DTLS-SPECIFIC CONSIDERATIONS 🎀

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:

  • A close_notify shutdown alert message is sent to the peer. 💌
  • A close_notify shutdown alert message is received from the peer. 📬

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. It’s giving “who texted first” energy, but with cryptographic alerts. 😭

🌸 Locally-Initiated Shutdown 🌸

Calling SSL_shutdown() on an 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, SSL_write(3) can no longer be used, but SSL_read(3) 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. So yeah, you can still read for a bit — main character energy, but make it half-closed. 💅

SSL_shutdown() does not affect an underlying network connection such as a TCP connection, which remains open. That connection is lowkey just standing there, still open. 🧍

🌈 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 SSL_read(3) (i.e., SSL_read(3) will fail and SSL_get_error(3) will return SSL_ERROR_ZERO_RETURN), 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 SSL_write(3) 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. So like… please respond, bestie. 😭

⭐ 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 SSL_get_error(3) will yield SSL_ERROR_WANT_READ or SSL_ERROR_WANT_WRITE. 🌀

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 SSL_read(3) until SSL_get_error(3) indicates EOF by returning SSL_ERROR_ZERO_RETURN. 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). This is the slay way to do it. 👑

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 SSL_read(3). 💀

When calling SSL_shutdown(), the SSL_SENT_SHUTDOWN flag is set once an attempt is made to send a close_notify alert, regardless of whether the attempt was successful. The SSL_RECEIVED_SHUTDOWN 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 SSL_read(3) or SSL_shutdown(). These flags may be checked using SSL_get_shutdown(3). 🚩

🔥 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. 🔥

Danger, bestie: 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. Like, actual cryptographic proof. Do not skip that unless you know what you’re doing. 😭

This approach of a single SSL_shutdown() call without waiting is preferable to simply calling SSL_free(3) or SSL_clear(3) as calling SSL_shutdown() beforehand makes an SSL session eligible for subsequent reuse and notifies the peer of connection shutdown. So yes, one little SSL_shutdown() call is doing important social networking for your session. 🫶

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. ⚠️

💜 Effects on Session Reuse 💜

Calling SSL_shutdown() sets the SSL_SENT_SHUTDOWN flag (see SSL_set_shutdown(3)), 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. Reuse era. ♻️

🍓 Quiet Shutdown 🍓

SSL_shutdown() can be modified to set the connection to the “shutdown” state without actually sending a close_notify alert message; see SSL_CTX_set_quiet_shutdown(3). 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. So like… quiet, but make it risky. 💀

💅 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. Rude, honestly. 🙄

If compatibility with such peers is desired, the option SSL_OP_IGNORE_UNEXPECTED_EOF can be set. For more information, see SSL_CTX_set_options(3). 💅

Note, no cap: 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. Do not just turn it on because it makes the error go away. 😭

An alternative approach is to simply avoid calling SSL_read(3) 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. 🌸

🧚 Session Ticket Handling 🧚

If a client application only writes to an 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 SSL_read(3) 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. Read the room, get the tickets, slay the session resumption. 🧚

✨ QUIC-SPECIFIC SHUTDOWN CONSIDERATIONS ✨

Okay so QUIC is a whole different beastie, bestie, buckle up 🦋

When it's used with a QUIC connection SSL object, SSL_shutdown() kicks off a QUIC immediate close using QUIC CONNECTION_CLOSE frames.

Big warning though: SSL_shutdown() cannot be used on QUIC stream SSL objects. Nope. Not a thing. If you wanna wrap a stream up the normal way, go see SSL_stream_conclude(3); and if you need to do a non-normal stream termination, that's SSL_stream_reset(3)'s whole job.

SSL_shutdown_ex() may be used instead of SSL_shutdown() when your app wants to spill some extra tea to the peer about why the connection is being shut down. Here's what you can hand over:

  • quic_error_code — an optional 62-bit application error code to be signalled to the peer. The value must be in the range [0, 2**62-1], otherwise the call to SSL_shutdown_ex() fails. If you don't provide one, an error code of 0 is used by default.
  • quic_reason — an optional zero-terminated (UTF-8) reason string to be signalled to the peer. You (yes, you) are responsible for providing a valid UTF-8 string, and OpenSSL will not validate it. If a reason isn't provided, or if you just used SSL_shutdown(), a zero-length string is used as the reason. If you do provide one, the reason string is copied and stored inside the QUIC connection SSL object, so it doesn't need to stay allocated after the call to SSL_shutdown_ex() returns. Heads up: reason strings are bounded by the path MTU and may be silently truncated if they're 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. Like, they're for the vibes and the debugging, not for logic. 💅

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. On subsequent calls they're just ignored, no cap.

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.

And now the important bit 👑: when you're using QUIC, an application must call SSL_shutdown() if it wants to ensure that all transmitted data was actually received by the peer. This is unlike a TLS/TCP connection, where reliable transmission of buffered data is the operating system's whole personality. 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 couldn't yet be transmitted — or which was sent but lost in the network — may not be received by the peer. Yeah. Gone. 😭

Also: when using QUIC, calling SSL_shutdown() allows internal network event processing to be performed. It's important that this processing happens regularly, whether during connection usage or during shutdown. If an application isn't 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 openssl-quic(7) and SSL_handle_events(3) for more info. iykyk.

🧚 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 whole process is completed is the shutdown considered complete. Very thorough. Very demure.

The 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.

You can skip this flushing-streams-during-shutdown behaviour by setting the SSL_SHUTDOWN_FLAG_NO_STREAM_FLUSH flag in a call to SSL_shutdown_ex(); in that case, data remaining in stream send buffers may not be transmitted to the peer. This flag is your girl when a non-normal application condition has occurred and the delivery of data written to streams via SSL_write(3) is just no longer relevant. Let it go. 🍓

🌈 Shutdown Mode

Applications have to take aspects of how QUIC handles connection closure into account. Ordinarily, QUIC expects a connection to continue to be serviced for a substantial period of time after it's nominally closed. This is necessary to ensure that any connection closure notification sent to the peer was successfully received. But the consequence of that? A fully RFC-compliant QUIC connection closure process could take, like, the order of seconds. 💀 Which may be unsuitable for some applications — for example short-lived processes which need to exit immediately after completing an application-layer transaction.

So, two shutdown modes are available to users of QUIC connection SSL objects:

  • RFC compliant shutdown mode — this is the default behaviour. The shutdown process may take a period of time up to three times the current estimated RTT to the peer. It's possible for the closure process to complete much faster in some circumstances, but that cannot be relied upon. In blocking mode, the function will return once the closure process is complete. In nonblocking mode, SSL_shutdown_ex() should be called until it returns 1, indicating the closure process is complete and the connection is now fully shut down.
  • Rapid shutdown mode — in this mode, the peer is notified of connection closure on a best effort basis by sending a single QUIC packet. If that QUIC packet is lost, the peer won't know the connection has terminated until the negotiated idle timeout (if any) expires. 🙈 This will generally return 0 on success, indicating that the connection has not yet been fully shut down (unless it has already done so, in which case it will return 1).

If SSL_SHUTDOWN_FLAG_RAPID is specified in flags, a rapid shutdown is performed — otherwise an RFC-compliant shutdown is performed.

And cute little plot twist: if an application calls SSL_shutdown_ex() with SSL_SHUTDOWN_FLAG_RAPID, it can subsequently change its mind about performing a rapid shutdown by making a subsequent call to SSL_shutdown_ex() without the flag set. Character development. ✨

🫶 Peer-Initiated Shutdown

Sometimes an application would rather wait for a shutdown initiated by the peer instead of triggering one locally. No shame in that. To do it, call SSL_shutdown_ex() with SSL_SHUTDOWN_FLAG_WAIT_PEER specified in flags. In blocking mode, this waits until the peer initiates a shutdown or the connection otherwise becomes terminated for another reason. In nonblocking mode it exits immediately with either success or failure, depending on whether a shutdown has occurred.

If a locally initiated shutdown has already been triggered, or the connection has started terminating for another reason, this flag has no effect.

Also, SSL_SHUTDOWN_FLAG_WAIT_PEER implies SSL_SHUTDOWN_FLAG_NO_STREAM_FLUSH, since stream data cannot be flushed after a peer closes the connection. Stream data may still be sent to the peer in any time spent waiting before the peer closes the connection, though there's no guarantee of this. 🤷‍♀️

💜 Nonblocking Mode

SSL_shutdown() and SSL_shutdown_ex() block if the connection is configured in blocking mode. This may be overridden by specifying SSL_SHUTDOWN_FLAG_NO_BLOCK in flags when calling SSL_shutdown_ex(), which causes the call to operate as though in nonblocking mode. Slay.

⭐ RETURN VALUES ⭐

For both SSL_shutdown() and SSL_shutdown_ex() the following return values can occur:

  • 0 — the shutdown process is ongoing and has not yet completed. For TLS and DTLS, this means that a close_notify alert has been sent but the peer has not yet replied in turn with its own close_notify. For QUIC connection SSL objects, a CONNECTION_CLOSE frame may have been sent but the connection closure process has not yet completed. Unlike most other functions, returning 0 does not indicate an error. SSL_get_error(3) should not be called; it may misleadingly indicate an error even though no error occurred. Do not fall for it. 🚩
  • 1 — the shutdown was successfully completed. 🎉 For TLS and DTLS, this means that a close_notify alert was sent and the peer's close_notify alert was received. For QUIC connection SSL objects, this means that the connection closure process has completed.
  • <0 — the shutdown was not successful. Call SSL_get_error(3) with the return value ret 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(), or if called on a QUIC stream SSL object. This value is also returned when called on QUIC stream SSL objects.

🌸 SEE ALSO 🌸

SSL_get_error(3), SSL_connect(3), SSL_accept(3), SSL_set_shutdown(3), SSL_CTX_set_quiet_shutdown(3), SSL_CTX_set_options(3) SSL_clear(3), SSL_free(3), ssl(7), bio(7)

🎀 HISTORY 🎀

The SSL_shutdown_ex() function was added in OpenSSL 3.2. Newer than the rest, iconic behaviour.

Copyright 2000-2023 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (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 <https://www.openssl.org/source/license.html>.

And that's the whole page, bestie, we ate that 🍓✨ This lil beauty is from version 3.5.0, dated 2026-09-25, and it's SSL_SHUTDOWN(3ossl) — go forth and close your connections properly 💅💖

📦 where this page comes from