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 [-dhpruv] [-i input_file] [-o output_file] device
8     fido2-assert -V [-dhpv] [-i input_file] key_file [type]
9

DESCRIPTION

11     fido2-assert gets or verifies a FIDO 2 assertion.
12
13     The input of fido2-assert is defined by the parameters of the assertion
14     to be obtained/verified.  See the INPUT FORMAT section for details.
15
16     The output of fido2-assert is defined by the result of the selected oper‐
17     ation.  See the OUTPUT FORMAT section for details.
18
19     If an assertion is successfully obtained or verified, fido2-assert exits
20     0.  Otherwise, fido2-assert exits 1.
21
22     The options are as follows:
23
24     -G      Tells fido2-assert to obtain a new assertion from device.
25
26     -V      Tells fido2-assert to verify an assertion using the PEM-encoded
27             public key in key_file of type type, where type may be es256
28             (denoting ECDSA over NIST P-256 with SHA-256), rs256 (denoting
29             2048-bit RSA with PKCS#1.5 padding and SHA-256), or eddsa (denot‐
30             ing EDDSA over Curve25519 with SHA-512).  If type is not speci‐
31             fied, es256 is assumed.
32
33     -h      If obtaining an assertion, enable the FIDO2 hmac-secret exten‐
34             sion.  If verifying an assertion, check whether the extension
35             data bit was signed by the authenticator.
36
37     -d      Causes fido2-assert to emit debugging output on stderr.
38
39     -i input_file
40             Tells fido2-assert to read the parameters of the assertion from
41             input_file instead of stdin.
42
43     -o output_file
44             Tells fido2-assert to write output on output_file instead of
45             stdout.
46
47     -p      If obtaining an assertion, request user presence.  If verifying
48             an assertion, check whether the user presence bit was signed by
49             the authenticator.
50
51     -r      Obtain an assertion using a resident credential.  If -r is speci‐
52             fied, fido2-assert will not expect a credential id in its input,
53             and may output multiple assertions.
54
55     -u      Obtain an assertion using U2F.  By default, fido2-assert will use
56             FIDO2 if supported by the authenticator, and fallback to U2F oth‐
57             erwise.
58
59     -v      If obtaining an assertion, prompt the user for a PIN and request
60             user verification from the authenticator.  If a tty is available,
61             fido2-assert will use it to obtain the PIN.  Otherwise, stdin is
62             used.  If verifying an assertion, check whether the user verifi‐
63             cation bit was signed by the authenticator.
64

INPUT FORMAT

66     The input of fido2-assert consists of base64 blobs and UTF-8 strings sep‐
67     arated by newline characters ('\n').
68
69     When obtaining an assertion, fido2-assert expects its input to consist
70     of:
71
72           1.   client data hash (base64 blob);
73           2.   relying party id (UTF-8 string);
74           3.   credential id, if credential not resident (base64 blob);
75           4.   hmac salt, if the FIDO2 hmac-secret extension is enabled
76                (base64 blob);
77
78     When verifying an assertion, fido2-assert expects its input to consist
79     of:
80
81           1.   client data hash (base64 blob);
82           2.   relying party id (UTF-8 string);
83           3.   authenticator data (base64 blob);
84           4.   assertion signature (base64 blob);
85
86     UTF-8 strings passed to fido2-assert must not contain embedded newline or
87     NUL characters.
88

OUTPUT FORMAT

90     The output of fido2-assert consists of base64 blobs and UTF-8 strings
91     separated by newline characters ('\n').
92
93     For each generated assertion, fido2-assert outputs:
94
95           1.   client data hash (base64 blob);
96           2.   relying party id (UTF-8 string);
97           3.   authenticator data (base64 blob);
98           4.   assertion signature (base64 blob);
99           5.   user id, if credential resident (base64 blob);
100           6.   hmac secret, if the FIDO2 hmac-secret extension is enabled
101                (base64 blob);
102
103     When verifying an assertion, fido2-assert produces no output.
104

EXAMPLES

106     Assuming cred contains a es256 credential created according to the steps
107     outlined in fido2-cred(1), obtain an assertion from an authenticator at
108     /dev/hidraw5 and verify it:
109
110           $ echo assertion challenge | openssl sha256 -binary | base64 >
111           assert_param
112           $ echo relying party >> assert_param
113           $ head -1 cred >> assert_param
114           $ tail -n +2 cred > pubkey
115           $ fido2-assert -G -i assert_param /dev/hidraw5 | fido2-assert -V
116           pubkey es256
117

SEE ALSO

119     fido2-cred(1), fido2-token(1)
120
121BSD                              May 10, 2020                              BSD
Impressum