home | help 
FIDO2-ASSERT(1) 	     General Commands Manual		 FIDO2-ASSERT(1)

NAME
     fido2-assert -- get/verify a FIDO2 assertion

SYNOPSIS
     fido2-assert -G [-bdhpruvw] [-t option] [-i input_file] [-o output_file]
		  device
     fido2-assert -V [-dhpv] [-i input_file] key_file [type]

DESCRIPTION
     fido2-assert gets or verifies a FIDO2 assertion.

     The  input of fido2-assert is defined by the parameters of the assertion to
     be obtained/verified.  See the "INPUT FORMAT" section for details.

     The output of fido2-assert is defined by the result of the selected  opera-
     tion.  See the "OUTPUT FORMAT" section for details.

     If an assertion is successfully obtained or verified, fido2-assert exits 0.
     Otherwise, fido2-assert exits 1.

     The options are as follows:

     -G      Tells fido2-assert to obtain a new assertion from device.

     -V      Tells  fido2-assert  to  verify  an assertion using the PEM-encoded
	     public key in key_file of type type, where type may be  es256  (de-
	     noting  ECDSA  over NIST P-256 with SHA-256), es384 (denoting ECDSA
	     over NIST P-384 with SHA-384), rs256 (denoting  2048-bit  RSA  with
	     PKCS#1.5  padding	and  SHA-256),	or  eddsa  (denoting  EDDSA over
	     Curve25519 with SHA-512).	If type is not specified, es256  is  as-
	     sumed.

     -b      Request  the  credential's  "largeBlobKey", a 32-byte symmetric key
	     associated with the asserted credential.

     -h      If obtaining an assertion, enable the FIDO2 hmac-secret  extension.
	     If verifying an assertion, check whether the extension data bit was
	     signed by the authenticator.

     -d      Causes fido2-assert to emit debugging output on stderr.

     -i input_file
	     Tells  fido2-assert  to  read  the parameters of the assertion from
	     input_file instead of stdin.

     -o output_file
	     Tells fido2-assert  to  write  output  on	output_file  instead  of
	     stdout.

     -p      If  obtaining an assertion, request user presence.  If verifying an
	     assertion, check whether the user presence bit was  signed  by  the
	     authenticator.

     -r      Obtain  an  assertion using a resident credential.  If -r is speci-
	     fied, fido2-assert will not expect a credential id  in  its  input,
	     and  may  output  multiple  assertions.   Resident  credentials are
	     called "discoverable credentials" in CTAP 2.1.

     -t option
	     Toggles a key/value option, where option is a string  of  the  form
	     "key=value".  The options supported at present are:

	     up=true|false
		     Asks  the	authenticator for user presence to be enabled or
		     disabled.

	     uv=true|false
		     Asks the authenticator for user verification to be  enabled
		     or disabled.

	     pin=true|false
		     Tells  fido2-assert whether to prompt for a PIN and request
		     user verification.

	     The -t option may be specified multiple times.

     -u      Obtain an assertion using U2F.  By default, fido2-assert  will  use
	     FIDO2 if supported by the authenticator, and fallback to U2F other-
	     wise.

     -v      If  obtaining  an	assertion, prompt the user for a PIN and request
	     user verification from the authenticator.	If verifying  an  asser-
	     tion, check whether the user verification bit was signed by the au-
	     thenticator.

     -w      Tells  fido2-assert  that the first line of input when obtaining an
	     assertion shall be interpreted as unhashed client	data.	This  is
	     required  by  Windows  Hello, which calculates the client data hash
	     internally.

     If a tty is available, fido2-assert will use it to obtain the PIN.   Other-
     wise, stdin is used.

INPUT FORMAT
     The  input of fido2-assert consists of base64 blobs and UTF-8 strings sepa-
     rated by newline characters ('\n').

     When obtaining an assertion, fido2-assert expects its input to consist of:

	   1.	client data hash (base64 blob);
	   2.	relying party id (UTF-8 string);
	   3.	credential id, if credential not resident (base64 blob);
	   4.	hmac salt, if the FIDO2 hmac-secret extension is enabled (base64
		blob);

     When verifying an assertion, fido2-assert expects its input to consist of:

	   1.	client data hash (base64 blob);
	   2.	relying party id (UTF-8 string);
	   3.	CBOR encoded authenticator data (base64 blob);
	   4.	assertion signature (base64 blob);

     UTF-8 strings passed to fido2-assert must not contain embedded  newline  or
     NUL characters.

OUTPUT FORMAT
     The output of fido2-assert consists of base64 blobs and UTF-8 strings sepa-
     rated by newline characters ('\n').

     For each generated assertion, fido2-assert outputs:

	   1.	client data hash (base64 blob);
	   2.	relying party id (UTF-8 string);
	   3.	CBOR encoded authenticator data (base64 blob);
	   4.	assertion signature (base64 blob);
	   5.	user id, if credential resident (base64 blob);
	   6.	hmac  secret,  if  the	FIDO2  hmac-secret  extension is enabled
		(base64 blob);
	   7.	the    credential's    associated    32-byte	symmetric    key
		("largeBlobKey"), if requested (base64 blob).

     When verifying an assertion, fido2-assert produces no output.

EXAMPLES
     Assuming  cred  contains  a es256 credential created according to the steps
     outlined in fido2-cred(1), obtain an assertion  from  an  authenticator  at
     /dev/hidraw5 and verify it:

	   $  echo  assertion  challenge  |  openssl  sha256  -binary | base64 >
	   assert_param
	   $ echo relying party >> assert_param
	   $ head -1 cred >> assert_param
	   $ tail -n +2 cred > pubkey
	   $ fido2-assert -G -i  assert_param  /dev/hidraw5  |	fido2-assert  -V
	   pubkey es256

SEE ALSO
     fido2-cred(1), fido2-token(1)

FreeBSD ports 15.quarterly	  July 3, 2023			 FIDO2-ASSERT(1)
home | help