TLSPOOL_CONTROL_DETACH(3)

📦 version 0.9.7, in nixos 26.05

💅 TLSPOOL_CONTROL_DETACH(3) — like, the library-calls one, bestie

okay so real talk, this is a page from the Library Calls section of the manual, and it's about one very specific little function. buckle up 🎀

✨ NAME ✨

tlspool_control_detach — detaches a TLS connection from the current process. that's the whole vibe. she lets go. 🦋

🌸 SYNOPSIS 🌸

#include <stdint.h>
#include <tlspool/commands.h>
#include <tlspool/starttls.h>

int tlspool_control_detach (uint8_t *ctlkey);

like, you include those three headers, and then it's one function call taking a uint8_t * named ctlkey. slay, that's it 💅

💖 DESCRIPTION 💖

so tlspool_control_detach() explicitly detaches a TLS session from the controlling connection to the TLS Pool. think of it as her moving out but keeping her keys 🔑

the tea is this: once she's detached, any control connection can reattach — and yes, that includes ones from other processes and other programs — using the ctlkey for the TLS session, provided that this value is passed to them through an application mechanism. so you gotta hand over the key yourself, no cap. 🫶

the value of ctlkey is what identifies a TLS session from among the set of sessions controlled by the current TLS Pool client. and where does that ctlkey come from? it's a random byte string constructed during the tlspool_starttls(3) call. iconic. ✨

okay and here's the important bit — if the flag PIOF_STARTTLS_FORK is set during this operation, then the TLS session is detached immediately. without that flag, it stays attached to the current TLS Pool client. iykyk 🌈

⚠️ lowkey crucial: when the current TLS Pool client closes its connection — for instance because the last process dies that held the connection to the TLS Pool open — then all attached TLS sessions will be closed by the TLS Pool. but 💀 TLS sessions in detached state will continue to run. that's the whole point of detaching, bestie.

and the tlspool_control_reattach() call can be used to re-attach a detached TLS session to a TLS Pool client, possibly in another process. this also uses the ctlkey, but this time it identifies the TLS session from among the set of sessions that are not controlled by any TLS Pool client. so like, the opposite pile of sessions. cute 🌸

⭐ RETURN VALUE ⭐

  • returns 0 on success 🎉
  • if an error occurs, it returns -1 and errno is set appropriately 😭

👑 AUTHOR 👑

written by Rick van Rein of OpenFortress.nl, for the ARPA2.net project. king behavior fr fr 💜

🙈 REPORTING BUGS 🙈

for any discussion, including about bugs, please use the mailing list found on http://lists.arpa2.org/mailman/listinfo/tls-pool. yes, even the bug talk goes on the list, that's the group chat 📬

also please read the software distribution's README, INSTALL and TODO files for information about the tlspool-daemon implementation status. do your reading first, bestie 🍓

Copyright © 2015 Rick van Rein, ARPA2.net.

ARPA2 is funded from InternetWide.org, which in turns receives donations from various funding sources with an interest in a private and secure Internet that gives users control over their online presence. this particular project has been sponsored in part by NCSC. very demure, very public-interest 💖

🧚 SEE ALSO 🧚

the TLS Pool API is documented in the include file <tlspool/commands.h> and <tlspool/starttls.h> for C, and the tlspool.py module for Python. two languages, one API, we love to see it 🌈

online resources may be found on the project home page, http://tlspool.arpa2.net. go click around 💅

k that's the whole page!! brought to you by ARPA2.net, hanging out in the November 2015 era, and the page you just read was TLSPOOL_CONTROL_DETACH(3) — stay detached, stay iconic, mwah 🫶💜

📦 where this page comes from