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