1.\" Copyright (c) 2018 Yubico AB. All rights reserved. 2.\" Use of this source code is governed by a BSD-style 3.\" license that can be found in the LICENSE file. 4.\" 5.Dd $Mdocdate: November 5 2019 $ 6.Dt FIDO2-ASSERT 1 7.Os 8.Sh NAME 9.Nm fido2-assert 10.Nd get/verify a FIDO 2 assertion 11.Sh SYNOPSIS 12.Nm 13.Fl G 14.Op Fl dhpruv 15.Op Fl t Ar option 16.Op Fl i Ar input_file 17.Op Fl o Ar output_file 18.Ar device 19.Nm 20.Fl V 21.Op Fl dhpv 22.Op Fl i Ar input_file 23.Ar key_file 24.Op Ar type 25.Sh DESCRIPTION 26.Nm 27gets or verifies a FIDO 2 assertion. 28.Pp 29The input of 30.Nm 31is defined by the parameters of the assertion to be obtained/verified. 32See the 33.Sx INPUT FORMAT 34section for details. 35.Pp 36The output of 37.Nm 38is defined by the result of the selected operation. 39See the 40.Sx OUTPUT FORMAT 41section for details. 42.Pp 43If an assertion is successfully obtained or verified, 44.Nm 45exits 0. 46Otherwise, 47.Nm 48exits 1. 49.Pp 50The options are as follows: 51.Bl -tag -width Ds 52.It Fl G 53Tells 54.Nm 55to obtain a new assertion from 56.Ar device . 57.It Fl V 58Tells 59.Nm 60to verify an assertion using the PEM-encoded public key in 61.Ar key_file 62of type 63.Ar type , 64where 65.Ar type 66may be 67.Em es256 68(denoting ECDSA over NIST P-256 with SHA-256), 69.Em rs256 70(denoting 2048-bit RSA with PKCS#1.5 padding and SHA-256), or 71.Em eddsa 72(denoting EDDSA over Curve25519 with SHA-512). 73If 74.Ar type 75is not specified, 76.Em es256 77is assumed. 78.It Fl h 79If obtaining an assertion, enable the FIDO2 hmac-secret 80extension. 81If verifying an assertion, check whether the extension data bit was 82signed by the authenticator. 83.It Fl d 84Causes 85.Nm 86to emit debugging output on 87.Em stderr . 88.It Fl i Ar input_file 89Tells 90.Nm 91to read the parameters of the assertion from 92.Ar input_file 93instead of 94.Em stdin . 95.It Fl o Ar output_file 96Tells 97.Nm 98to write output on 99.Ar output_file 100instead of 101.Em stdout . 102.It Fl p 103If obtaining an assertion, request user presence. 104If verifying an assertion, check whether the user presence bit was 105signed by the authenticator. 106.It Fl r 107Obtain an assertion using a resident credential. 108If 109.Fl r 110is specified, 111.Nm 112will not expect a credential id in its input, and may output 113multiple assertions. 114.It Fl t Ar option 115Toggles a key/value 116.Ar option , 117where 118.Ar option 119is a string of the form 120.Dq key=value . 121The options supported at present are: 122.Bl -tag -width Ds 123.It Cm up Ns = Ns Ar true|false 124Asks the authenticator for user presence to be enabled or disabled. 125.It Cm uv Ns = Ns Ar true|false 126Asks the authenticator for user verification to be enabled or 127disabled. 128.It Cm pin Ns = Ns Ar true|false 129Tells 130.Nm 131whether to prompt for a PIN and request user verification. 132.El 133.Pp 134The 135.Fl t 136option may be specified multiple times. 137.It Fl u 138Obtain an assertion using U2F. 139By default, 140.Nm 141will use FIDO2 if supported by the authenticator, and fallback to 142U2F otherwise. 143.It Fl v 144If obtaining an assertion, prompt the user for a PIN and request 145user verification from the authenticator. 146If verifying an assertion, check whether the user verification bit 147was signed by the authenticator. 148.El 149.Pp 150If a 151.Em tty 152is available, 153.Nm 154will use it to obtain the PIN. 155Otherwise, 156.Em stdin 157is used. 158.Sh INPUT FORMAT 159The input of 160.Nm 161consists of base64 blobs and UTF-8 strings separated 162by newline characters ('\\n'). 163.Pp 164When obtaining an assertion, 165.Nm 166expects its input to consist of: 167.Pp 168.Bl -enum -offset indent -compact 169.It 170client data hash (base64 blob); 171.It 172relying party id (UTF-8 string); 173.It 174credential id, if credential not resident (base64 blob); 175.It 176hmac salt, if the FIDO2 hmac-secret extension is enabled 177(base64 blob); 178.El 179.Pp 180When verifying an assertion, 181.Nm 182expects its input to consist of: 183.Pp 184.Bl -enum -offset indent -compact 185.It 186client data hash (base64 blob); 187.It 188relying party id (UTF-8 string); 189.It 190authenticator data (base64 blob); 191.It 192assertion signature (base64 blob); 193.El 194.Pp 195UTF-8 strings passed to 196.Nm 197must not contain embedded newline or NUL characters. 198.Sh OUTPUT FORMAT 199The output of 200.Nm 201consists of base64 blobs and UTF-8 strings separated 202by newline characters ('\\n'). 203.Pp 204For each generated assertion, 205.Nm 206outputs: 207.Pp 208.Bl -enum -offset indent -compact 209.It 210client data hash (base64 blob); 211.It 212relying party id (UTF-8 string); 213.It 214authenticator data (base64 blob); 215.It 216assertion signature (base64 blob); 217.It 218user id, if credential resident (base64 blob); 219.It 220hmac secret, if the FIDO2 hmac-secret extension is enabled 221(base64 blob); 222.El 223.Pp 224When verifying an assertion, 225.Nm 226produces no output. 227.Sh EXAMPLES 228Assuming 229.Pa cred 230contains a 231.Em es256 232credential created according to the steps outlined in 233.Xr fido2-cred 1 , 234obtain an assertion from an authenticator at 235.Pa /dev/hidraw5 236and verify it: 237.Pp 238.Dl $ echo assertion challenge | openssl sha256 -binary | base64 > assert_param 239.Dl $ echo relying party >> assert_param 240.Dl $ head -1 cred >> assert_param 241.Dl $ tail -n +2 cred > pubkey 242.Dl $ fido2-assert -G -i assert_param /dev/hidraw5 | fido2-assert -V pubkey es256 243.Sh SEE ALSO 244.Xr fido2-cred 1 , 245.Xr fido2-token 1 246