gnutls_session_key_update(3)

📦
version 3.8.13 · 7 versions
, in alpine 3.22, alpine 3.23, alpine 3.24, arch rolling, fedora 43, fedora 44, ubuntu stonking

💖 gnutls_session_key_update 💖

okay bestie, so this one is from the gnutls manual — yes, that gnutls, the TLS library that's lowkey carrying half the internet's encrypted vibes ✨ — and today we're learning about gnutls_session_key_update, which is exactly what it sounds like: refreshing your session keys. it's giving "new year new me" but for cryptographic material. periodt. 🔐

✨ NAME ✨

gnutls_session_key_update — API function 👑

🌸 SYNOPSIS 🌸

#include <gnutls/gnutls.h>

int gnutls_session_key_update(gnutls_session_t session, unsigned flags);

🎀 ARGUMENTS 🎀

  • gnutls_session_t session — is a gnutls_session_t type. that's it, that's the whole description, she's self-describing and honestly? iconic. 💅
  • unsigned flags — zero of GNUTLS_KU_PEER. (yes babes, the original says "zero of" and not "zero or" — we are simply passing along the lore exactly as it was handed to us, no cap 🫶)

🦋 DESCRIPTION 🦋

so here's the tea: this function will update/refresh the session keys when the TLS protocol is 1.3 or better. the peer gets notified of the update by sending a message — so think of it less like a quiet little local refresh and more like a whole group-chat announcement that the keys are changing. 📣

because of that, this function should be treated similarly to gnutls_record_send() --i.e., it may return GNUTLS_E_AGAIN or GNUTLS_E_INTERRUPTED. so yeah, it can totally need you to come back around and try again. don't ghost it, just call it again. 🔁

when this flag GNUTLS_KU_PEER is specified, this function — in addition to updating the local keys — will ask the peer to refresh its keys too. mutual glow-up energy fr fr. ✨🤝✨

and if the negotiated version is not TLS 1.3 or better? this function will return GNUTLS_E_INVALID_REQUEST. she said "wrong era, not my problem." 💀

⭐ RETURNS ⭐

GNUTLS_E_SUCCESS on success, otherwise a negative error code. slay when it works, check the sign when it doesn't. 😌

🌈 SINCE 🌈

3.6.3 — an elder, honestly. been holding it down since way back. 👑

🙈 REPORTING BUGS 🙈

found a bug? don't be shy, tell the maintainers:

they want to know. seriously. 🐛💌

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. (free to share, just keep the receipts. we love a license that respects the vibe. 🫶)

🔥 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, visit:

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

and that's the whole page bestie!! 💖✨ go forth and rotate those keys responsibly. this one shipped as gnutls version 3.8.13, and it's the gnutls_session_key_update page itself — no date on the footer, she's mysterious like that 🎀 mwah, ily, bye!! 🦋💅

📦 where this page comes from