TLSPOOL_PIN_SERVICE(3)

📦 version 0.9.7, in nixos 26.05

💅 TLSPOOL_PIN_SERVICE(3) — Library Calls, but make it make sense ✨

okay so bestie, this is a page from TLSPOOL_PIN_SERVICE(3) in the Library Calls section, and it's literally about handing the TLS Pool a little popup so somebody can type their PIN. very specific, very niche, very iconic. let's go 🫶

✨ NAME ✨

tlspool_pin_service — offer PIN entry service to the TLS Pool 💳

🌸 SYNOPSIS 🌸

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

int tlspool_pin_service (char *path,
       uint32_t regflags, int responsetimeout_usec,
       void (*cb) (pinentry_t *entry, void *data),
       void *data);

like, that's the whole signature. five args. no notes. 👑

🦋 DESCRIPTION 🦋

so tlspool_pin_service() registers you with the TLS Pool for PIN entry callbacks. that's the whole vibe. you use this when getting at the PKCS #11 backend needs a PIN — which, ngl, is usually because you want a private or secret key. the intention here is to let front-end programs pop up a lil window for PIN entry. very main character of them 💅

the TLS Pool accepts at most one active PIN entry frontend at any time, periodt. and it will even protect a PIN entry frontend from being replaced while it's in the process of entering a PIN. the limit to that protection? that's what you request in responsetimeout_usec. 🎀

the callback function gets called with the opaque data value you handed to tlspool_pin_service, plus a pointer to a pinentry_t structure. that struct holds the usual PKCS #11 identifiers (but terminated with a NUL character) — token_manuf, token_model, token_serial and token_label. and on top of that there are some TLS-Pool-specific fields: prompt, pin, attempt, timeout_us and flags. here's the breakdown bestie:

  • prompt — can be shown to the user; it holds a string generated by the TLS Pool. 🗣️
  • pin — should be filled with the PIN entered, or an empty string. the string is assumed to be terminated with a NUL character. and the library code will wipe this field as soon as it's been submitted to the TLS Pool. 🧼
  • timeout_us — indicates the timeout, in microseconds, to be taken into account when entering the requested PIN. ⏱️
  • attempt — a counter that tells the user how many preceding authentication failures there have been for the currently requested PIN. you can use this to keep an eye on lockout counters, which are often implemented in a hardware token. 👀
  • flags — currently not used, but reserved for PIOF_PINENTRY_xxx flags. 🚧

the regflags parameter to tlspool_pin_service() is used for the initial registration to the PIN service — but in lieu of any defined flags in the current version, this value should be set to 0. yes, literally 0. don't get creative. 🙈

the path parameter to tlspool_pin_service() points to the socket path for the TLS Pool. heads up: this function does not share in the general resources setup through tlspool_socket(3), because it's usually employed in isolated commands. for that reason the function opens its own client socket, and will close it before ending — even when the thread running it is victimised to pthread_cancel(3). 💀 the path may be set to NULL, in which case TLSPOOL_DEFAULT_SOCKET_PATH is used to connect to the TLS Pool. slay, defaults. ✨

🔥 RETURN VALUE 🔥

as long as the function is successful, it does not return — it just keeps the TLS Pool locked into its PIN entry loop. it's giving "I live here now". 🫶

at some point though, the routine may return with an error code in errno and the return value -1. 😭

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

also please read the software distribution's README, INSTALL and TODO files for information about the tlspool-daemon implementation status. fr fr, they're right there. 📚

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

in the same file, pkcs11_pin can be setup with a fixed PIN, as an alternative to the use of this function. 🔑

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 💅 — brought to you by ARPA2.net, dated November 2015, and yes we're still thriving 🦋✨

📦 where this page comes from