SSL_DO_HANDSHAKE(3ossl)

📦 version 3.5.0, in opensuse-leap 16.0

💅 SSL_DO_HANDSHAKE 💅

okay so bestie, we're in the OpenSSL manual — this is the SSL_DO_HANDSHAKE(3ossl) page, and it's literally the one that tells you how to do a TLS/SSL handshake. yes. the whole ✨connection-establishing✨ moment. let's go 🎀

🌸 NAME 🌸

SSL_do_handshake — perform a TLS/SSL handshake 🫶

✨ SYNOPSIS ✨

#include <openssl/ssl.h>

int SSL_do_handshake(SSL *ssl);

that's it. one function, one SSL *ssl, iconic behavior only 💅

🦋 DESCRIPTION 🦋

so SSL_do_handshake() will wait for an SSL/TLS handshake to take place. that's the vibe. it's giving "hold on, we're negotiating" 💖

if the connection is in client mode, the handshake will be started. main character energy fr fr 👑

lowkey important though: the handshake routines may have to be explicitly set in advance using either SSL_set_connect_state(3) or SSL_set_accept_state(3). don't skip that step bestie, i'm begging 🥺

💀 NOTES 💀

the behavior of SSL_do_handshake() depends on the underlying BIO. yep. it's a whole thing. let me break it down:

  • blocking BIO — SSL_do_handshake() will only return once the handshake has been finished or an error occurred. that's it, it just sits there until something happens. patient queen 🧘‍♀️
  • nonblocking BIO — SSL_do_handshake() will also return when the underlying BIO could not satisfy the needs of SSL_do_handshake() to continue the handshake. so it bails early, no drama. in this case a call to SSL_get_error() with the return value of SSL_do_handshake() will yield SSL_ERROR_WANT_READ or SSL_ERROR_WANT_WRITE. 📖✨

then the calling process must repeat the call after taking appropriate action to satisfy the needs of SSL_do_handshake(). 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. literally nothing to do, just vibe check it with select() 🌈
  • 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. so you gotta feed it or empty it first, iykyk 🍓

🔥 RETURN VALUES 🔥

the following return values can occur — pay attention bestie, these matter so much:

  • 0 — the TLS/SSL handshake was not successful but was shut down controlled and by the specifications of the TLS/SSL protocol. call SSL_get_error() with the return value ret to find out the reason. not a crash, just a polite shutdown 🙈
  • 1 — the TLS/SSL handshake was successfully completed, a TLS/SSL connection has been established. slay!! that's the good ending 💖🎉
  • <0 — the TLS/SSL handshake was not successful because a fatal error occurred either at the protocol level or a connection failure occurred. the shutdown was not clean. 💀 it can also occur if action is needed to continue the operation for nonblocking BIOs. call SSL_get_error() with the return value ret to find out the reason. yes, <0 does double duty, no cap 😭
ok real talk: whenever you get 0 or <0, run SSL_get_error() with ret. that's the move. always. 🫶

👑 SEE ALSO 👑

SSL_get_error(3), SSL_connect(3), SSL_accept(3), ssl(7), bio(7), SSL_set_connect_state(3)

go read those too, they're all part of the friend group bestie 💜

Copyright 2002-2020 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!! this was OpenSSL 3.5.0, dated 2026-09-25, manual SSL_DO_HANDSHAKE(3ossl) — mwah, go forth and handshake responsibly 💅✨🦋

📦 where this page comes from