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