README.md

age plugin for using a Tillitis TKey USB security key.

For X25519 ECDH key agreement it embeds and runs the tkey-device-x25519 app on the TKey. The Go package tkeyx25519 is used for communicating with the device app.

Note that this should still be considered work in progress (WIP). In particular, there is a possibility that we could need to make changes to tkey-device-x25519 for some reason. That said, I think current design and its implementation may be sound.

Changes to the source code of tkey-device-x25519 would change the binary, which would cause the identity of a TKey that runs it to be different. This would mean that the secret key no longer is the same, and that data encrypted for an identity based on the previous secret would be impossible to decrypt. It could be possible to work around this by first decrypting using an older version, and then encrypting again using a later.

Installing

The easiest way is to run the following, which installs the age-plugin-tkey binary in $GOPATH/bin (or $HOME/go/bin if GOPATH is not set).

go install github.com/quite/age-plugin-tkey/cmd/age-plugin-tkey@latest

age-plugin-tkey needs to be installed in a directory listed in PATH, so that age can find it.

See below for information about building yourself.

If you have not installed and used any other software for the TKey before, you might not be able to access the serial port of the TKey. One way to solve that is by executing the following as root:

cp -a 60-tkey.rules /etc/udev/rules.d/
udevadm control --reload
udevadm trigger

You could also add yourself to the group that owns /dev/ttyACM0 on your system.

Using

In the following we create a new random identity (private key) for ourselves and learn about the corresponding recipient (public key). Then we encrypt a message to ourselves using that recipient, and proceed to decrypt it using our identity. The LED on the TKey will shine yellow when the X25519 app has been loaded, and will flash in the same colour when it needs to be touched (upon decryption).

$ age-plugin-tkey --generate --output my-identity
# recipient: age1xuqv8tq5ttkgwe3quys0dfwxv6zzqpemvckjeutudtjjhfac2f9q6lc377
$ echo "remember to fix all bugs!" | age --encrypt -a -r age1xuqv8tq5ttkgwe3quys0dfwxv6zzqpemvckjeutudtjjhfac2f9q6lc377 >note-to-self
$ age -i my-identity --decrypt ./note-to-self
remember to fix all bugs!

After running this, the file my-identity will contain a line beginning with AGE-PLUGIN-TKEY- which holds parameters that were used on the TKey when generating the identity, and will be used again to recreate it before computing a shared key (to be used for decryption of the message). The file my-identity file should be treated as a secret, even though the full identity is a combination of data in this file and key material on the TKey -- which is unique to each TKey, and never leaves the hardware. There is actually no storage on the TKey, you can learn more about how it derives secret keys here: https://dev.tillitis.se/intro/#measured-boot--secrets

The file also has some comment lines beginning with # with more information about the identity. Especially useful is the recipient, which is used to encrypt data which then can be decrypted this precise identity.

You can generate as many identities as you want, each will be bound to the unique TKey it was generated with, and have its own corresponding recipient. The recipient is not a secret, on the contrary it is what you give to your friend so they can encrypt their message for you. The corresponding identity and the same physical TKey device are both needed in order to decrypt it. The age option -i/--identity takes a file, which can contain one or more identity lines.

The generated identity will by default cause TKey to require physical touch before computing a shared key (doing ECDH). You can pass the flag --no-touch to generate an identity that does not.

To run the plugin towards an emulated TKey in QEMU instead of real hardware, you can set the environment variable AGE_TKEY_PORT to QEMU's char-device (shown when QEMU starts up). Before running age, do something like export AGE_TKEY_PORT=/dev/pts/22.

Multiple recipients

Files encrypted for multiple recipients are indeed handled by this plugin. There is however one gotcha which might be slightly confusing and annoying at times. If your TKey identity requires touch (which they do by default), then you may have to touch your TKey more than one time when decrypting a single piece of data that has been encrypted for more than one recipient.

The best you can do to avoid this when encrypting for multiple recipients using age is to pass any TKey recipient with the first -r. Also, when decrypting, if the identity file you're passing with -i has multiple identities, then make sure any TKey identity line comes last. This will avoid "unnecessary" touching if the data can be decrypted using an earlier non-TKey identity. Below follows a more in-depth explanation.

Recipients for identities based in TKey have the same format as recipients for identities generated by the native age-keygen. This ought to be because TKey also use native X25519 keys (which is also why we only needed to implement Unwrap of a "file key", not Wrap).

The consequence is that when you are decrypting using a TKey identity (-i) and the data is encrypted for multiple recipients, then an attempt to use the TKey (for ECDH) will be made for each native X25519 recipient, in the order they were passed with -r (but I guess the order could vary depending the implementation). Consider the following procedure of encrypting and then decrypting a message, some data:

age-keygen -o some-agekeygen-id
# Make a note of the RECIPIENT (public key) for this some-agekeygen-id

age-plugin-tkey --generate -o my-tkey-id
# Make a note of the RECIPIENT (public key) for this my-tkey-id

printf "some data\n" | age -r SOME-AGEKEYGEN-RECIPIENT -r MY-TKEY-RECIPIENT --encrypt -o ./ciphertext

age -i my-tkey-id --decrypt ./ciphertext

When decrypting, two recipients are found to be native X25519, and both have to be tried using the passed TKey identity (-i). The first recipient (non-TKey) passed using -r will be tried first. You will have to touch your TKey, but decryption will fail silently. Then the second recipient (TKey) will be tried. You will have to touch TKey again, but this time decryption will succeed.

The reason for why decryption have to be attempted is because the recipient-stanza does not simply contain the public key recipient corresponding to an identity, so no simple check can be made. The recipient-stanza contains an ephemeral share and a file-key which is wrapped using a key derived from that. To unwrap the file-key, the shared secret must first be computed using ECDH. Only if this secret is correct can the key derived from it successfully unwrap the file-key, which can then decrypt the message. So if a message is encrypted for multiple native X25519 recipients, then for each one of them ECDH has to be run on the TKey -- which then has to be touched -- until the file-key can be unwrapped (if at all possible).

One can imagine another implementation where the TKey device app does not only do X25519 ECDH, but instead more of the age cryptography is run on it. The device app running on the TKey could then receive the wrapped file-key along with all the recipients, and would try them one by one until it successfully unwraps the file-key (or fails to). It would execute multiple ECDH, but could be made to require touching only once for this whole operation.

Building

For ease of installing and building the age-plugin-tkey Go program, we keep the device app binary committed to the repository. So if you don't want or need to rebuild or work on the device app, you can just build with:

make

For reproducibility the X25519 device app is typically built in a container, thus locking down the toolchain, and using specific versions of dependencies. Because if one single bit changes in the app.bin that will run on the TKey (for example due to a newer clang/llvm), then the identity (private/public key) of it will change.

You can use build-in-container.sh to build both the device app and age-plugin-tkey using our own container image (see Containerfile). The clone of this repo that you're sitting in will be mounted into the container and built, but dependencies will be freshly cloned as they don't exist inside (it runs build.sh there). podman is used for running the container (packages: podman rootlesskit slirp4netns).

The file internal/tkey/x25519-hashes.sha512 contains hashes of known versions of the device app binary, as built using our container image (which currently has clang 17). We keep the device app binaries committed to the repository. A tagged version of age-plugin-tkey currently uses one specific version of that binary, which is embedded during build, see internal/tkey/tkey.go.