TLSPOOL_ASYNC_OPEN(3)

📦 version 0.9.7, in nixos 26.05

💅 TLSPOOL_ASYNC_OPEN 💅

okay so this is the tlspool_async_open(3) page from the Library Calls manual, and honestly? it's kind of the moment where your app first slides into the TLS Pool's DMs. let's get into it bestie ✨

🌸 NAME 🌸

tlspool_async_open — Open the TLS Pool for asynchronous communication. that's it, that's the whole vibe. 🎀

🦋 SYNOPSIS 🦋

#include <stdint.h>
#include <stdbool.h>

#include <unistd.h>

#include <tlspool/async.h>
#include <tlspool/commands.h>

bool tlspool_async_open (
       struct tlspool_async_pool *pool,
       size_t sizeof_tlspool_command,
       char *tlspool_identity,
       uint32_t required_facilities,
       char *socket_path);

look at her. five arguments, one bool, zero chill. 💅

✨ DESCRIPTION ✨

so tlspool_async_open() connects to the TLS Pool at the socket_path you hand it. and here's the tea: if that path starts with a slash, it's treated as a file name for a UNIX domain socket. the connection gets described in pool, and all your further operations work off of that. 🫶

and if you set it to NULL? no stress, it falls back — first it looks up socket_name in the configuration file, and lastly it uses TLSPOOL_DEFAULT_SOCKET_PATH. ✨

a few precautions get taken during this time, bestie, because we're responsible:

  • First, the sizeof_tlspool_command argument is normally set with the outcome of sizeof (struct tlspool_command), which the library will check to assure binary compatibility under separate distribution.
  • Second, it's possible to detect the TLS Pool version and the facilities available to us.

that second chunk of info ends up in the pool structure under pingdata. it's obtained with an initial synchronous exchange with the TLS Pool — but only when required_facilities is non-zero. the value is composed of the PIOF_FACILITY_xxx flags that an application needs. for use with TLS, it should be set to PIOF_FACILITY_STARTTLS, and it will then be required in the TLS Pool offering. 👑

a version and vendor of the TLS Pool is also exchanged, in a YYYYMMDD<tag>@<domain> textual format. the client usually provides its identity from the header files it sees by sending TLSPOOL_IDENTITY_V2 as the value for the tlspool_identity parameter. 🦋

okay so why are we doing this tlspool_ping(3) operation now, and synchronously? because it's habitually run by all applications, but only once, at the start of their work. synchronous access is quite simple at this time, and it rarely harms when it's only done during the setup phase. and if you insist, you can still set required_facilities to zero and skip this exchange entirely. 🙈

tl;dr: the tlspool_async_open() call handles most negotiation to improve the reliability of the client operation. when successful, everything should be plain sailing. ⛵

🌈 ASYNCHRONOUS AND EVENT-DRIVEN USE 🌈

the asynchronous API never allocates memory. read that again. the pool structure needs to be allocated by the caller. and it cannot be cleared until a matching call to tlspool_async_close() succeeds. no cap. 💀

the call to tlspool_async_open() is not itself asynchronous, let alone event-driven, but it prepares for these patterns immediately after it returns. the pool serves as a collection point for requests to the same link to the TLS Pool. 🎀

event loops can find the socket in the handle field of the pool structure. they can respond to reading offerings through the tlspool_async_process() function. ✨

to stop using the pool, use the tlspool_async_close() function. and before reaching that point? tlspool_async_request() can be used to send a request to the TLS Pool over the link. 🫶

💖 RETURN VALUE 💖

the function returns true on success or, in case of failure, it returns false and sets errno appropriately. 📌

note that there are local extensions founded in the com_err(3) system. error codes specific to the TLS Pool are in <tlspool/errortable.h> but other systems may also link in with the com_err(3) error system. iykyk 💅

🍓 ERRORS 🍓

None known to date. 😭 iconic honestly

👑 AUTHOR 👑

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

🔥 REPORTING BUGS 🔥

for any discussion, including about bugs, please use the mailing list found on http://lists.arpa2.org/mailman/listinfo/tls-pool. 🦋

and please read the software distribution's README, INSTALL and TODO files for information about the tlspool-daemon implementation status. fr fr, go read them. ⭐

Copyright © 2015-2019 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 configuration file option socket_name influences the path at which the TLS Pool is available — this is not read by the client library, and when it differs from the default path in TLSPOOL_DEFAULT_SOCKET_PATH, this function is used to inform the client library once, before calling any of the other client functions. 📌

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

and that's the whole page, bestie ✨ this lil manual page comes to you from ARPA2.net, dated March 2019 — slay, we love a vintage moment. 💅🎀🦋

📦 where this page comes from