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-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 bdhqruv 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.El 181.Sh INPUT FORMAT 182The input of 183.Nm 184consists of base64 blobs and UTF-8 strings separated 185by newline characters ('\\n'). 186.Pp 187When making a credential, 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 197user name (UTF-8 string); 198.It 199user id (base64 blob). 200.El 201.Pp 202When verifying a credential, 203.Nm 204expects its input to consist of: 205.Pp 206.Bl -enum -offset indent -compact 207.It 208client data hash (base64 blob); 209.It 210relying party id (UTF-8 string); 211.It 212credential format (UTF-8 string); 213.It 214authenticator data (base64 blob); 215.It 216credential id (base64 blob); 217.It 218attestation signature (base64 blob); 219.It 220attestation certificate (optional, base64 blob). 221.El 222.Pp 223UTF-8 strings passed to 224.Nm 225must not contain embedded newline or NUL characters. 226.Sh OUTPUT FORMAT 227The output of 228.Nm 229consists of base64 blobs, UTF-8 strings, and PEM-encoded public 230keys separated by newline characters ('\\n'). 231.Pp 232Upon the successful generation of a credential, 233.Nm 234outputs: 235.Pp 236.Bl -enum -offset indent -compact 237.It 238client data hash (base64 blob); 239.It 240relying party id (UTF-8 string); 241.It 242credential format (UTF-8 string); 243.It 244authenticator data (base64 blob); 245.It 246credential id (base64 blob); 247.It 248attestation signature (base64 blob); 249.It 250attestation certificate, if present (base64 blob). 251.It 252the credential's associated 32-byte symmetric key 253.Pq Dq largeBlobKey , 254if present (base64 blob). 255.El 256.Pp 257Upon the successful verification of a credential, 258.Nm 259outputs: 260.Pp 261.Bl -enum -offset indent -compact 262.It 263credential id (base64 blob); 264.It 265PEM-encoded credential key. 266.El 267.Sh EXAMPLES 268Create a new 269.Em es256 270credential on 271.Pa /dev/hidraw5 , 272verify it, and save the id and the public key of the credential in 273.Em cred : 274.Pp 275.Dl $ echo credential challenge | openssl sha256 -binary | base64 > cred_param 276.Dl $ echo relying party >> cred_param 277.Dl $ echo user name >> cred_param 278.Dl $ dd if=/dev/urandom bs=1 count=32 | base64 >> cred_param 279.Dl $ fido2-cred -M -i cred_param /dev/hidraw5 | fido2-cred -V -o cred 280.Sh SEE ALSO 281.Xr fido2-assert 1 , 282.Xr fido2-token 1 283.Sh CAVEATS 284Please note that 285.Nm 286handles Basic Attestation and Self Attestation transparently. 287In the case of Basic Attestation, the validity of the authenticator's 288attestation certificate is 289.Em not 290verified. 291