TLS_CONFIG_SET_SESSION_LIFETIME(3ssl)

📦 version 4.1.0, in opensuse-leap 16.0

💖 TLS_CONFIG_SET_SESSION_I(3) — Library Functions Manual 💖

okay bestie, welcome to the group chat where we talk about the Library Functions Manual page for tls_config_set_session_fd, tls_config_set_session_id, tls_config_set_session_lifetime and tls_config_add_ticket_key — aka the four functions that configure resuming of TLS handshakes. yes, the page name on the tin is a whole mouthful, and the function we're most obsessed with (tls_config_add_ticket_key) lives right here, so buckle up 🎀

✨ NAME ✨

tls_config_set_session_fd, tls_config_set_session_id, tls_config_set_session_lifetime, tls_config_add_ticket_key — configure resuming of TLS handshakes 🦋

🌸 SYNOPSIS 🌸

#include <tls.h>

int
tls_config_set_session_fd(struct tls_config *config, int session_fd);

int
tls_config_set_session_id(struct tls_config *config,
    const unsigned char *session_id, size_t len);

int
tls_config_set_session_lifetime(struct tls_config *config,
    int lifetime);

int
tls_config_add_ticket_key(struct tls_config *config, uint32_t keyrev,
    unsigned char *key, size_t keylen);

💅 DESCRIPTION 💅

tls_config_set_session_fd()

so this one sets a file descriptor that gets used to manage data for TLS sessions — and it's client only, no cap. the file descriptor you hand over must be a regular file, it must be owned by the current user, and the permissions have to be locked down so that literally only the owner can read and write it (0600). iykyk 🔐

if that file has a non-zero length, the client will try to read session data out of it and resume the previous TLS session with the server. and once a handshake goes through successfully, the file gets updated with the current session data — if there is any available, that is. main character behaviour tbh ✨

heads up bestie: you (the caller) are responsible for closing this file descriptor. and not whenever you feel like it — only after all the TLS contexts that were configured to use it have been freed via tls_free(). do not skip this step, the way that timing matters is giving responsibility 💀

tls_config_set_session_id()

sets the session identifier that the TLS server is gonna use when sessions are enabled — server only bestie. and by default? a random value is used, so if you do nothing, the vibes are already random and correct 🌈

tls_config_set_session_lifetime()

sets the lifetime used for TLS sessions — again, server only. now listen: if you pass a lifetime of zero, session support gets disabled. and guess what the default is? yep. zero. so sessions are off until you say otherwise, periodt 🫶

tls_config_add_ticket_key()

the icon itself 👑. this adds a key used for the encryption and authentication of TLS tickets — server only, obviously.

by default, keys are generated and rotated automatically based on their lifetime, so you don't have to do a thing. this function should only be used to synchronise the ticket encryption key across multiple processes — that's its whole thing, that's the assignment 💜

and a warning, fr fr: re-adding a known key will result in an error — unless it's the most recently added key. so like, read that twice bestie 😭

⭐ RETURN VALUES ⭐

these functions return 0 on success, or -1 on error. that's it, that's the whole vibe check 💫

🦋 SEE ALSO 🦋

🎀 HISTORY 🎀

tls_config_set_session_id(), tls_config_set_session_lifetime() and tls_config_add_ticket_key() appeared in OpenBSD 6.1. lowkey vintage ✨

tls_config_set_session_fd() appeared in OpenBSD 6.3. a little baby sibling, we love to see it 🍼

👑 AUTHORS 👑

  • Claudio Jeker <claudio@openbsd.org>
  • Joel Sing <jsing@openbsd.org>

absolute legends, no notes 💖

and that's the page bestie!! this one's from Debian, dated February 10, 2018, and it signs off as TLS_CONFIG_SET_SESSION_ID(3) — so like, go configure those sessions, stay encrypted, and don't forget to close that file descriptor 🫶💅🌸

📦 where this page comes from