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-CRED 1 30.Os 31.Sh NAME 32.Nm fido2-cred 33.Nd make/verify a FIDO2 credential 34.Sh SYNOPSIS 35.Nm 36.Fl M 37.Op Fl bdhqruvw 38.Op Fl c Ar cred_protect 39.Op Fl i Ar input_file 40.Op Fl o Ar output_file 41.Ar device 42.Op Ar type 43.Nm 44.Fl V 45.Op Fl dhv 46.Op Fl c Ar cred_protect 47.Op Fl i Ar input_file 48.Op Fl o Ar output_file 49.Op Ar type 50.Sh DESCRIPTION 51.Nm 52makes or verifies a FIDO2 credential. 53.Pp 54A credential 55.Ar type 56may be 57.Em es256 58(denoting ECDSA over NIST P-256 with SHA-256), 59.Em rs256 60(denoting 2048-bit RSA with PKCS#1.5 padding and SHA-256), or 61.Em eddsa 62(denoting EDDSA over Curve25519 with SHA-512). 63If 64.Ar type 65is not specified, 66.Em es256 67is assumed. 68.Pp 69When making a credential, the authenticator may require the user 70to authenticate with a PIN. 71If the 72.Fl q 73option is not specified, 74.Nm 75will prompt the user for the PIN. 76If a 77.Em tty 78is available, 79.Nm 80will use it to obtain the PIN. 81Otherwise, 82.Em stdin 83is used. 84.Pp 85The input of 86.Nm 87is defined by the parameters of the credential to be made/verified. 88See the 89.Sx INPUT FORMAT 90section for details. 91.Pp 92The output of 93.Nm 94is defined by the result of the selected operation. 95See the 96.Sx OUTPUT FORMAT 97section for details. 98.Pp 99If a credential is successfully created or verified, 100.Nm 101exits 0. 102Otherwise, 103.Nm 104exits 1. 105.Pp 106The options are as follows: 107.Bl -tag -width Ds 108.It Fl M 109Tells 110.Nm 111to make a new credential on 112.Ar device . 113.It Fl V 114Tells 115.Nm 116to verify a credential. 117.It Fl b 118Request the credential's 119.Dq largeBlobKey , 120a 32-byte symmetric key associated with the generated credential. 121.It Fl c Ar cred_protect 122If making a credential, set the credential's protection level to 123.Ar cred_protect , 124where 125.Ar cred_protect 126is the credential's protection level in decimal notation. 127Please refer to 128.In fido/param.h 129for the set of possible values. 130If verifying a credential, check whether the credential's protection 131level was signed by the authenticator as 132.Ar cred_protect . 133.It Fl d 134Causes 135.Nm 136to emit debugging output on 137.Em stderr . 138.It Fl h 139If making a credential, enable the FIDO2 hmac-secret extension. 140If verifying a credential, check whether the extension data bit was 141signed by the authenticator. 142.It Fl i Ar input_file 143Tells 144.Nm 145to read the parameters of the credential from 146.Ar input_file 147instead of 148.Em stdin . 149.It Fl o Ar output_file 150Tells 151.Nm 152to write output on 153.Ar output_file 154instead of 155.Em stdout . 156.It Fl q 157Tells 158.Nm 159to be quiet. 160If a PIN is required and 161.Fl q 162is specified, 163.Nm 164will fail. 165.It Fl r 166Create a resident credential. 167Resident credentials are called 168.Dq discoverable credentials 169in CTAP 2.1. 170.It Fl u 171Create a U2F credential. 172By default, 173.Nm 174will use FIDO2 if supported by the authenticator, and fallback to 175U2F otherwise. 176.It Fl v 177If making a credential, request user verification. 178If verifying a credential, check whether the user verification bit 179was signed by the authenticator. 180.It Fl w 181Tells 182.Nm 183that the first line of input when making a credential shall be 184interpreted as unhashed client data. 185This is required by Windows Hello, which calculates the client data hash 186internally. 187.El 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 making a credential, 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 204user name (UTF-8 string); 205.It 206user id (base64 blob). 207.El 208.Pp 209When verifying a credential, 210.Nm 211expects its input to consist of: 212.Pp 213.Bl -enum -offset indent -compact 214.It 215client data hash (base64 blob); 216.It 217relying party id (UTF-8 string); 218.It 219credential format (UTF-8 string); 220.It 221authenticator data (base64 blob); 222.It 223credential id (base64 blob); 224.It 225attestation signature (base64 blob); 226.It 227attestation certificate (optional, base64 blob). 228.El 229.Pp 230UTF-8 strings passed to 231.Nm 232must not contain embedded newline or NUL characters. 233.Sh OUTPUT FORMAT 234The output of 235.Nm 236consists of base64 blobs, UTF-8 strings, and PEM-encoded public 237keys separated by newline characters ('\\n'). 238.Pp 239Upon the successful generation of a credential, 240.Nm 241outputs: 242.Pp 243.Bl -enum -offset indent -compact 244.It 245client data hash (base64 blob); 246.It 247relying party id (UTF-8 string); 248.It 249credential format (UTF-8 string); 250.It 251authenticator data (base64 blob); 252.It 253credential id (base64 blob); 254.It 255attestation signature (base64 blob); 256.It 257attestation certificate, if present (base64 blob). 258.It 259the credential's associated 32-byte symmetric key 260.Pq Dq largeBlobKey , 261if present (base64 blob). 262.El 263.Pp 264Upon the successful verification of a credential, 265.Nm 266outputs: 267.Pp 268.Bl -enum -offset indent -compact 269.It 270credential id (base64 blob); 271.It 272PEM-encoded credential key. 273.El 274.Sh EXAMPLES 275Create a new 276.Em es256 277credential on 278.Pa /dev/hidraw5 , 279verify it, and save the id and the public key of the credential in 280.Em cred : 281.Pp 282.Dl $ echo credential challenge | openssl sha256 -binary | base64 > cred_param 283.Dl $ echo relying party >> cred_param 284.Dl $ echo user name >> cred_param 285.Dl $ dd if=/dev/urandom bs=1 count=32 | base64 >> cred_param 286.Dl $ fido2-cred -M -i cred_param /dev/hidraw5 | fido2-cred -V -o cred 287.Sh SEE ALSO 288.Xr fido2-assert 1 , 289.Xr fido2-token 1 290.Sh CAVEATS 291Please note that 292.Nm 293handles Basic Attestation and Self Attestation transparently. 294In the case of Basic Attestation, the validity of the authenticator's 295attestation certificate is 296.Em not 297verified. 298