FIDOCRYPT(1) General Commands Manual FIDOCRYPT(1)

fidocrypt —
store a short secret in a file encrypted with U2F/FIDO

fidocrypt [-Edqv] [-r rpid] command [args...]

The fidocrypt utility stores a short secret in a file encrypted with U2F/FIDO security keys. The file is called a cryptfile, and any U2F/FIDO security key enrolled in it with fidocrypt enroll can be used with fidocrypt get to decrypt the enclosed secret. The secret may then be used for other purposes, such as a cgd(4) disk encryption key.

WARNING: fidocrypt is a work in progress. The file format is not yet stable.

Enable reading experimental cryptfile formats. Use with care only during development and testing.
Enable debug output: print various internal diagnostics to stderr. For additional (and very verbose) debug output including the raw U2F/CTAP transactions, which might include secrets, you may also set the FIDO_DEBUG environment variable.
Enable verbose output: print the vendor and product ids of the devices being queried to stderr.
Quiet — suppress messages to the tty prompting taps. Error messages may still be printed to stderr.
rpid
Set the relying party id.

WARNING: You should set this to a DNS name that identifies the purpose of the cryptfile, distinctly from any other U2F/FIDO usage to avoid cross-domain attacks. Don't set the relying party id to the domain name of any web site that you log into with U2F/FIDO.

Instead of the -r option, you can set the FIDOCRYPT_RPID environment variable; when both are specified, the -r option takes precedence.

-N username -u userid [-n nickname] [-s secretfile] cryptfile
Enroll a new U2F/FIDO security key in the cryptfile to encrypt a short secret with it.
  • If secretfile is specified, it will be read and its verbatim contents will be chosen as the secret. If secretfile is ‘-’, the secret will be read from stdin. It must be at most 65536 bytes long — fidocrypt is not meant for storing long secrets, only short secrets such as encryption keys.
  • Otherwise, if cryptfile already exists and no secretfile is specified, you will be prompted to tap a U2F/FIDO security key that is already enrolled in order to derive the secret that is already stored.
  • Otherwise, if cryptfile does not exist and no secretfile is specified, fidocrypt will generate a 32-byte string uniformly at random and use that as the secret and create a new cryptfile.

You will then be prompted to tap a new U2F/FIDO security key, not currently enrolled in cryptfile, to enroll.

WARNING: If you specify -s secretfile for a cryptfile that already has a secret stored in it, fidocrypt has no way to verify that it is the same secret as is already stored, so you may end up with a cryptfile that stores different secrets for different U2F/FIDO security keys. You should use this only in an application that has already gotten the stored secret with fidocrypt get and still has it in memory, in order to reduce the amount of device tapping.

The option -n nickname lets you specify a nickname for later display with fidocrypt list or use with fidocrypt unenroll.

The -N username and -u userid arguments are mandatory, but fidocrypt assigns them no particular meaning. U2F/FIDO devices with displays might show them on the display. You may also set the environment variables FIDOCRYPT_USERNAME and FIDOCRYPT_USERID instead; when both the environment variable and the command-line argument are specified, the command-line argument takes precedence.

-F format cryptfile
Get the secret stored in the cryptfile and print it to stdout in the specified format. You will be prompted to tap a U2F/FIDO security key that is enrolled in cryptfile. The supported formats are:
none
Don't actually print anything — only verify that the U2F/FIDO security key is enrolled.
raw
Print the raw bytes of the stored secret.
base64
Print the stored secret encoded in base64.

The -F option is mandatory — that way, you won't inadvertently either screw up your terminal or feed base64 data into a program that expects raw bytes.

cryptfile
List the credentials in cryptfile, by internally assigned numeric id and by the optional nickname passed to fidocrypt enroll.
[-i id] [-n nickname] cryptfile newname
Set a nickname for an existing U2F/FIDO security key enrolled in cryptfile.
[-i id] [-n nickname] cryptfile
Unenroll a U2F/FIDO security key from cryptfile so will no longer pass fidocrypt get. The enrollment may be specified by numeric id with -i as shown in fidocrypt list output, or by the nickname with -n that was passed to fidocrypt enroll.

  • An adversary without the cryptfile can't recover the stored secret, even if they have all of the enrolled U2F/FIDO devices.
  • An adversary without at least one of the U2F/FIDO devices enrolled in a cryptfile can't recover the secret stored in it, even if they have the cryptfile.
  • An adversary without at least one of the U2F/FIDO devices enrolled in a cryptfile can't fool fidocrypt get into passing with it.

N.B.: fidocrypt does not defend against a compromised host while cryptfile is being decrypted, and can't defend against any attacker who has access to the stored secret in the host's memory once decrypted.

fidocrypt also doesn't defend against a poorly designed U2F/FIDO device that exposes the public key in the credential id. Fortunately, credential ids are almost always either ciphertext themselves, encrypted with a secret key stored on the U2F/FIDO device, or a random input to a pseudorandom function under a secret key stored on the U2F/FIDO device.

Relying party id. Overridden by the -r option.
User id for fidocrypt enroll. Overridden by the -u option.
User name for fidocrypt enroll. Overridden by the -N option.

% export FIDOCRYPT_RPID=fidocrypt.example.com
% fidocrypt enroll -N Falken -u falken -n yubi5nano example.crypt
tap key to enroll; waiting...
% fidocrypt list example.crypt
1 yubi5nano
% fidocrypt get example.crypt
fidocrypt: specify an output format (-F)
Usage: fidocrypt get -F <format> <cryptfile>
% fidocrypt get -F base64 example.crypt
tap key; waiting...
yTpyXp1Hk3F48Wx3Mp7B2gNOChPyPW0VOH3C7l5AM9A=
% fidocrypt enroll -N Falken -u falken -n redsolokey example.crypt
tap a key that's already enrolled; waiting...
tap key to enroll; waiting...
% fidocrypt get -F base64 example.crypt
tap key; waiting...
yTpyXp1Hk3F48Wx3Mp7B2gNOChPyPW0VOH3C7l5AM9A=
% fidocrypt rename -n redsolokey example.crypt blacksolokey
% fidocrypt list example.crypt
2 blacksolokey
1 yubi5nano

Once you have created a cryptfile named cgd.crypt with several U2F/FIDO security keys enrolled, using ‘fidocrypt.example.com’ as the relying party id, create a cgd(4) parameters file that combines a password and the fidocrypt secret:

algorithm adiantum;
iv-method encblkno1;
keylength 256;
verify_method gpt;
keygen pkcs5_pbkdf2/sha1 {
    iterations 458588;
    salt AAAAgNXFkicvB33MhEfPLnXF2AI=;
};
keygen shell_cmd {
    cmd "fidocrypt -r fidocrypt.example.com get -F raw cgd.crypt";
};

This way, the cgd(4) disk can be opened only with the password and at least one of the U2F/FIDO security keys (and the cgd(4) parameters file).

The fidocrypt utility exits 0 on success, and >0 if an error occurs.
fidocrypt: no matching devices found
None of the available U2F/FIDO security keys is enrolled in the cryptfile when trying to retrieve the secret from it, or all of the available U2F/FIDO security keys are already enrolled when trying to enroll a new one.

pamu2fcfg(1)

Joseph Birr-Pixton, Abusing U2F to 'store' keys, https://jbp.io/2015/11/23/abusing-u2f-to-store-keys.html, 2015-11-23.

Rolf Lindemann, Vijay Bharadwaj, Alexei Czeskis, Michael B. Jones, Jeff Hodges, Akshay Kumar, Christiaan Brand, Johan Verrept, and Jakob Ehrensvärd, Client To Authenticator Protocol, https://fidoalliance.org/specs/fido-v2.0-ps-20170927/fido-client-to-authenticator-protocol-v2.0-ps-20170927.html, FIDO Alliance, 2017-09-27.

Dirk Balfanz, Alexei Czeskis, Jeff Hodges, J.C. Jones, Michael B. Jones, Akshay Kumar, Angelo Liao, Rolf Lindemann, and Emil Lundberg, Web Authentication: An API for accessing Public Key Credentials Level 1, https://www.w3.org/TR/webauthn-1/, World Wide Web Consortium, 2019-03-04.

fidocrypt works only with ECDSA over NIST P-256. It cannot be made to work with Ed25519. (Fortunately, essentially all U2F/FIDO devices on the market support ECDSA over NIST P-256.)

fidocrypt limits cryptfiles to be 1048576 bytes long, including metadata, credential ids, and ciphertexts. Usually, with a 32-byte secret, each U2F/FIDO security key requires under 200 bytes of storage in the file. fidocrypt is not meant for enrolling very large numbers of U2F/FIDO security keys — you are expected to use a primary key and a handful of backups stored in safe places.

User ids and relying party ids can't have NUL bytes.

Cryptfiles don't store nicknames for U2F/FIDO security keys, and fidocrypt doesn't support unenrolling keys.

December 24, 2020 NetBSD 9.1_STABLE