SSL_CLEAR(3ossl)

✨ SSL_CLEAR ✨

okay bestie, buckle up, because this is SSL_clear from the OpenSSL manual — third section of the manuals, 3ossl if you're keeping score 🎀 — and it's literally the "reset this thing so we can go again" function. 💅

---

🌸 NAME 🌸

SSL_clear — reset SSL object to allow another connection

---

🦋 SYNOPSIS 🦋

#include <openssl/ssl.h>

int SSL_clear(SSL *ssl);

---

💖 DESCRIPTION 💖

Reset ssl so it can do another connection. That's the whole vibe. All settings (method, ciphers, BIOs) are kept. She keeps her whole personality, she just gets a fresh start. ✨

---

🎀 NOTES 🎀

So SSL_clear is the glow-up-prep function — you use it to get an SSL object ready for a brand new connection. All the settings stay, yes, but there's a little side-quest happening in the background with the current SSL session, and you need to know about it, fr fr.

If a session is still open, it is considered bad and will be removed from the session cache, as required by RFC2246. Not me being dramatic, that's literally what the spec says. 👑

And a session counts as "open" if:

• SSL_shutdown(3) was not called for the connection, or
• at minimum, SSL_set_shutdown(3) was used to set the SSL_SENT_SHUTDOWN state.

Now, if a session was closed cleanly, then the session object will be kept and all settings corresponding. Which explicitly means — and this is the tea ☕ — that e.g. the special method used during the session will be kept for the next handshake. So 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_*_methods were chosen on startup. And that will might lead to connection failures — go read SSL_new(3) for a description of the method's properties, because the method is lowkey holding grudges from last time. 😭

🚫 Also: this function is not supported on QUIC SSL objects and returns failure if called on such an object. QUIC said no thank you, and we respect her boundaries.

---

💀 WARNINGS 💀

SSL_clear() resets the SSL object to allow for another connection. Sounds cute. It is not fully cute. 🫶

The reset operation however keeps several settings of the last sessions (some of these settings were made automatically during the last handshake). So it only makes sense for a new connection with the exact same peer that shares these settings, and it may fail if that peer changes its settings between connections. Rude of the peer, honestly, but here we are.

Instead, use this sequence to avoid such failures: c SSL_get_session(3); SSL_new(3); SSL_set_session(3); SSL_free(3) …or, if session reuse is not desired, just go the simple route: c SSL_free(3); SSL_new(3) No cap, that's the safe path. 🧚

---

🌈 RETURN VALUES 🌈

Here's what you might get back:

• 0 — the SSL_clear() operation could not be performed. Check the error stack to find out the reason. She's not telling you why, go ask the error stack. 🙈
• 1 — the SSL_clear() operation was successful. Slay. ✨

---

👀 SEE ALSO 👀

SSL_new(3), SSL_free(3), SSL_shutdown(3), SSL_set_shutdown(3), SSL_CTX_set_options(3), ssl(7), SSL_CTX_set_client_cert_cb(3)

---

⭐ COPYRIGHT ⭐

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

---

okay that's the whole page, you're so welcome 💜 this was version 3.5.9, dated 2026-09-29, filed under SSL_CLEAR(3ossl) — main character energy in the OpenSSL 3ossl manual series, periodt. 🎀✨