SSL_CLEAR(3)

📦 version 4.4.0, in alpine 3.24, arch rolling

💅 SSL_CLEAR(3) — like, the reset button for your SSL object

okay so this is from the Library Functions Manual, and we're talking about SSL_clear — the glow-up-reverse button that gets your SSL object ready to go again 🔁✨

🌸 NAME 🌸

SSL_clear — reset an SSL object so it can do another connection, bestie

🎀 SYNOPSIS 🎀

library libssl libcrypto

#include <openssl/ssl.h>

int
SSL_clear(SSL *ssl);

✨ DESCRIPTION ✨

So SSL_clear() resets ssl to allow another connection, and here's the tea: all settings are kept — the method, the ciphers, the BIOs, all of it just vibes there waiting for round two 💅

It's literally THE function you call to prep an SSL object for a new connection. But there's a little side quest 👀 — while all the settings stick around, the current SSL session gets handled too. If a session is still open, it's considered bad and gets yeeted out of the session cache, because RFC 2246 said so, periodt. And a session counts as "open" if SSL_shutdown(3) was never called for the connection, or if at least SSL_set_shutdown(3) was used to set the SSL_SENT_SHUTDOWN state 🫶

Now, if the session was closed cleanly? Different story — the session object is kept, along with all the settings that correspond to it. And that explicitly means, like, the special method used during the session sticks around for the next handshake 👑

So real talk: if the session was a TLSv1 session, an SSL client object will use a TLSv1 client method for the next handshake, and an SSL server object will use a TLSv1 server method — even if TLS_*_method()s were chosen on startup. And yeah, that might lead to connection failures 😭 (peep SSL_new(3) for a description of the method's properties, iykyk).

🔥 RETURN VALUES 🔥

Two possible outcomes, no in-between:

  • 0 — the SSL_clear() operation could not be performed 💀 check the error stack to find out the reason.
  • 1 — the SSL_clear() operation was successful 🎉 slay.

🦋 SEE ALSO 🦋

🌈 HISTORY 🌈

SSL_clear() first appeared in SSLeay 0.4.5b and has been available since OpenBSD 2.4 — truly a legacy icon 👑

💀 CAVEATS 💀

okay bestie, listen up because this part matters:

SSL_clear() resets the SSL object to allow for another connection. But the reset operation keeps several settings from the last session — and some of those settings were made automatically during the last handshake 🙈 It only makes sense for a new connection with the exact same peer that shares those settings, and it may fail if that peer changes its settings between connections. Not ideal, ngl.

Instead, use this sequence to avoid such failures:

SSL_get_session(3);
SSL_new(3);
SSL_set_session(3);
SSL_free(3);

Or, if session reuse isn't even the vibe you're going for, just do the simple thing:

SSL_free(3);
SSL_new(3);
💖 friendly reminder: keep the settings, keep the peer, keep the vibes — otherwise just start fresh, fr fr 💖

and that's the whole page, babes 🫶 this lil number's from Debian, dated June 8, 2025 — go forth and clear those SSL objects responsibly 🌸💅✨

📦 where this page comes from