home | help 
FIDO_ASSERT_SET_AUTHDATA(3)  Library Functions ManualFIDO_ASSERT_SET_AUTHDATA(3)

NAME
     fido_assert_set_authdata,			   fido_assert_set_authdata_raw,
     fido_assert_set_clientdata,		fido_assert_set_clientdata_hash,
     fido_assert_set_count,			     fido_assert_set_extensions,
     fido_assert_set_hmac_salt, fido_assert_set_hmac_secret, fido_assert_set_up,
     fido_assert_set_uv,	fido_assert_set_rp,	    fido_assert_set_sig,
     fido_assert_set_winhello_appid -- set parameters of a FIDO2 assertion

SYNOPSIS
     #include <fido.h>

     typedef enum {
	     FIDO_OPT_OMIT = 0, /* use authenticator's default */
	     FIDO_OPT_FALSE,	/* explicitly set option to false */
	     FIDO_OPT_TRUE,	/* explicitly set option to true */
     } fido_opt_t;

     int
     fido_assert_set_authdata(fido_assert_t *assert, size_t idx,
	 const unsigned char *ptr, size_t len);

     int
     fido_assert_set_authdata_raw(fido_assert_t *assert, size_t idx,
	 const unsigned char *ptr, size_t len);

     int
     fido_assert_set_clientdata(fido_assert_t *assert, const unsigned char *ptr,
	 size_t len);

     int
     fido_assert_set_clientdata_hash(fido_assert_t *assert,
	 const unsigned char *ptr, size_t len);

     int
     fido_assert_set_count(fido_assert_t *assert, size_t n);

     int
     fido_assert_set_extensions(fido_assert_t *assert, int flags);

     int
     fido_assert_set_hmac_salt(fido_assert_t *assert, const unsigned char *ptr,
	 size_t len);

     int
     fido_assert_set_hmac_secret(fido_assert_t *assert, size_t idx,
	 const unsigned char *ptr, size_t len);

     int
     fido_assert_set_up(fido_assert_t *assert, fido_opt_t up);

     int
     fido_assert_set_uv(fido_assert_t *assert, fido_opt_t uv);

     int
     fido_assert_set_rp(fido_assert_t *assert, const char *id);

     int
     fido_assert_set_sig(fido_assert_t *assert, size_t idx,
	 const unsigned char *ptr, size_t len);

     int
     fido_assert_set_winhello_appid(fido_assert_t *assert, const char *id);

DESCRIPTION
     The fido_assert_set_authdata set of functions define the various parameters
     of  a  FIDO2  assertion, allowing a fido_assert_t type to be prepared for a
     subsequent call to fido_dev_get_assert(3)	or  fido_assert_verify(3).   For
     the  complete specification of a FIDO2 assertion and the format of its con-
     stituent parts, please refer to the Web Authentication (webauthn) standard.

     The fido_assert_set_count() function sets the number  of  assertion  state-
     ments in assert to n.

     The  fido_assert_set_authdata() and fido_assert_set_sig() functions set the
     authenticator data and signature parts of the statement with index  idx  of
     assert  to  ptr, where ptr points to len bytes.  A copy of ptr is made, and
     no references to the passed pointer are kept.  Please note that  the  first
     assertion	statement  of  assert  has  an idx of 0.  The authenticator data
     passed to fido_assert_set_authdata() must be a CBOR-encoded byte string, as
     obtained from fido_assert_authdata_ptr().	Alternatively, a raw binary blob
     may be passed to fido_assert_set_authdata_raw().

     The fido_assert_set_clientdata_hash() function sets the client data hash of
     assert to ptr, where ptr points to len bytes.  A copy of ptr is  made,  and
     no references to the passed pointer are kept.

     The  fido_assert_set_clientdata() function allows an application to set the
     client data hash of assert by specifying the  assertion's	unhashed  client
     data.   This is required by Windows Hello, which calculates the client data
     hash internally.  For compatibility with Windows Hello, applications should
     use   fido_assert_set_clientdata()   instead   of	 fido_assert_set_client-
     data_hash().

     The  fido_assert_set_rp()	function  sets	the  relying party id of assert,
     where id is a NUL-terminated UTF-8 string.  The content of  id  is  copied,
     and no references to the passed pointer are kept.

     The  fido_assert_set_extensions() function sets the extensions of assert to
     the  bitmask  flags.   At	the   moment,	only   the   FIDO_EXT_CRED_BLOB,
     FIDO_EXT_HMAC_SECRET,  FIDO_EXT_LARGEBLOB_KEY,  and FIDO_EXT_PAYMENT exten-
     sions are supported.  If flags  is  zero,	the  extensions  of  assert  are
     cleared.	Enabling  FIDO_EXT_PAYMENT  does not affect how fido_assert_ver-
     ify(3) verifies the RP ID; the platform is responsible for determining what
     constitutes a payment authentication.

     The fido_assert_set_hmac_salt() and fido_assert_set_hmac_secret() functions
     set the hmac-salt and hmac-secret parts of assert to ptr, where ptr  points
     to  len  bytes.   A  copy	of  ptr is made, and no references to the passed
     pointer are kept.	The HMAC Secret (hmac-secret) Extension is  a  CTAP  2.0
     extension.  Note that the resulting hmac-secret varies according to whether
     user  verification  was  performed  by  the  authenticator.   The	fido_as-
     sert_set_hmac_secret() function is normally only useful when writing tests.

     The fido_assert_set_up() and  fido_assert_set_uv()  functions  set  the  up
     (user  presence) and uv (user verification) attributes of assert.	Both are
     FIDO_OPT_OMIT by default, allowing the authenticator  to  use  its  default
     settings.

     The  fido_assert_set_winhello_appid()  function sets the U2F application id
     ("U2F AppID") of assert, where id is a NUL-terminated  UTF-8  string.   The
     content  of id is copied, and no references to the passed pointer are kept.
     The fido_assert_set_winhello_appid() function is a no-op unless  assert  is
     passed   to   fido_dev_get_assert(3)   with   a   device	dev   on   which
     fido_dev_is_winhello(3) holds true.  In this case, libfido2  will	instruct
     Windows  Hello  to  try  the  assertion  twice, first with the id passed to
     fido_assert_set_rp(), and a second time with  the	id  passed  to	fido_as-
     sert_set_winhello_appid().   If  the  second  assertion  succeeds, fido_as-
     sert_rp_id(3) will point to the U2F AppID once fido_dev_get_assert(3)  com-
     pletes.   This  mechanism	exists	in Windows Hello to ensure U2F backwards
     compatibility without the	application  inadvertently  prompting  the  user
     twice.   Note  that fido_assert_set_winhello_appid() is not needed on plat-
     forms offering CTAP primitives, since the	authenticator  can  be	silently
     probed for the existence of U2F credentials.

     Use of the fido_assert_set_authdata set of functions may happen in two dis-
     tinct  situations: when asking a FIDO2 device to produce a series of asser-
     tion statements, prior to fido_dev_get_assert(3) (i.e, in the context of  a
     FIDO2  client),  or  when	verifying  assertion  statements  using fido_as-
     sert_verify(3) (i.e, in the context of a FIDO2 server).

     For a complete description of the generation of a FIDO2 assertion	and  its
     verification,  please  refer to the FIDO2 specification.  An example of how
     to use the fido_assert_set_authdata set of functions can be  found  in  the
     examples/assert.c file shipped with libfido2.

RETURN VALUES
     The  fido_assert_set_authdata functions return FIDO_OK on success.  The er-
     ror codes returned by the fido_assert_set_authdata set of functions are de-
     fined in <fido/err.h>.

SEE ALSO
     fido_assert_allow_cred(3),  fido_assert_verify(3),  fido_dev_get_assert(3),
     fido_dev_is_winhello(3)

FreeBSD ports 15.quarterly	 March 26, 2026      FIDO_ASSERT_SET_AUTHDATA(3)
home | help