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
       constituent parts, please refer to the Web Authentication (webauthn) standard.

       The fido_assert_set_count() function sets the number of assertion statements 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_clientdata_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,  and  FIDO_EXT_LARGEBLOB_KEY  extensions  are
       supported.  If flags is zero, the extensions of assert are cleared.

       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_assert_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_assert_set_winhello_appid().  If the
       second assertion succeeds, fido_assert_rp_id(3) will point to the U2F AppID  once  fido_dev_get_assert(3)
       completes.   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  platforms  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 distinct situations: when asking a
       FIDO2 device to produce a series of assertion statements, prior to fido_dev_get_assert(3)  (i.e,  in  the
       context  of  a FIDO2 client), or when verifying assertion statements using fido_assert_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  error  codes  returned  by  the
       fido_assert_set_authdata set of functions are defined 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)

Debian                                            April 8, 2023                      FIDO_ASSERT_SET_AUTHDATA(3)