Himitsu is a new approach to storing secret information on Unix systems, such as passwords or private keys, and I released version 0.1 this morning. It’s available on Alpine Linux community and the Arch User Repository, with more distributions hopefully on the way soon.
So, what is Himitsu and what makes it special? The following video introduces the essential concepts and gives you an idea of what’s possible:
If you prefer reading to watching, this blog post includes everything that’s in the video.
What is Himitsu?
Himitsu draws inspiration from Plan 9’s factotum, but polished up and redesigned for Unix. At its core, Himitsu is a key/value store and a simple protocol for interacting with it. For example, a web login could be stored like so:
proto=web host=example.org user=jdoe password!=hunter2
Himitsu has no built-in knowledge of web logins, it just stores arbitrary keys and values. The bang (!) indicates that the password is a “secret” value, and the “proto” key defines additional conventions for each kind of secret. For proto=web, each key/value pair represents a form field on a HTML login form.
We can query the key store using the “hiq” command. For instance, we can obtain the example key above by querying for any key with “proto=web”, any “host”, “user”, and “password” value, and an optional “comment” value:
$ hiq proto=web host user password! comment?
proto=web host=example.org user=jdoe password!
You’ll notice that the password is hidden here. In order to obtain it, we must ask for the user’s consent.
$ hiq -d proto=web host user password! comment?
proto=web host=example.org user=jdoe password!=hunter2
You can also use hiq to add or delete keys, or incorporate it into a shell pipeline:
$ hiq -dFpassword host=example.org
A simple, extensible protocol
The protocol is a simple line-oriented text protocol, which is documented in the himitsu-ipc(5) manual page. We can also use it via netcat:
$ nc -U $XDG_RUNTIME_DIR/himitsu
key proto=web host=example.org user=jdoe password!
query -d host=example.org
key proto=web host=example.org user=jdoe password!=hunter2
The consent prompter also uses a standardized protocol, documented by himitsu-prompter(5). Based on this, you can implement new prompters for Qt, or the TTY, or any other technology appropriate to your system, or implement a more novel approach, such as sending a push notification to your phone to facilitate consent.
Based on these protocols, a number of additional integrations are possible. Martijn Braam has written a nice GTK+ frontend called keyring:
There’s also a Firefox add-on which auto-fills forms for keys with proto=web:
We also have a package called himitsu-ssh which provides an SSH agent:
$ hissh-import < ~/.ssh/id_ed25519
Enter SSH key passphrase:
key proto=ssh type=ssh-ed25519 pkey=pF7SljE25sVLdWvInO4gfqpJbbjxI6j+tIUcNWzVTHU= skey! comment=sircmpwn@homura
$ ssh-add -l
256 SHA256:kPr5ZKTNE54TRHGSaanhcQYiJ56zSgcpKeLZw4/myEI sircmpwn@homura (ED25519)
$ ssh firstname.lastname@example.org
Hi sircmpwn! You've successfully authenticated, but I do not provide an interactive shell. Bye!
Connection to git.sr.ht closed.
I hope to see an ecosystem of tools built around Himitsu to grow. New frontends like keyring would be great, and new integrations like GPG agents would also be nice to see.
Himitsu-aware software can discover your credentials and connection details
without any additional configuration. For example, a mail client might look for
proto=smtp and discover something like this:
proto=imap host=imap.migadu.com email@example.com password! port=993 enc=tls
proto=smtp host=imap.migadu.com firstname.lastname@example.org password! port=465 enc=tls
After a quick consent prompt, the software can load your IMAP and SMTP configuration and get connected without any manual steps. With an agent like himitsu-ssh, it could even connect without actually handling your credentials directly — a use-case we want to support with improvements to the prompter UI (to distinguish between a case where an application will view versus use your credentials).
Your key store is located at $XDG_DATA_HOME/himitsu/. The key is derived by mixing your password with argon2, and the resulting key is used for AEAD with XChaCha20+Poly1305. The “index” file contains a list of base64-encoded encrypted blobs, one per line, enumerating the keys in the key store.1 Secret keys are encrypted and stored separately in files in this directory. If you like the pass approach to storing your keys in git, you can easily commit this directory to a git repository, or haul it along to each of your devices with whatever other means is convenient to you.
Himitsu is written in Hare and uses cryptography primitives available from its standard library. Note that these have not been audited.
I’d like to expand on Himitsu in the future. One idea is to store your full disk encryption password in Himitsu and stick a subset of your key store into the initramfs, which you unlock during early boot, pull FDE keys out of, and then pre-authorize the keyring for your desktop session - which you’re logged in to automatically on the basis that you were pre-authorized during boot.
We also want to add key sharing and synchronization tools. The protocol could easily be moved to TCP and authorized with your existing key store key (we could make an ed25519 key out of it, or generate and store one separately), so setting up key synchronization might be as simple as:
$ hiq -a proto=sync host=himitsu.sr.ht
You could also use Himitsu for service discovery — imagine a key ring running on your datacenter LAN with entries for your Postgres database, SMTP credentials, and so on.
There are some other ideas that we could use your help with:
- himitsu-firefox improvements (web devs welcome!)
- Chromium support (web devs welcome!)
- Himitsu apps for phones (mobile devs welcome!)
- More key management frontends (maybe a TUI?)
- More security options — smart cards? U2F?
- hare-ssh improvements (e.g. RSA keys)
- PGP support
- Anything else you can think of
Please join us! We hang out on IRC in #himitsu on Libera Chat. Give Himitsu a shot and let us know what you think.
Alright, back to kernel hacking. I got multi-tasking working yesterday!
This offers an improvement over pass, for example, by not storing the list of entries in plain text. ↩︎