TLSPOOL_LOCALID_SERVICE(3)

📦 version 0.9.7, in nixos 26.05

💅 TLSPOOL_LOCALID_SERVICE — library calls, section 3, bestie

okay so real talk: this is tlspool_localid_service, and she lives in section 3 of the manual (that's the Library Calls girldirectory, iykyk — not the shell commands one, not the file formats one, the library calls one 🎀). If you're the type who goes "wait what section was that in" — it's 3. three. tres. write it down.

✨ NAME ✨

tlspool_localid_service — the way you offer localid selection service to the TLS Pool. that's it, that's the whole vibe. she's a service-bestie, she shows up with localid picks, the TLS Pool says thank you 💖

🌸 SYNOPSIS 🌸

first things first, you gotta pull in the headers or nothing works, no cap:

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

then the actual call, and yes, copy it exactly, do not get creative with the argument order, I am begging 🙈:

int tlspool_localid_service (char *path,
       uint32_t regflags, int responsetimeout,
       char * (*cb) (lidentry_t *entry, void *data),
       void *data);

look at her. five arguments, one int return, one callback that hands you a lidentry_t *entry and your very own void *data back. the way that callback signature is just chef's kiss — she's literally going to call you back, bestie, so have your data ready 🦋

and that's where part one leaves us — the juicy stuff (like what path actually means and what those regflags are doing) is coming up next, so don't go anywhere 💜

💖 DESCRIPTION 💖

okay so bestie, tlspool_localid_service() is literally the function that registers you with the TLS Pool for callbacks that pick which local identity gets shown to remote peers. iconic behaviour, honestly. This whole thing exists because the TLS Pool sometimes needs to reveal an identity, and it cares deeply about privacy and about you having control over your online presence. so cute of it. 🫶

The whole intention behind tlspool_localid_service() is to let front-end programs pop up a little menu — yes, a popup with a menu — for choosing a local identity from the list, and to potentially add a brand-new local identity into the mix while they're at it. slay.

The TLS Pool accepts at most one active localid selection frontend at any time, and it will even protect a localid selection frontend from being replaced while it's in the middle of choosing a local identity. like, don't interrupt her, she's working. 💅 The limit to this protection is requested as a number of seconds in responsetimeout.

The callback function gets called with the opaque data value you supplied to tlspool_localid_service, plus a pointer to a lidentry_t structure that holds a bunch of fields to guide the selection process:

  • flags — holds flags PIOF_LIDENTRY_xxx, described down below 👇
  • maxlevels — tells you the number of generalisation steps the response may make from the concrete remote identity
  • timeout — the time value (as returned from the time() function) at which the selection process times out, and at which it may be replaced by a new registration from another TLS Pool client
  • localid — may be set to a suggested local identity when cb is called, and should be set to the selected local identity when it returns. To signal that no selection was made, set this field to an empty string
  • remoteid — may be set to the current remote identity when cb is called, and should be set to the (possibly generalised) remote identity when it returns — although this may not take more than maxlevels steps up

A single local identity selection callback may be preceded by zero or more database entries that might match, and those are what you can use to fill a menu. 🎀 These get passed in invocations to cb before the actual inquiry call to cb. The various calls to cb return NULL when they succeed, or an error description (plus a corresponding error number in errno) that gets relayed back to the TLS Pool and — after it bounces from there — to the calling program.

🌸 the regflags situation 🌸

The regflags set the behaviour while searching the database disclose.db for entries that map a remote identity to a list of local identities. It indicates which values may be passed without interaction with cb. By default — as long as a cb is registered through tlspool_lidentry_service() — all attempts to determine a local identity pass through cb. The PIOF_LIDENTRY_SKIP_xxx flags indicate which entries may be implicitly skipped when they all apply.

  • PIOF_LIDENTRY_SKIP_USER — indicates that part of the skip condition is that any username is not removed; variants with just a domain name are also considered skippable under this flag
  • PIOF_LIDENTRY_SKIP_DOMAIN_xxx — indicates whether the domain may be changed; use PIOF_LIDENTRY_SKIP_SAME and/or PIOF_LIDENTRY_SKIP_EUP to indicate 0 and 1 levels up from the concrete domain name; the _SUB variation combines PIOF_LIDENTRY_SKIP_ME and PIOF_LIDENTRY_SKIP_EUP
  • PIOF_LIDENTRY_SKIP_NOTROOT — indicates that the entry must not be the root domain entry; whether or not the username is removed is not of influence on the meaning of this flag
  • PIOF_LIDENTRY_SKIP_DBENTRY — indicates that the entry must be in the database; it's implied by all the above, but it has meaning when used on its own, since it permits skipping anything that is stored, without further restricting flags

These flags are used as regflags when calling tlspool_localid_service(); they're also returned in callbacks, where they refer to the remote identity selector. For example, PIOF_LIDENTRY_SKIP_USER indicates that the username part was skipped, and PIOF_LIDENTRY_SKIP_DOMAIN_ONEUP indicates that the domain name goes one up. ✨

  • PIOF_LIDENTRY_WANT_DBENTRY — used as part of the regflags to cause the invocation of cb for database entries at the most concrete level above the considered remoteid. These can be used to build up a menu, for instance in a data structure pointed to by the data parameter of cb

Although the skip selection could be made in the extension, it's less efficient that way — the interaction with the extension is forced into a sequence, and concurrent contenders may therefore need to wait for the extension while it's interacting with the user. so skipping user interaction when it's not needed is a whole advantage. 😌 When skipping, the disclose.db is used as a source, as if there is no active tlspool_localid_service() call active. Where the database holds multiple values for a given key, the first will be used.

🦋 the database-entry callbacks 🦋

Any invocations of cb to deliver a database entry come before the actual inquiry for a local identity. These invocations are only made when PIOF_LIDENTRY_WANT_DBENTRY is included in regflags, and the number of entries reported is 0 or more — basically variable. 📈 Any such database entry callbacks precede the normal callback and have:

  • PIOF_LIDENTRY_DBENTRY set
  • maxlevels set to the number of levels up for this entry (0 for concrete)
  • remoteid set to the remoteid entry found in disclose.db
  • localid set to an entry found in the database

The return to these database entries from cb should not be ERROR, but is otherwise ignored. TODO: return error/success?

🧚 the final / normal callback 🧚

The final/normal call to cb asks for a local identity, and it's different:

  • PIOF_LIDENTRY_DBENTRY is not set
  • maxlevels set to the number of permissible levels up (from 0 for concrete)
  • remoteid set to the concrete remote identity considered
  • localid set to the application-suggested local identity, or empty to signal that it's undefined

The entry returned value from the callback function cb should have:

  • flags can hold PIOF_LIDENTRY_xxx flags suitable for callback processing remoteid is the given concrete, or no more than maxlevels iterations up
  • localid is the concrete identity to disclose, unrelated to the suggested

In addition to the above interactions, the callback function cb can introduce flags to indicate what it wants to have done. These flags may relay an end user's requirements. 👑

💅 writing to the database 💅

PIOF_LIDENTRY_DBAPPEND and PIOF_LIDENTRY_DBINSERT indicate that the provided information should be added to the database — respectively at the end or the beginning of the disclose.db list of local identities for the given remote identity. When the entry is already available, the posision is not changed by default, but that will be done when PIOF_LIDENTRY_DBREORDER is set.

Changes to the database are part of a database transaction that is rolled back when the TLS handshake fails. This means that providing an identity that somehow fails to work is not going to be remembered for the next time. A simple restart of the TLS handshake therefore suffices to restart the user interaction and find an alternative. Note that it is assumed that the application that uses the TLS Pool will somehow report back on the failure, and the user should therefore not be surprised to be confronted with a question that he though had been stored. 🙈

Note that these flags lead to database activity; optimal efficiency requires that they're only set on cb responses that actually write to the database — because they return either: a remoteid less than maxlevels steps up with PIOF_LIDENTRY_DBINSERT or PIOF_LIDENTRY_DBAPPEND; a localid with PIOF_LIDENTRY_DBINSERT or PIOF_LIDENTRY_DBAPPEND if it is not yet setup in the database; a localid whose position must be updated under PIOF_LIDENTRY_DBREORDER.

⭐ PIOF_LIDENTRY_NEW ⭐

The cb-returned flag PIOF_LIDENTRY_NEW indicates in a response to a callback that the selected local identity should be available soon, but may not have come through yet. It instructs the TLS Pool to await its arrival before proceeding. ⏳

This flag is useful to end a callback (and thus free up the resource of the forced user-interaction sequence) while identities are being created in complex network infrastructures that may involve key generation, publication in identity showcases like DNS or LDAP, and whatever else is needed to have identities embedded in an infrastructure. like, go off, build your whole PKI, we'll wait. 🫡

TODO: PIOF_LIDENTRY_NEW is unimplemented behaviour; the flag is merely allocated. The result of using this is currently immediate return of DB_NOTFOUND. 💀

🌈 PIOF_LIDENTRY_ONTHEFLY 🌈

The cb-returned flag PIOF_LIDENTRY_ONTHEFLY indicates in a response to callback that the selected local identity should be setup as an on-the-fly identity. This type of identity is only available locally, and uses a configured credential to vouch for the on-the-fly generated identity. The manner in which this is done depends on the kind of credential to provide. ✨

These on-the-fly identities will disappear when the TLS Pool restarts, and possibly sooner. They are to be considered usable for one connection only, although temporary caching may be used to improve efficiency. In general, do not rely on the same certificate to stay available. Also, do not expect public visibility of this identity in LDAP, DNS, or other identity showcase. 🦋

Note that it should be assumed that these identities require special setup in the remote node; if it's a full-blown TLS Pool, it will not appreciate the locality of the identity, and demand more infrastructural confirmation in identity showcases. One example of its use however, is towards lame and old-fashioned remote services and towards highly structured local users, such as off-the-shelve browsers that require a HTTPS proxy. 😭

TODO: The flag PIOF_LIDENTRY_ONTHEFLY is unimplemented behaviour; the flag is merely allocated. For now, the response is the same as in lieu of configuration of a root key and cert, namely to return DB_NOTFOUND. 💀

🍓 the path parameter 🍓

The path parameter to tlspool_localid_service() points to the socket path for the TLS Pool. This function does not share in the general resources setup through tlspool_socket(3), because it's usually employed in isolated commands. For this 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). rude, but ok, she cleans up after herself. 🧹 The path may be set to NULL, in which case the TLSPOOL_DEFAULT_SOCKET_PATH is used to connect to the TLS Pool.

✨ RETURN VALUE ✨

As long as the function is successful, it does not return — instead it continues to keep the TLS Pool locked into its localid entry loop. 🔁 At some point however, the routine may return with an error code in errno and the return value -1. 😭

👑 AUTHOR

So who made this masterpiece? It was written by Rick van Rein of OpenFortress.nl, for the ARPA2.net project. Give the man his flowers 💐 like fr fr, iconic behavior.

🐛 REPORTING BUGS

Found a bug? First of all bestie, breathe. Second of all — for any discussion, including about bugs, please use the mailing list found on http://lists.arpa2.org/mailman/listinfo/tls-pool. That's the group chat, literally, come vibe with us 🌸

Also, please read the software distribution's README, INSTALL and TODO files for information about the tlspool-daemon implementation status. Like, do your reading first, iykyk 🙈 the TODO file especially is giving honesty.

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. That's the whole mission and honestly? slay 💅 This particular project has been sponsored in part by NCSC.

Shoutout to the funders, we love a project that's actually funded and actually cares about your control over your online presence 🫶

🔍 SEE ALSO

🎀 config file tea (the important context)

The configuration file option socket_name influences the path at which the TLS Pool is available. Here's the key detail bestie: 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. So it's a one-and-done vibe check, don't spam it ✨

The configuration file options dbenv_dir, db_localid and db_disclose together determine where the databases are located that play a role in the local identity service, and store any changes requested over it. Three options, one job, teamwork makes the dream work 💜

The configuration file options tls_onthefly_signcert and tls_onthefly_signkey are used to setup on-the-fly creation of identities. Identity creation, but make it ✨ spontaneous ✨

📚 where the actual docs live

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. Both languages, both eating, no crumbs left 🔥

Online resources may be found on the project home page, http://tlspool.arpa2.net. Bookmark it, thank me later 🌟

That's the whole page bestie, you made it to the end, we're so proud 🥹 Now go read README like I asked. 💅

Source/version: ARPA2.net, dated November 2015, page TLSPOOL_LOCALID_SERVICE(3) — vintage but still slaying, no cap. 🦋🎀

📦 where this page comes from