NAME

fidocrypt —

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

SYNOPSIS

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

DESCRIPTION

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.

Common options

-d

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.

-E

Allow experimental cryptfile formats. Use with care only during development and testing.

-H

Disable the hmac-secret extension. By default, fidocrypt will automatically take advantage of hmac-secret on any device that supports it. This option is useful mainly for testing.

hmac-secret must be enabled or disabled for both fidocrypt enroll and fidocrypt get; disabling it for one and enabling it for the other will not work. When hmac-secret is disabled, or with devices that don't support it, only ES256 keys over P256 (that is, ECDSA with SHA-256 over the curve NIST P-256, also known as secp256r1) are supported.

-v

Verbose output: print the vendor and product ids of the devices being queried to stderr.

-q

Quiet — suppress messages to the tty prompting taps. Error messages may still be printed to stderr.

-r rpid

Set the relying party id.

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.

Commands

backup cryptfile backup

Create a backup copy of cryptfile at backup. This is like

cp
      cryptfile backup

if there are no concurrent changes to cryptfile, but fidocrypt backup will safely make a backup of a snapshot of cryptfile even if fidocrypt enroll,

fidocrypt
      rename

, etc., are happening at the same time.

enroll -N username -u userid [-n nickname] [-s secretfile] [-t type] 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, and then tap it again to verify the enrollment.

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 the U2F/FIDO security key. fidocrypt list will display the nickname, and you can use the nickname with fidocrypt unenroll. A nickname must be a UTF-8 string at most 128 bytes long with no control characters (Unicode general category Cc, code points U+0000 through U+001f and U+007f through U+009f).

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.

The option -t type specifies a credential type. The following types are supported:

es256-p256: ECDSA with SHA-256 over the curve NIST P-256.
ed25519: EdDSA over the curve edwards25519 with SHA-512.

By default, fidocrypt uses es256-p256; essentially all U2F/FIDO devices support it, and it is the only credential type supported by U2F-only devices.

get -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 format argument is mandatory — that way, you won't inadvertently either screw up your terminal or feed base64 data into a program that expects raw bytes.

list cryptfile

List the credentials in cryptfile, by internally assigned numeric id and by the optional nickname passed to fidocrypt enroll.

rename [-i id] [-n nickname] cryptfile newname

Set a nickname for an existing U2F/FIDO security key enrolled in cryptfile. The enrollment may be selected by numeric id with -i as shown in

fidocrypt
      list

output, or by nickname with -n.

unenroll [-i id] [-n nickname] cryptfile

Unenroll a U2F/FIDO security key from cryptfile so will no longer pass fidocrypt get. The enrollment may be selected by numeric id with -i as shown in fidocrypt list output, or by nickname with -n.

Security properties

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 both (a) exposes the public key in the credential id and (b) lacks support for the hmac-secret extension. 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.

ENVIRONMENT

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

EXAMPLES

$ export FIDOCRYPT_RPID=fidocrypt.example.com
$ fidocrypt enroll -N Falken -u falken -n yubi5nano example.crypt
tap key to enroll; waiting...
tap key again to verify; 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...
tap key again to verify; 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).

DIAGNOSTICS

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.

CAVEATS

fidocrypt works only with U2F devices, and with FIDO2 devices that either (a) support ECDSA over NIST P-256, or (b) support the hmac-secret extension. fidocrypt also only supports ECDSA over NIST P-256 and Ed25519 to date. (Fortunately, essentially all U2F/FIDO devices on the market as of 2020 support ECDSA over NIST P-256 — and it is even hard to find ones that support any other credential types such as RS256.)

fidocrypt is not meant for storing very large secrets or 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, to encrypt a 32-byte secret key for another purpose.

BUGS

User ids can't have NUL bytes.