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 [-bdhqruv] [-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     -b      Request the credential's “largeBlobKey”, a 32-byte symmetric key
41             associated with the generated credential.
42
43     -c cred_protect
44             If making a credential, set the credential's protection level to
45             cred_protect, where cred_protect is the credential's protection
46             level in decimal notation.  Please refer to <fido/param.h> for
47             the set of possible values.  If verifying a credential, check
48             whether the credential's protection level was signed by the au‐
49             thenticator as cred_protect.
50
51     -d      Causes fido2-cred to emit debugging output on stderr.
52
53     -h      If making a credential, enable the FIDO2 hmac-secret extension.
54             If verifying a credential, check whether the extension data bit
55             was signed by the authenticator.
56
57     -i input_file
58             Tells fido2-cred to read the parameters of the credential from
59             input_file instead of stdin.
60
61     -o output_file
62             Tells fido2-cred to write output on output_file instead of
63             stdout.
64
65     -q      Tells fido2-cred to be quiet.  If a PIN is required and -q is
66             specified, fido2-cred will fail.
67
68     -r      Create a resident credential.  Resident credentials are called
69             “discoverable credentials” in FIDO 2.1.
70
71     -u      Create a U2F credential.  By default, fido2-cred will use FIDO2
72             if supported by the authenticator, and fallback to U2F otherwise.
73
74     -v      If making a credential, request user verification.  If verifying
75             a credential, check whether the user verification bit was signed
76             by the authenticator.
77

INPUT FORMAT

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

OUTPUT FORMAT

103     The output of fido2-cred consists of base64 blobs, UTF-8 strings, and
104     PEM-encoded public keys separated by newline characters ('\n').
105
106     Upon the successful generation of a credential, fido2-cred outputs:
107
108           1.   client data hash (base64 blob);
109           2.   relying party id (UTF-8 string);
110           3.   credential format (UTF-8 string);
111           4.   authenticator data (base64 blob);
112           5.   credential id (base64 blob);
113           6.   attestation signature (base64 blob);
114           7.   attestation certificate, if present (base64 blob).
115           8.   the credential's associated 32-byte symmetric key
116                (“largeBlobKey”), if present (base64 blob).
117
118     Upon the successful verification of a credential, fido2-cred outputs:
119
120           1.   credential id (base64 blob);
121           2.   PEM-encoded credential key.
122

EXAMPLES

124     Create a new es256 credential on /dev/hidraw5, verify it, and save the id
125     and the public key of the credential in cred:
126
127           $ echo credential challenge | openssl sha256 -binary | base64 >
128           cred_param
129           $ echo relying party >> cred_param
130           $ echo user name >> cred_param
131           $ dd if=/dev/urandom bs=1 count=32 | base64 >> cred_param
132           $ fido2-cred -M -i cred_param /dev/hidraw5 | fido2-cred -V -o cred
133

CAVEATS

138     Please note that fido2-cred handles Basic Attestation and Self Attesta‐
139     tion transparently.  In the case of Basic Attestation, the validity of
140     the authenticator's attestation certificate is not verified.
141
142BSD                            November 5, 2019                            BSD