1.\" Copyright (c) 2018-2023 Yubico AB. All rights reserved. 2.\" 3.\" Redistribution and use in source and binary forms, with or without 4.\" modification, are permitted provided that the following conditions are 5.\" met: 6.\" 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. 9.\" 2. Redistributions in binary form must reproduce the above copyright 10.\" notice, this list of conditions and the following disclaimer in 11.\" the documentation and/or other materials provided with the 12.\" distribution. 13.\" 14.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 15.\" "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 16.\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR 17.\" A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT 18.\" HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 19.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT 20.\" LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 21.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 22.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 23.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 24.\" OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 25.\" 26.\" SPDX-License-Identifier: BSD-2-Clause 27.\" 28.Dd $Mdocdate: July 3 2023 $ 29.Dt FIDO2-ASSERT 1 30.Os 31.Sh NAME 32.Nm fido2-assert 33.Nd get/verify a FIDO2 assertion 34.Sh SYNOPSIS 35.Nm 36.Fl G 37.Op Fl bdhpruvw 38.Op Fl t Ar option 39.Op Fl i Ar input_file 40.Op Fl o Ar output_file 41.Ar device 42.Nm 43.Fl V 44.Op Fl dhpv 45.Op Fl i Ar input_file 46.Ar key_file 47.Op Ar type 48.Sh DESCRIPTION 49.Nm 50gets or verifies a FIDO2 assertion. 51.Pp 52The input of 53.Nm 54is defined by the parameters of the assertion to be obtained/verified. 55See the 56.Sx INPUT FORMAT 57section for details. 58.Pp 59The output of 60.Nm 61is defined by the result of the selected operation. 62See the 63.Sx OUTPUT FORMAT 64section for details. 65.Pp 66If an assertion is successfully obtained or verified, 67.Nm 68exits 0. 69Otherwise, 70.Nm 71exits 1. 72.Pp 73The options are as follows: 74.Bl -tag -width Ds 75.It Fl G 76Tells 77.Nm 78to obtain a new assertion from 79.Ar device . 80.It Fl V 81Tells 82.Nm 83to verify an assertion using the PEM-encoded public key in 84.Ar key_file 85of type 86.Ar type , 87where 88.Ar type 89may be 90.Em es256 91(denoting ECDSA over NIST P-256 with SHA-256), 92.Em rs256 93(denoting 2048-bit RSA with PKCS#1.5 padding and SHA-256), or 94.Em eddsa 95(denoting EDDSA over Curve25519 with SHA-512). 96If 97.Ar type 98is not specified, 99.Em es256 100is assumed. 101.It Fl b 102Request the credential's 103.Dq largeBlobKey , 104a 32-byte symmetric key associated with the asserted credential. 105.It Fl h 106If obtaining an assertion, enable the FIDO2 hmac-secret 107extension. 108If verifying an assertion, check whether the extension data bit was 109signed by the authenticator. 110.It Fl d 111Causes 112.Nm 113to emit debugging output on 114.Em stderr . 115.It Fl i Ar input_file 116Tells 117.Nm 118to read the parameters of the assertion from 119.Ar input_file 120instead of 121.Em stdin . 122.It Fl o Ar output_file 123Tells 124.Nm 125to write output on 126.Ar output_file 127instead of 128.Em stdout . 129.It Fl p 130If obtaining an assertion, request user presence. 131If verifying an assertion, check whether the user presence bit was 132signed by the authenticator. 133.It Fl r 134Obtain an assertion using a resident credential. 135If 136.Fl r 137is specified, 138.Nm 139will not expect a credential id in its input, and may output 140multiple assertions. 141Resident credentials are called 142.Dq discoverable credentials 143in CTAP 2.1. 144.It Fl t Ar option 145Toggles a key/value 146.Ar option , 147where 148.Ar option 149is a string of the form 150.Dq key=value . 151The options supported at present are: 152.Bl -tag -width Ds 153.It Cm up Ns = Ns Ar true|false 154Asks the authenticator for user presence to be enabled or disabled. 155.It Cm uv Ns = Ns Ar true|false 156Asks the authenticator for user verification to be enabled or 157disabled. 158.It Cm pin Ns = Ns Ar true|false 159Tells 160.Nm 161whether to prompt for a PIN and request user verification. 162.El 163.Pp 164The 165.Fl t 166option may be specified multiple times. 167.It Fl u 168Obtain an assertion using U2F. 169By default, 170.Nm 171will use FIDO2 if supported by the authenticator, and fallback to 172U2F otherwise. 173.It Fl v 174If obtaining an assertion, prompt the user for a PIN and request 175user verification from the authenticator. 176If verifying an assertion, check whether the user verification bit 177was signed by the authenticator. 178.It Fl w 179Tells 180.Nm 181that the first line of input when obtaining an assertion shall be 182interpreted as unhashed client data. 183This is required by Windows Hello, which calculates the client data hash 184internally. 185.El 186.Pp 187If a 188.Em tty 189is available, 190.Nm 191will use it to obtain the PIN. 192Otherwise, 193.Em stdin 194is used. 195.Sh INPUT FORMAT 196The input of 197.Nm 198consists of base64 blobs and UTF-8 strings separated 199by newline characters ('\\n'). 200.Pp 201When obtaining an assertion, 202.Nm 203expects its input to consist of: 204.Pp 205.Bl -enum -offset indent -compact 206.It 207client data hash (base64 blob); 208.It 209relying party id (UTF-8 string); 210.It 211credential id, if credential not resident (base64 blob); 212.It 213hmac salt, if the FIDO2 hmac-secret extension is enabled 214(base64 blob); 215.El 216.Pp 217When verifying an assertion, 218.Nm 219expects its input to consist of: 220.Pp 221.Bl -enum -offset indent -compact 222.It 223client data hash (base64 blob); 224.It 225relying party id (UTF-8 string); 226.It 227authenticator data (base64 blob); 228.It 229assertion signature (base64 blob); 230.El 231.Pp 232UTF-8 strings passed to 233.Nm 234must not contain embedded newline or NUL characters. 235.Sh OUTPUT FORMAT 236The output of 237.Nm 238consists of base64 blobs and UTF-8 strings separated 239by newline characters ('\\n'). 240.Pp 241For each generated assertion, 242.Nm 243outputs: 244.Pp 245.Bl -enum -offset indent -compact 246.It 247client data hash (base64 blob); 248.It 249relying party id (UTF-8 string); 250.It 251authenticator data (base64 blob); 252.It 253assertion signature (base64 blob); 254.It 255user id, if credential resident (base64 blob); 256.It 257hmac secret, if the FIDO2 hmac-secret extension is enabled 258(base64 blob); 259.It 260the credential's associated 32-byte symmetric key 261.Pq Dq largeBlobKey , 262if requested (base64 blob). 263.El 264.Pp 265When verifying an assertion, 266.Nm 267produces no output. 268.Sh EXAMPLES 269Assuming 270.Pa cred 271contains a 272.Em es256 273credential created according to the steps outlined in 274.Xr fido2-cred 1 , 275obtain an assertion from an authenticator at 276.Pa /dev/hidraw5 277and verify it: 278.Pp 279.Dl $ echo assertion challenge | openssl sha256 -binary | base64 > assert_param 280.Dl $ echo relying party >> assert_param 281.Dl $ head -1 cred >> assert_param 282.Dl $ tail -n +2 cred > pubkey 283.Dl $ fido2-assert -G -i assert_param /dev/hidraw5 | fido2-assert -V pubkey es256 284.Sh SEE ALSO 285.Xr fido2-cred 1 , 286.Xr fido2-token 1 287