fido2-cred(1)

1FIDO2-CRED(1)             BSD General Commands Manual            FIDO2-CRED(1)
2

NAME

4     fido2-cred — make/verify a FIDO 2 credential
5

SYNOPSIS

7     fido2-cred -M [-dhqruv] [-c cred_protect] [-i input_file]
8                [-o output_file] device [type]
9     fido2-cred -V [-dhv] [-c cred_protect] [-i input_file] [-o output_file]
10                [type]
11

DESCRIPTION

13     fido2-cred makes or verifies a FIDO 2 credential.
14
15     A credential type may be es256 (denoting ECDSA over NIST P-256 with
16     SHA-256), rs256 (denoting 2048-bit RSA with PKCS#1.5 padding and
17     SHA-256), or eddsa (denoting EDDSA over Curve25519 with SHA-512).  If
18     type is not specified, es256 is assumed.
19
20     When making a credential, the authenticator may require the user to au‐
21     thenticate with a PIN.  If the -q option is not specified, fido2-cred
22     will prompt the user for the PIN.  If a tty is available, fido2-cred will
23     use it to obtain the PIN.  Otherwise, stdin is used.
24
25     The input of fido2-cred is defined by the parameters of the credential to
26     be made/verified.  See the INPUT FORMAT section for details.
27
28     The output of fido2-cred is defined by the result of the selected opera‐
29     tion.  See the OUTPUT FORMAT section for details.
30
31     If a credential is successfully created or verified, fido2-cred exits 0.
32     Otherwise, fido2-cred exits 1.
33
34     The options are as follows:
35
36     -M      Tells fido2-cred to make a new credential on device.
37
38     -V      Tells fido2-cred to verify a credential.
39
40     -c cred_protect
41             If making a credential, set the credential's protection level to
42             cred_protect.  If verifying a credential, check whether the cre‐
43             dential's protection level was signed by the authenticator as
44             cred_protect.
45
46     -d      Causes fido2-cred to emit debugging output on stderr.
47
48     -h      If making a credential, enable the FIDO2 hmac-secret extension.
49             If verifying a credential, check whether the extension data bit
50             was signed by the authenticator.
51
52     -i input_file
53             Tells fido2-cred to read the parameters of the credential from
54             input_file instead of stdin.
55
56     -o output_file
57             Tells fido2-cred to write output on output_file instead of
58             stdout.
59
60     -q      Tells fido2-cred to be quiet.  If a PIN is required and -q is
61             specified, fido2-cred will fail.
62
63     -r      Create a resident credential.  Resident credentials are called
64             “discoverable credentials” in FIDO2.1.
65
66     -u      Create a U2F credential.  By default, fido2-cred will use FIDO2
67             if supported by the authenticator, and fallback to U2F otherwise.
68
69     -v      If making a credential, request user verification.  If verifying
70             a credential, check whether the user verification bit was signed
71             by the authenticator.
72

INPUT FORMAT

74     The input of fido2-cred consists of base64 blobs and UTF-8 strings sepa‐
75     rated by newline characters ('\n').
76
77     When making a credential, fido2-cred expects its input to consist of:
78
79           1.   client data hash (base64 blob);
80           2.   relying party id (UTF-8 string);
81           3.   user name (UTF-8 string);
82           4.   user id (base64 blob).
83
84     When verifying a credential, fido2-cred expects its input to consist of:
85
86           1.   client data hash (base64 blob);
87           2.   relying party id (UTF-8 string);
88           3.   credential format (UTF-8 string);
89           4.   authenticator data (base64 blob);
90           5.   credential id (base64 blob);
91           6.   attestation signature (base64 blob);
92           7.   attestation certificate (optional, base64 blob).
93
94     UTF-8 strings passed to fido2-cred must not contain embedded newline or
95     NUL characters.
96

OUTPUT FORMAT

98     The output of fido2-cred consists of base64 blobs, UTF-8 strings, and
99     PEM-encoded public keys separated by newline characters ('\n').
100
101     Upon the successful generation of a credential, fido2-cred outputs:
102
103           1.   client data hash (base64 blob);
104           2.   relying party id (UTF-8 string);
105           3.   credential format (UTF-8 string);
106           4.   authenticator data (base64 blob);
107           5.   credential id (base64 blob);
108           6.   attestation signature (base64 blob);
109           7.   attestation certificate, if present (base64 blob).
110
111     Upon the successful verification of a credential, fido2-cred outputs:
112
113           1.   credential id (base64 blob);
114           2.   PEM-encoded credential key.
115

EXAMPLES

117     Create a new es256 credential on /dev/hidraw5, verify it, and save the id
118     and the public key of the credential in cred:
119
120           $ echo credential challenge | openssl sha256 -binary | base64 >
121           cred_param
122           $ echo relying party >> cred_param
123           $ echo user name >> cred_param
124           $ dd if=/dev/urandom bs=1 count=32 | base64 >> cred_param
125           $ fido2-cred -M -i cred_param /dev/hidraw5 | fido2-cred -V -o cred
126

CAVEATS

131     Please note that fido2-cred handles Basic Attestation and Self Attesta‐
132     tion transparently.
133
134BSD                            November 5, 2019                            BSD