home | help 
FIDO_CRED_SET_AUTHDATA(3)    Library Functions Manual  FIDO_CRED_SET_AUTHDATA(3)

NAME
     fido_cred_set_authdata,  fido_cred_set_authdata_raw, fido_cred_set_attstmt,
     fido_cred_set_attobj,	  fido_cred_set_x509,	      fido_cred_set_sig,
     fido_cred_set_id,	fido_cred_set_clientdata, fido_cred_set_clientdata_hash,
     fido_cred_set_rp,	     fido_cred_set_user,	fido_cred_set_entattest,
     fido_cred_set_extensions,	  fido_cred_set_blob,	fido_cred_set_hmac_salt,
     fido_cred_set_hmac_secret,  fido_cred_set_pin_minlen,   fido_cred_set_prot,
     fido_cred_set_rk,	fido_cred_set_uv,  fido_cred_set_fmt, fido_cred_set_type
     -- set parameters of a FIDO2 credential

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_cred_set_authdata(fido_cred_t *cred, const unsigned char *ptr,
	 size_t len);

     int
     fido_cred_set_authdata_raw(fido_cred_t *cred, const unsigned char *ptr,
	 size_t len);

     int
     fido_cred_set_attstmt(fido_cred_t *cred, const unsigned char *ptr,
	 size_t len);

     int
     fido_cred_set_attobj(fido_cred_t *cred, const unsigned char *ptr,
	 size_t len);

     int
     fido_cred_set_x509(fido_cred_t *cred, const unsigned char *ptr,
	 size_t len);

     int
     fido_cred_set_sig(fido_cred_t *cred, const unsigned char *ptr, size_t len);

     int
     fido_cred_set_id(fido_cred_t *cred, const unsigned char *ptr, size_t len);

     int
     fido_cred_set_clientdata(fido_cred_t *cred, const unsigned char *ptr,
	 size_t len);

     int
     fido_cred_set_clientdata_hash(fido_cred_t *cred, const unsigned char *ptr,
	 size_t len);

     int
     fido_cred_set_rp(fido_cred_t *cred, const char *id, const char *name);

     int
     fido_cred_set_user(fido_cred_t *cred, const unsigned char *user_id,
	 size_t user_id_len, const char *name, const char *display_name,
	 const char *icon);

     int
     fido_cred_set_entattest(fido_cred_t *cred, int ea);

     int
     fido_cred_set_extensions(fido_cred_t *cred, int flags);

     int
     fido_cred_set_blob(fido_cred_t *cred, const unsigned char *ptr,
	 size_t len);

     int
     fido_cred_set_hmac_salt(fido_cred_t *cred, const unsigned char *ptr,
	 size_t len);

     int
     fido_cred_set_hmac_secret(fido_cred_t *cred, const unsigned char *ptr,
	 size_t len);

     int
     fido_cred_set_pin_minlen(fido_cred_t *cred, size_t len);

     int
     fido_cred_set_prot(fido_cred_t *cred, int prot);

     int
     fido_cred_set_rk(fido_cred_t *cred, fido_opt_t rk);

     int
     fido_cred_set_uv(fido_cred_t *cred, fido_opt_t uv);

     int
     fido_cred_set_fmt(fido_cred_t *cred, const char *ptr);

     int
     fido_cred_set_type(fido_cred_t *cred, int cose_alg);

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

     The  fido_cred_set_authdata(),  fido_cred_set_attstmt(),  fido_cred_set_at-
     tobj(),  fido_cred_set_x509(), fido_cred_set_sig(), fido_cred_set_id(), and
     fido_cred_set_clientdata_hash() functions set the authenticator  data,  at-
     testation	statement, attestation object, attestation certificate, attesta-
     tion signature, id, and client data hash parts of cred to	ptr,  where  ptr
     points  to  len  bytes.   A  copy	of ptr is made, and no references to the
     passed pointer are kept.

     The authenticator data passed to fido_cred_set_authdata() must be	a  CBOR-
     encoded  byte  string, as obtained from fido_cred_authdata_ptr().	Alterna-
     tively, a raw binary blob may be  passed  to  fido_cred_set_authdata_raw().
     An  application  calling  fido_cred_set_authdata()  does  not  need to call
     fido_cred_set_id().  The latter is meant to be used in contexts  where  the
     credential's authenticator data is not available.

     The attestation statement passed to fido_cred_set_attstmt() must be a CBOR-
     encoded  map,  as	obtained  from	fido_cred_attstmt_ptr().  An application
     calling fido_cred_set_attstmt() does not need to call  fido_cred_set_x509()
     or  fido_cred_set_sig().	The  latter two are meant to be used in contexts
     where the credential's complete attestation statement is not  available  or
     required.

     The  attestation object passed to fido_cred_set_attobj() must be a CBOR-en-
     coded map containing "authData",  "fmt",  and  "attStmt".	 An  application
     calling  fido_cred_set_attobj()  does not need to call fido_cred_set_fmt(),
     fido_cred_set_attstmt(), fido_cred_set_authdata(),  or  fido_cred_set_auth-
     data_raw().  fido_cred_set_attobj() may be useful in applications interfac-
     ing with the WebAuthn API, removing the need to first parse the attestation
     object to verify the credential.

     The  fido_cred_set_clientdata()  function	allows an application to set the
     client data hash of cred by specifying  the  credential'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_cred_set_clientdata() instead of fido_cred_set_clientdata_hash().

     The fido_cred_set_rp() function sets the relying party id and name  parame-
     ters of cred, where id and name are NUL-terminated UTF-8 strings.	The con-
     tents  of	id and name are copied, and no references to the passed pointers
     are kept.

     The fido_cred_set_user() function sets the user attributes of  cred,  where
     user_id  points  to  user_id_len bytes and name, display_name, and icon are
     NUL-terminated UTF-8 strings.  The contents of user_id, name, display_name,
     and icon are copied, and no references to the  passed  pointers  are  kept.
     Previously   set	user   attributes   are  flushed.   The  user_id,  name,
     display_name, and icon parameters may be NULL.

     The fido_cred_set_entattest() function sets the enterprise attestation mode
     of  cred  to  ea.	 At  the  moment,  only  the  FIDO_ENTATTEST_VENDOR  and
     FIDO_ENTATTEST_PLATFORM modes are supported.  By default, or if ea is zero,
     no enterprise attestation is requested.

     The  fido_cred_set_extensions() function sets the extensions of cred to the
     bitmask   flags.	 At   the   moment,   only    the    FIDO_EXT_CRED_BLOB,
     FIDO_EXT_CRED_PROTECT,    FIDO_EXT_HMAC_SECRET,	FIDO_EXT_HMAC_SECRET_MC,
     FIDO_EXT_MINPINLEN, FIDO_EXT_LARGEBLOB_KEY, and FIDO_EXT_PAYMENT extensions
     are supported.  If flags is zero, the extensions of cred are cleared.

     The fido_cred_set_blob() function sets the "credBlob"  to	be  stored  with
     cred to the data pointed to by ptr, which must be len bytes long.

     The fido_cred_set_hmac_salt() and fido_cred_set_hmac_secret() functions set
     the hmac-salt and hmac-secret parts of cred 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 MakeCredential (hmac-secret-mc) extension is a  CTAP
     2.2  extension.   Note  that  the resulting hmac-secret varies according to
     whether  user  verification  was  performed  by  the  authenticator.    The
     fido_cred_set_hmac_secret()  function  is normally only useful when writing
     tests.

     The   fido_cred_set_pin_minlen()	function   enables    the    CTAP    2.1
     FIDO_EXT_MINPINLEN  extension  on	cred  and  sets the expected minimum PIN
     length of cred to len, where len is greater than zero.  If len is zero, the
     FIDO_EXT_MINPINLEN extension is disabled on cred.

     The    fido_cred_set_prot()    function	enables     the     CTAP     2.1
     FIDO_EXT_CRED_PROTECT  extension on cred and sets the protection of cred to
     the scalar prot.	At  the  moment,  only	the  FIDO_CRED_PROT_UV_OPTIONAL,
     FIDO_CRED_PROT_UV_OPTIONAL_WITH_ID,  and FIDO_CRED_PROT_UV_REQUIRED protec-
     tions are supported.  If prot is zero, the protection of cred is cleared.

     The  fido_cred_set_rk()  and  fido_cred_set_uv()  functions  set	the   rk
     (resident/discoverable  key) and uv (user verification) attributes of cred.
     Both are FIDO_OPT_OMIT by default, allowing the authenticator  to	use  its
     default settings.

     The  fido_cred_set_fmt()  function  sets  the  attestation statement format
     identifier of cred to fmt, where fmt must be packed  (the	format	used  in
     FIDO2),  fido-u2f	(the  format  used  in	U2F),  tpm  (the  format used by
     TPM-based authenticators), or none.  A copy of fmt is made, and  no  refer-
     ences  to	the  passed  pointer are kept.	Note that not all authenticators
     support FIDO2 and therefore may only be able to generate fido-u2f	attesta-
     tion statements.

     The  fido_cred_set_type() function sets the type of cred to cose_alg, where
     cose_alg is COSE_ES256, COSE_ES384, COSE_RS256, or COSE_EDDSA.  The type of
     a credential may only be set once.  Note that not all  authenticators  sup-
     port COSE_RS256, COSE_ES384, or COSE_EDDSA.

     Use  of  the fido_cred_set_authdata set of functions may happen in two dis-
     tinct situations: when generating a new credential on a FIDO2 device, prior
     to fido_dev_make_cred(3) (i.e, in the context of a FIDO2 client),	or  when
     validating  a  generated  credential using fido_cred_verify(3) (i.e, in the
     context of a FIDO2 server).

     For a complete description of the generation of a FIDO2 credential and  its
     verification, please refer to the FIDO2 specification.  A concrete utilisa-
     tion example of the fido_cred_set_authdata set of functions can be found in
     the cred.c example shipped with libfido2.

RETURN VALUES
     The error codes returned by the fido_cred_set_authdata set of functions are
     defined in <fido/err.h>.  On success, FIDO_OK is returned.

SEE ALSO
     fido_cred_exclude(3), fido_cred_verify(3), fido_dev_make_cred(3)

FreeBSD ports 15.quarterly	 March 10, 2026        FIDO_CRED_SET_AUTHDATA(3)
home | help