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 FIDO2 assertion 11.Sh SYNOPSIS 12.Nm 13.Fl G 14.Op Fl bdhpruv 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 FIDO2 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 b 79Request the credential's 80.Dq largeBlobKey , 81a 32-byte symmetric key associated with the asserted credential. 82.It Fl h 83If obtaining an assertion, enable the FIDO2 hmac-secret 84extension. 85If verifying an assertion, check whether the extension data bit was 86signed by the authenticator. 87.It Fl d 88Causes 89.Nm 90to emit debugging output on 91.Em stderr . 92.It Fl i Ar input_file 93Tells 94.Nm 95to read the parameters of the assertion from 96.Ar input_file 97instead of 98.Em stdin . 99.It Fl o Ar output_file 100Tells 101.Nm 102to write output on 103.Ar output_file 104instead of 105.Em stdout . 106.It Fl p 107If obtaining an assertion, request user presence. 108If verifying an assertion, check whether the user presence bit was 109signed by the authenticator. 110.It Fl r 111Obtain an assertion using a resident credential. 112If 113.Fl r 114is specified, 115.Nm 116will not expect a credential id in its input, and may output 117multiple assertions. 118Resident credentials are called 119.Dq discoverable credentials 120in CTAP 2.1. 121.It Fl t Ar option 122Toggles a key/value 123.Ar option , 124where 125.Ar option 126is a string of the form 127.Dq key=value . 128The options supported at present are: 129.Bl -tag -width Ds 130.It Cm up Ns = Ns Ar true|false 131Asks the authenticator for user presence to be enabled or disabled. 132.It Cm uv Ns = Ns Ar true|false 133Asks the authenticator for user verification to be enabled or 134disabled. 135.It Cm pin Ns = Ns Ar true|false 136Tells 137.Nm 138whether to prompt for a PIN and request user verification. 139.El 140.Pp 141The 142.Fl t 143option may be specified multiple times. 144.It Fl u 145Obtain an assertion using U2F. 146By default, 147.Nm 148will use FIDO2 if supported by the authenticator, and fallback to 149U2F otherwise. 150.It Fl v 151If obtaining an assertion, prompt the user for a PIN and request 152user verification from the authenticator. 153If verifying an assertion, check whether the user verification bit 154was signed by the authenticator. 155.El 156.Pp 157If a 158.Em tty 159is available, 160.Nm 161will use it to obtain the PIN. 162Otherwise, 163.Em stdin 164is used. 165.Sh INPUT FORMAT 166The input of 167.Nm 168consists of base64 blobs and UTF-8 strings separated 169by newline characters ('\\n'). 170.Pp 171When obtaining an assertion, 172.Nm 173expects its input to consist of: 174.Pp 175.Bl -enum -offset indent -compact 176.It 177client data hash (base64 blob); 178.It 179relying party id (UTF-8 string); 180.It 181credential id, if credential not resident (base64 blob); 182.It 183hmac salt, if the FIDO2 hmac-secret extension is enabled 184(base64 blob); 185.El 186.Pp 187When verifying an assertion, 188.Nm 189expects its input to consist of: 190.Pp 191.Bl -enum -offset indent -compact 192.It 193client data hash (base64 blob); 194.It 195relying party id (UTF-8 string); 196.It 197authenticator data (base64 blob); 198.It 199assertion signature (base64 blob); 200.El 201.Pp 202UTF-8 strings passed to 203.Nm 204must not contain embedded newline or NUL characters. 205.Sh OUTPUT FORMAT 206The output of 207.Nm 208consists of base64 blobs and UTF-8 strings separated 209by newline characters ('\\n'). 210.Pp 211For each generated assertion, 212.Nm 213outputs: 214.Pp 215.Bl -enum -offset indent -compact 216.It 217client data hash (base64 blob); 218.It 219relying party id (UTF-8 string); 220.It 221authenticator data (base64 blob); 222.It 223assertion signature (base64 blob); 224.It 225user id, if credential resident (base64 blob); 226.It 227hmac secret, if the FIDO2 hmac-secret extension is enabled 228(base64 blob); 229.It 230the credential's associated 32-byte symmetric key 231.Pq Dq largeBlobKey , 232if requested (base64 blob). 233.El 234.Pp 235When verifying an assertion, 236.Nm 237produces no output. 238.Sh EXAMPLES 239Assuming 240.Pa cred 241contains a 242.Em es256 243credential created according to the steps outlined in 244.Xr fido2-cred 1 , 245obtain an assertion from an authenticator at 246.Pa /dev/hidraw5 247and verify it: 248.Pp 249.Dl $ echo assertion challenge | openssl sha256 -binary | base64 > assert_param 250.Dl $ echo relying party >> assert_param 251.Dl $ head -1 cred >> assert_param 252.Dl $ tail -n +2 cred > pubkey 253.Dl $ fido2-assert -G -i assert_param /dev/hidraw5 | fido2-assert -V pubkey es256 254.Sh SEE ALSO 255.Xr fido2-cred 1 , 256.Xr fido2-token 1 257