olastor/age-plugin-fido2-hmac

Age plugin to encrypt files with fido2 tokens using the hmac-secret extension and non-discoverable credentials.

age-plugin-fido2-hmac

⚠️ Consider this plugin to be experimental until the version v1.0.0 is published! ⚠️

---

🔑 Symmetrically encrypt files with fido2 keys that support the "hmac-secret" extension.

#️⃣ Unlimited generation of recipients/identities because generated fido2 credentials are stateless.

📝 See SPEC.md for more details.

---

Requirements

• age (>= 1.1.0) or rage
  • Prefer rage when encrypting to multiple fido2 tokens (because of #525).

Installation

git clone https://github.com/olastor/age-plugin-fido2-hmac.git
cd age-plugin-fido2-hmac
pip install .

Usage

Generate a new recpient/identity

$ age-plugin-fido2-hmac -n
Please insert your fido2 token now...
Please enter the PIN:
Please touch the authenticator.
Do you want to require a PIN for encryption/decryption? [y/N]: y
Do you want to create a secret identity? [y/N]: N
# -> prints either recipient ("age1fido2-hmac1...") or identity ("AGE-PLUGIN-FIDO2-HMAC-...")

• Don't loose your fido2 token (obviously)!
• You can only require a PIN if you have one set (obviously)!
• Keep identities secret and don't loose them!
• Keep track of which token matches which identity (if you have multiple fido2 tokens)!
• You cannot encrypt to a recipient without your fido2 token.*
• To decrypt files encrypted with a recipient use the magic identity (age-plugin-fido2-hmac -m).
• To decrypt files encrypted with an identity use the same identity.

Meaning of recipients/identities

* In contrast to asymmetric key pairs, this plugin uses symmetric encryption, meaning for both encryption and decryption the plugin needs to interact with the fido2 token. The difference between a recipient and an identity is nuanced. Basically identities isolate additional information required for decryption, while recipients treat that as public metadata. See SPEC.md for more details.

Encrypting/Decrypting

Encryption:

cat test.txt | rage -r age1fido2-hmac1... -o test.txt.enc

or

cat test.txt | rage -e -i identity.txt -o test.txt.enc

Decryption:

age-plugin-fido2-hmac -m > magic.txt
cat test.txt.enc | age -d -i magic.txt -o test-decrypted.txt

or

cat test.txt.enc | age -d -i identity.txt -o test-decrypted.txt

Choosing a different algorithm

By default, one of the following algorithms is picked (in that order): ES256, EdDSA, RS256. If you want the credential to use a specific algorithm, use the -a parameter:

age-plugin-fido2-hmac -a eddsa -n

Note that

• your authenticator may not support all algorithms,
• the length of recipient/identity strings can increase dramatically by using a different algorithm.

The default (in most cases) is "es256", which should provide the smallest recipient/identity strings.

age-plugin-fido2-hmac's Issues

Docs

CICD

• Lint/Test
• Release on new Tag

Encryption in absence of the token

The current design requires the fido2 token to be present for every operation, which is a big inconvenience. This is because the symmetric key (the HMAC challenge response) is directly used as the encryption key.

One way to solve this would be to use the symmetric key as a seed to generate an asymmetric key pair, and use the public key as the recipient. I chose to keep it simple and not do it because this exceeded my knowledge and the amount of complexity I was comfortable dealing with. However, if there's a well defined and secure way of deriving keypairs from 32 random bytes, the spec could in the future be changed to use that instead (while still keeping backwards compatibility to the current format).

Multi Device UX

• Improve messages
• Handle cases where controller implementations deviate from spec

Tests

Find a way to simulate a fido2 token somehow so that automatic e2e testing can be done.

Recipients

Improve UX for protected SSH private keys not exposing the pub key

Split sent body lines at 48 bytes