Database get and set utilities

The TLS Pool rests on databases for its dynamic data, and this means that entries can be changed on the fly, ready for the TLS Pool to pick them up on their next use. We provide elementary utilities to administrate these, and would not be surprised or displeased if future software inspired on them helps to get direct control through these databases.

The databases used by the TLS Pool are described in detail in the database documentation. This is explicitly intended for direct use by any applications that desire to influence the TLS Pool in a dynamic manner.

For use from scripts, we provide the get and set utilities described below. For use from LDAP configurations, we provide the PulleyBack module that plugs into the Pulley component of SteamWorks.

Usage: tlspool-dbget-localid tlspool.conf [user@]fqdn type [outfile.der]
 - tlspool.conf      is the configuration file for the TLS Pool
 - user@fqdn or fqdn is a network access identifier
 - type              X.509,OpenPGP,valexp,client,server,noP11,chained
 - outfile.der       optional output file for binary encoded public data
Since the public data is stored in a binary format, it will never be printed
on stdout; in absense of outfile.der the value is simply not output.

This utility works on localid.db and is meant for retrieving local credentials, selecting them with the local identity with typing and flags; and outputting the PKCS #11 URI on the command output and the binary credential in a file.

Usage: tlspool-dbset-localid tlspool.conf [user@]fqdn type [p11priv pubdata...]
 - tlspool.conf      is the configuration file for the TLS Pool
 - user@fqdn or fqdn is a network access identifier
 - type              X.509,OpenPGP,valexp,client,server,nop11,chained
 - p11priv           is a PKCS #11 URI string for the private key
 - pubdata           is a file name    string for the public key package
The pairs of p11priv and pubdata replace the old content.  An empty list of
pairs is nothing special; it replaces the old content with zero entries.

This utility works on localid.db and is meant for adding and removing local credentials, selecting them with the local identity with typing and flags; and inputting the PKCS #11 URI from the command line and the binary public credential from a file mentioned on the command line. The utility removes any former matches with the same selection criteria. When the PKCS #11 URI and public credential are not provided, this removal is all that is done; the utility can then be used for deletion of a local credential.

Usage: tlspool-dbget-disclose tlspool.conf selector
 - tlspool.conf      is the configuration file for the TLS Pool
 - selector              is a matcher for remote peer identities
The selector may take the following forms:
 - domain      matches remote peer DoNAI  completely but    with no username
 - .domain     matches remote peer DoNAIs ending in .domain with no username
 - .           matches any remote peer                      with no username
 - user@domain matches remote peer DoNAI  with the username given
 - @domain     matches remote peer DoNAIs with any username
 - @.domain    matches remote peer DoNAIs with any username ending in .domain
 - @.          matches remote peer DoNAIs with any username and any domain
The command walks all the way from the selector to its most abstract form, and
shows which entries exist in the disclose.db; it then picks the one that the
TLS Pool would use and prints the localid values for that one.

This utility works on disclose.db and is meant to retrieve information about disclose of local credentials to remote peers when using TLS in client mode. The tool will make a concrete-to-abstract search through the keys, which are not full-blown DoNAIs but, instead, DoNAI Selectors. Matches may propose one or more local identities, and are indeed keys for use with the localid.db where they help to retrieve the adjoining credentials.

Usage: tlspool-dbset-disclose tlspool.conf selector [[user@]domain...]
 - tlspool.conf      is the configuration file for the TLS Pool
 - selector              is a matcher for remote peer identities
 - user@domain or domain is a local client network access identifier
The list of client identities replaces the old list.  An empty list is nothing
special; it replaces the old content with zero entries.
The selector may take the following forms:
 - domain      matches remote peer DoNAI  completely but    with no username
 - .domain     matches remote peer DoNAIs ending in .domain with no username
 - .           matches any remote peer                      with no username
 - user@domain matches remote peer DoNAI  with the username given
 - @domain     matches remote peer DoNAIs with any username
 - @.domain    matches remote peer DoNAIs with any username ending in .domain
 - @.          matches remote peer DoNAIs with any username and any domain
When multiple selectors match a remote DoNAI, only the most concrete applies.
When no selector matches a remote DoNAI, the default policy is to reject.
An empty [[user@]domain] list is nothing special; it removes old content.

This utility works on disclose.db and is meant to update the information about disclose of local credentials to remote peers when using TLS in client mode.

Usage: tlspool-dbget-trust tlspool.conf flags aabbccdd [outfile.bin]
 - tlspool.conf is the configuration file for the TLS Pool
 - flags        selection of x509,pgp,revoke,pinned,client,server,notroot
 - aabbccdd     is an anchor's key in hexadecimal notation
 - outfile.bin  optional output file for binary encoded anchor data
Since the anchor data is stored in a binary format, it will never be printed
on stdout; in absense of outfile.bin the value is simply not output.

This utility works on the trust.db and is meant to retrieve information about trust to be placed into remote credentials by the TLS Pool.

Usage: tlspool-dbset-trust tlspool.conf flags aabbccdd valexp [infile.bin]
 - tlspool.conf is the configuration file for the TLS Pool
 - flags        selection of x509,pgp,revoke,pinned,client,server,notroot
 - aabbccdd     is an anchor's key in hexadecimal notation
 - valexp       is a validation expression for this entry
 - infile.bin   optional input file with binary encoded anchor data
When the infile.bin argument is absent, the corresponding entry is deleted.

This utility works on the trust.db and is meant to update information about trust to be placed into remote credentials by the TLS Pool.