Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

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 op-
       eration.	 See the "OUTPUT FORMAT" section for details.

       If an assertion is successfully obtained	or verified, fido2-assert  ex-
       its 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
	       (denoting ECDSA over NIST P-256 with SHA-256), rs256  (denoting
	       2048-bit	 RSA with PKCS#1.5 padding and SHA-256), or eddsa (de-
	       noting EDDSA over Curve25519 with SHA-512).   If	 type  is  not
	       specified, es256	is assumed.

       -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	exten-
	       sion.   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
	       specified, fido2-assert will not	expect a credential id in  its
	       input,  and  may	 output	multiple assertions.  Resident creden-
	       tials 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  en-
		       abled or	disabled.

	       pin=true|false
		       Tells  fido2-assert whether to prompt for a PIN and re-
		       quest 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 otherwise.

       -v      If obtaining an assertion, prompt the user for a	 PIN  and  re-
	       quest  user  verification from the authenticator.  If verifying
	       an assertion, check  whether  the  user	verification  bit  was
	       signed by the authenticator.

       -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.
       Otherwise, stdin	is used.

INPUT FORMAT
       The  input  of  fido2-assert consists of	base64 blobs and UTF-8 strings
       separated 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.	  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
       separated 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.	  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  authenti-
       cator 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 14.quarterly	 July 3, 2023		       FIDO2-ASSERT(1)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=fido2-assert&sektion=1&manpath=FreeBSD+Ports+14.3.quarterly>

home | help