1.\" Copyright (c) 2018 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: November 5 2019 $ 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 bdhpruv 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.El 179.Pp 180If a 181.Em tty 182is available, 183.Nm 184will use it to obtain the PIN. 185Otherwise, 186.Em stdin 187is used. 188.Sh INPUT FORMAT 189The input of 190.Nm 191consists of base64 blobs and UTF-8 strings separated 192by newline characters ('\\n'). 193.Pp 194When obtaining an assertion, 195.Nm 196expects its input to consist of: 197.Pp 198.Bl -enum -offset indent -compact 199.It 200client data hash (base64 blob); 201.It 202relying party id (UTF-8 string); 203.It 204credential id, if credential not resident (base64 blob); 205.It 206hmac salt, if the FIDO2 hmac-secret extension is enabled 207(base64 blob); 208.El 209.Pp 210When verifying an assertion, 211.Nm 212expects its input to consist of: 213.Pp 214.Bl -enum -offset indent -compact 215.It 216client data hash (base64 blob); 217.It 218relying party id (UTF-8 string); 219.It 220authenticator data (base64 blob); 221.It 222assertion signature (base64 blob); 223.El 224.Pp 225UTF-8 strings passed to 226.Nm 227must not contain embedded newline or NUL characters. 228.Sh OUTPUT FORMAT 229The output of 230.Nm 231consists of base64 blobs and UTF-8 strings separated 232by newline characters ('\\n'). 233.Pp 234For each generated assertion, 235.Nm 236outputs: 237.Pp 238.Bl -enum -offset indent -compact 239.It 240client data hash (base64 blob); 241.It 242relying party id (UTF-8 string); 243.It 244authenticator data (base64 blob); 245.It 246assertion signature (base64 blob); 247.It 248user id, if credential resident (base64 blob); 249.It 250hmac secret, if the FIDO2 hmac-secret extension is enabled 251(base64 blob); 252.It 253the credential's associated 32-byte symmetric key 254.Pq Dq largeBlobKey , 255if requested (base64 blob). 256.El 257.Pp 258When verifying an assertion, 259.Nm 260produces no output. 261.Sh EXAMPLES 262Assuming 263.Pa cred 264contains a 265.Em es256 266credential created according to the steps outlined in 267.Xr fido2-cred 1 , 268obtain an assertion from an authenticator at 269.Pa /dev/hidraw5 270and verify it: 271.Pp 272.Dl $ echo assertion challenge | openssl sha256 -binary | base64 > assert_param 273.Dl $ echo relying party >> assert_param 274.Dl $ head -1 cred >> assert_param 275.Dl $ tail -n +2 cred > pubkey 276.Dl $ fido2-assert -G -i assert_param /dev/hidraw5 | fido2-assert -V pubkey es256 277.Sh SEE ALSO 278.Xr fido2-cred 1 , 279.Xr fido2-token 1 280