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)