gnutls_handshake(3)

💖 gnutls_handshake(3) 💖

okay bestie, gather round, because we're about to talk about the single most iconic function in the whole gnutls manual (yes, that's the manual name, we're in the gnutls house 🏠✨). this one is the moment, the main character entrance, the vibe check for your entire TLS session. let's go 🦋

---

✨ NAME ✨

gnutls_handshake — it's an API function, and it's giving "let me introduce you to your new encrypted bestie" 💅

---

🌸 SYNOPSIS 🌸

#include <gnutls/gnutls.h>

int gnutls_handshake(gnutls_session_t session);

---

🎀 ARGUMENTS 🎀

• gnutls_session_t session — bestie, it's a gnutls_session_t type. that's the whole vibe of this argument, no notes 🫶

---

👑 DESCRIPTION 👑

okay so. this function performs the handshake of the TLS/SSL protocol, and it initializes the TLS session parameters. that's it, that's the whole glow-up ✨

the non-fatal errors you should expect from this function are: GNUTLS_E_INTERRUPTED, GNUTLS_E_AGAIN, and GNUTLS_E_WARNING_ALERT_RECEIVED. and when you call this function for a re-handshake under TLS 1.2 or earlier, the non-fatal error code GNUTLS_E_GOT_APPLICATION_DATA may also show up. not me giving you a whole roster of plot twists 😭

so the former two (that's GNUTLS_E_INTERRUPTED and GNUTLS_E_AGAIN) interrupt the handshake procedure because the transport layer got interrupted, and the latter (GNUTLS_E_WARNING_ALERT_RECEIVED) happens because of a "warning" alert that was sent by the peer — and yes, it is always a good idea to check any received alerts, periodt 💅

on these non-fatal errors you just call this function again, until it returns 0. cf. gnutls_record_get_direction() and gnutls_error_is_fatal(). (translation: go read those two too, iykyk 👀)

and in DTLS sessions, the non-fatal error GNUTLS_E_LARGE_PACKET is also possible, and it indicates that the MTU should be adjusted. lowkey important, don't skip it 🔥

when this function is called by a server after a rehandshake request under TLS 1.2 or earlier, the GNUTLS_E_GOT_APPLICATION_DATA error code indicates that some data were pending prior to peer initiating the handshake. okay so plot twist number two 🌈

under TLS 1.3, when this function is called after a successful handshake, it is a no-op and always succeeds in server side; and in client side this function is equivalent to gnutls_session_key_update() with GNUTLS_KU_PEER flag. literally two completely different energies depending on who you are, it's giving duality 💀

this function handles both full and abbreviated TLS handshakes (resumption). for abbreviated handshakes, in client side, the gnutls_session_set_data() should be called prior to this function to set parameters from a previous session. in server side, resumption is handled by either setting a DB back-end, or setting up keys for session tickets. slay, so many ways to be iconic 👑

---

⭐ RETURNS ⭐

GNUTLS_E_SUCCESS on a successful handshake 🎉 otherwise a negative error code. that's the whole deal bestie, no cap.

---

🙈 REPORTING BUGS 🙈

found a bug? not the vibe, but okay, report it to <bugs@gnutls.org> 🐛

home page: https://www.gnutls.org 🏡

---

💜 COPYRIGHT 💜

Copyright © 2001-2023 Free Software Foundation, Inc., and others. 🫶

Copying and distribution of this file, with or without modification, are permitted in any medium without royalty provided the copyright notice and this notice are preserved.

---

🧚 SEE ALSO 🧚

the full documentation for gnutls is maintained as a Texinfo manual. if the /usr/share/doc/gnutls/ directory does not contain the HTML form, go visit:

https://www.gnutls.org/manual/

go read it bestie, it's giving knowledge 📚✨

---

🎀 and that's a wrap! this page came to you from gnutls version 3.8.13 💖 stay encrypted, stay hydrated, and call gnutls_handshake again until it returns 0 💅🦋🌸