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

NAME

4     fido2-assert — get/verify a FIDO 2 assertion
5

SYNOPSIS

7     fido2-assert -G [-bdhpruv] [-t option] [-i input_file] [-o output_file]
8                  device
9     fido2-assert -V [-dhpv] [-i input_file] key_file [type]
10

DESCRIPTION

12     fido2-assert gets or verifies a FIDO 2 assertion.
13
14     The input of fido2-assert is defined by the parameters of the assertion
15     to be obtained/verified.  See the INPUT FORMAT section for details.
16
17     The output of fido2-assert is defined by the result of the selected oper‐
18     ation.  See the OUTPUT FORMAT section for details.
19
20     If an assertion is successfully obtained or verified, fido2-assert exits
21     0.  Otherwise, fido2-assert exits 1.
22
23     The options are as follows:
24
25     -G      Tells fido2-assert to obtain a new assertion from device.
26
27     -V      Tells fido2-assert to verify an assertion using the PEM-encoded
28             public key in key_file of type type, where type may be es256 (de‐
29             noting ECDSA over NIST P-256 with SHA-256), rs256 (denoting
30             2048-bit RSA with PKCS#1.5 padding and SHA-256), or eddsa (denot‐
31             ing EDDSA over Curve25519 with SHA-512).  If type is not speci‐
32             fied, es256 is assumed.
33
34     -b      Request the credential's “largeBlobKey”, a 32-byte symmetric key
35             associated with the asserted credential.
36
37     -h      If obtaining an assertion, enable the FIDO2 hmac-secret exten‐
38             sion.  If verifying an assertion, check whether the extension
39             data bit was signed by the authenticator.
40
41     -d      Causes fido2-assert to emit debugging output on stderr.
42
43     -i input_file
44             Tells fido2-assert to read the parameters of the assertion from
45             input_file instead of stdin.
46
47     -o output_file
48             Tells fido2-assert to write output on output_file instead of
49             stdout.
50
51     -p      If obtaining an assertion, request user presence.  If verifying
52             an assertion, check whether the user presence bit was signed by
53             the authenticator.
54
55     -r      Obtain an assertion using a resident credential.  If -r is speci‐
56             fied, fido2-assert will not expect a credential id in its input,
57             and may output multiple assertions.  Resident credentials are
58             called “discoverable credentials” in FIDO 2.1.
59
60     -t option
61             Toggles a key/value option, where option is a string of the form
62             “key=value”.  The options supported at present are:
63
64             up=true|false
65                     Asks the authenticator for user presence to be enabled or
66                     disabled.
67
68             uv=true|false
69                     Asks the authenticator for user verification to be en‐
70                     abled or disabled.
71
72             pin=true|false
73                     Tells fido2-assert whether to prompt for a PIN and re‐
74                     quest user verification.
75
76             The -t option may be specified multiple times.
77
78     -u      Obtain an assertion using U2F.  By default, fido2-assert will use
79             FIDO2 if supported by the authenticator, and fallback to U2F oth‐
80             erwise.
81
82     -v      If obtaining an assertion, prompt the user for a PIN and request
83             user verification from the authenticator.  If verifying an asser‐
84             tion, check whether the user verification bit was signed by the
85             authenticator.
86
87     If a tty is available, fido2-assert will use it to obtain the PIN.  Oth‐
88     erwise, stdin is used.
89

INPUT FORMAT

91     The input of fido2-assert consists of base64 blobs and UTF-8 strings sep‐
92     arated by newline characters ('\n').
93
94     When obtaining an assertion, fido2-assert expects its input to consist
95     of:
96
97           1.   client data hash (base64 blob);
98           2.   relying party id (UTF-8 string);
99           3.   credential id, if credential not resident (base64 blob);
100           4.   hmac salt, if the FIDO2 hmac-secret extension is enabled
101                (base64 blob);
102
103     When verifying an assertion, fido2-assert expects its input to consist
104     of:
105
106           1.   client data hash (base64 blob);
107           2.   relying party id (UTF-8 string);
108           3.   authenticator data (base64 blob);
109           4.   assertion signature (base64 blob);
110
111     UTF-8 strings passed to fido2-assert must not contain embedded newline or
112     NUL characters.
113

OUTPUT FORMAT

115     The output of fido2-assert consists of base64 blobs and UTF-8 strings
116     separated by newline characters ('\n').
117
118     For each generated assertion, fido2-assert outputs:
119
120           1.   client data hash (base64 blob);
121           2.   relying party id (UTF-8 string);
122           3.   authenticator data (base64 blob);
123           4.   assertion signature (base64 blob);
124           5.   user id, if credential resident (base64 blob);
125           6.   hmac secret, if the FIDO2 hmac-secret extension is enabled
126                (base64 blob);
127           7.   the credential's associated 32-byte symmetric key
128                (“largeBlobKey”), if requested (base64 blob).
129
130     When verifying an assertion, fido2-assert produces no output.
131

EXAMPLES

133     Assuming cred contains a es256 credential created according to the steps
134     outlined in fido2-cred(1), obtain an assertion from an authenticator at
135     /dev/hidraw5 and verify it:
136
137           $ echo assertion challenge | openssl sha256 -binary | base64 >
138           assert_param
139           $ echo relying party >> assert_param
140           $ head -1 cred >> assert_param
141           $ tail -n +2 cred > pubkey
142           $ fido2-assert -G -i assert_param /dev/hidraw5 | fido2-assert -V
143           pubkey es256
144

SEE ALSO

146     fido2-cred(1), fido2-token(1)
147
148BSD                            November 5, 2019                            BSD
Impressum