himitsu

Himitsu is a WORK IN PROGRESS system for storing secrets.

The following information is provisional.

Himitsu for users

If you're using a Linux system with PAM and Wayland, then himitsu installation is as simple as installing the package. It'll automatically unlock your keys when you log in, and adding and retrieving secrets is automatic for compatible programs.

If you prefer a more hands-on or build-it-yourself approach, read on.

Starting the daemon

On POSIX systems:

export HIMITSU_SOCKET=$(himitsud -dc hiprompt-wl)

This will start the himitsu daemon in the background (-d) using the Wayland prompter as the consent command. Add this to your ~/.profile or equivalent. A Unix socket will become available at $HIMITSU_SOCKET.

Key templates

Key templates are inspired by Plan 9's ndb and factotum, and are the basic language for interacting with himitsu. A key template consists of a list of space-separated key-value pairs. An example would be:

proto=irc server=irc.freenode.net nick=ddevault password!

The use of ! with the password key indicates that it is a secret key. Regardless, a key template may include such values, for example when inserting new keys:

proto=irc server=irc.freenode.net nick=ddevault password!=hunter2

Values which contain spaces or quotation marks should be single-quoted. Two single quotes in a row become one literal single quote.

password!='you know, ''hunter 2'' is a bad password'

The resulting value is you know, 'hunter 2' is a bad password.

Keys can additionally have a ? instead of a !, indicating a key which needs to be provided by the user. For example, let's say your software is a web browser and your user needs to fill out a login form. You might use the following key template to represent this:

proto=https host=example.org path=/login username? password!

Retreiving a secret

Let's extend that example. If you send this key template to himitsu, it'll search the key store for any matching keys - that is, ones where proto, host, and path respectively are equal to https, example.org, and /login, and where a username and password field are both provided.

If such a key is found, the user is prompted to consent to your use of the secret. If no such key is found, the user is prompted to fill in the missing details first. Finally, the secret is returned to the application.

This can also be done via the CLI:

$ hictl get "proto=https host=example.org path=/login username? password!"
Enter username for example.org: ddevault
Enter password for example.org: [echo disabled]
proto=https host=example.org path=/login username=ddevault password!=hunter2

Adding a secret

A similar add operation is available, which adds a key and prompts for any necessary information, but does not return the secrets back to the application.

$ hictl add "proto=https host=example.org path=/login username? password!"
Enter username for example.org: ddevault
Enter password for example.org: [echo disabled]
proto=https host=example.org path=/login username=ddevault password!

Querying keys

Applications (or users) can also query for keys without reading their secrets, which is an unprivileged operation. For example, to check if the user has a key for the same HTTP form, you could submit the following query:

proto=https host=example.org path=/login username password

In this case, the omission of username and password adds search criteria that state that the key store must have a key with both of those fields, and they cannot be empty. The following results may be returned:

proto=https host=example.org path=/login username=ddevault password!
proto=https host=example.org path=/login username=sircmpwn password!

It looks like this user has two accounts on example.org. Your application may want to present a UI for disambiguation.

The equivalent CLI is:

$ hictl query proto=https host=example.org path=/login username password
proto=https host=example.org path=/login username=ddevault password!
proto=https host=example.org path=/login username=sircmpwn password!

Authenticating connections

If your application supports it, himitsu can establish authenticated connections on your behalf. In such cases, your application code never has to handle the secrets at all. Let's say you want to open an authenticated IMAP connection, for example. The application submits a connection RPC request with the following query:

proto=imaps host=mail.example.org auth=login username=ddevault password!

The himitsu daemon looks up the secret and starts up the himitsu-imaps helper program, then writes the unredacted key to the helper's stdin. It establishes the connection, authenticates, and then returns a file descriptor to the caller which represents the authenticated TCP connection, and, in the case of IMAP, a list of server capabilities which the client would otherwise be unable to see.

The precise nature of these exchanges varies from protocol to protocol. Another example would be with the HTTP form we've been using as examples in other sections. proto could be https+multipart/form-data. An SSH client could set proto=ssh.

This feature is not available with the CLI.

libhiauth

libhiauth is the recommended mechanism for applications to communicate with himitsu. It can handle secret storage, queries, retrieval, and authenticated connections, on your behalf.

Compatibility

libsecret provides an implementation of GNOME's libsecret which uses himitsu RPC instead of dbus. For those wishing to use dbus, hidbusd provides a dbus service that can communicate to himitsu.