TLSPOOL_CONTROL_REATTACH(3)

📦 version 0.9.7, in nixos 26.05

💅 TLSPOOL_CONTROL_REATTACH 💅

okay bestie, welcome to section 3 of the manual — Library Calls, the TLSPOOL_CONTROL_REATTACH page ✨ this one's short and sweet and it's literally about snatching a TLS session back and holding onto it, so let's get into it 🫶

✨ NAME ✨

tlspool_control_reattach — Detach a TLS connection from the current process

(yes babes, that's the official one-liner word-for-word — keep reading, the DESCRIPTION clears the whole vibe up 💀)

🦋 SYNOPSIS 🦋

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

int tlspool_control_reattach (uint8_t *ctlkey);

three includes, one function, one uint8_t * argument. that's the whole menu, no cap 🎀

🌸 DESCRIPTION 🌸

okay so here's the tea, bestie 🍓 tlspool_control_reattach() attaches a TLS session that is currently not attached to any TLS Pool client — and it attaches it to the calling TLS Pool client. main character behaviour, honestly 👑

and what that means is: control connections (including ones coming from other processes and other programs) can no longer reattach that same TLS session, not until they've used tlspool_control_detach() and made the ctlkey value known to the intended recipient process. so like, the door is locked and only you have the key 🔑

so what's ctlkey actually doing? it's the identifier, babes — the value of ctlkey is used to identify a TLS session from among the set of sessions that are not currently controlled by any TLS Pool client. it's a random byte string constructed during the tlspool_starttls(3) call. you can pass that value from the place where this call initiated the TLS session over to another process 🌈

and now the fork situation, listen up 🧚 if the flag PIOF_STARTTLS_FORK is set during this operation, then the TLS session is detached immediately. without that flag? it gets attached to the current TLS Pool client. two different vibes, one flag 💅

okay and now the part where you have to pay attention 😭 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. so, like, attached = comes down with the ship, detached = lives on 💀

and for the reverse move: you use the tlspool_control_detach() call to detach a TLS session from the current TLS Pool client. it also uses the ctlkey, but this time to identify the TLS session from among the set of sessions that are controlled by the current TLS Pool client. same key, different pile 🎀

⭐ RETURN VALUE ⭐

  • 0 — slay, it worked, success 💖
  • -1 — it did not work 😭 and errno is set appropriately, so go read it

👑 AUTHOR 👑

Written by Rick van Rein of OpenFortress.nl, for the ARPA2.net project. iconic. no notes 🫶

💀 REPORTING BUGS 💀

for any discussion — yes, including about bugs 🐛 — please use the mailing list found on http://lists.arpa2.org/mailman/listinfo/tls-pool. come chat, we don't bite ✨

also, please read the software distribution's README, INSTALL and TODO files for information about the tlspool-daemon implementation status 👀 (yes, the TODO file exists for a reason, be nice)

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 🏛️✨

🌈 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 🐍

online resources may be found on the project home page, http://tlspool.arpa2.net — go snoop, iykyk 🔥

and that's the whole page, bestie 🎀 brought to you by ARPA2.net, dated November 2015, living at the bottom of TLSPOOL_CONTROL_REATTACH(3) — go reattach something responsibly 💅💖

📦 where this page comes from