Introducing the Himitsu keyring & password manager for Unix June 20, 2022 on Drew DeVault's blog

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 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 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?

A screenshot of a GTK+ dialog confirming the operation

proto=web user=jdoe password!=hunter2

You can also use hiq to add or delete keys, or incorporate it into a shell pipeline:

$ hiq -dFpassword

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 user=jdoe password!
query -d
key proto=web 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.

Additional frontends

Based on these protocols, a number of additional integrations are possible. Martijn Braam has written a nice GTK+ frontend called keyring:

A screenshot of the GTK+ frontend

There’s also a Firefox add-on which auto-fills forms for keys with proto=web:

Screenshot of himitsu-firefox

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
Hi sircmpwn! You've successfully authenticated, but I do not provide an interactive shell. Bye!
Connection to 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.

Zero configuration

Himitsu-aware software can discover your credentials and connection details without any additional configuration. For example, a mail client might look for proto=imap and proto=smtp and discover something like this:

proto=imap password! port=993 enc=tls
proto=smtp 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).

The cryptography

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.

Future plans

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

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:

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!

  1. This offers an improvement over pass, for example, by not storing the list of entries in plain text. ↩︎

Have a comment on one of my posts? Start a discussion in my public inbox by sending an email to ~sircmpwn/ [mailing list etiquette]

Articles from blogs I read Generated by openring

What's cooking on SourceHut? August 2022

Good morning! 785 new users are joining us on this cool August morning, for a total of 31,600 SourceHut users. Remember to be kind and patient with our new members as they learn how to use the software and work with the communities here. We only have a short…

via Blogs on Sourcehut August 16, 2022

Status update, August 2022

Hi all! This month I’ve been pondering offline-first apps. The online aspect of modern apps is an important feature for many use-cases: it enables collaboration between multiple people and seamless transition between devices (e.g. I often switch between my pe…

via emersion August 14, 2022

Go 1.19 is released!

Go 1.19 adds richer doc comments, performance improvements, and more.

via The Go Blog August 2, 2022