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

NAME
     fido_cbor_info_new,       fido_cbor_info_free,	 fido_dev_get_cbor_info,
     fido_cbor_info_decrypt,			      fido_cbor_info_aaguid_ptr,
     fido_cbor_info_attfmts_ptr,		       fido_cbor_info_encid_ptr,
     fido_cbor_info_id_ptr,			    fido_cbor_info_encstate_ptr,
     fido_cbor_info_state_ptr,			  fido_cbor_info_extensions_ptr,
     fido_cbor_info_pin_policy_url_ptr, 	   fido_cbor_info_protocols_ptr,
     fido_cbor_info_reset_transports_ptr,	  fido_cbor_info_transports_ptr,
     fido_cbor_info_versions_ptr,		fido_cbor_info_options_name_ptr,
     fido_cbor_info_options_value_ptr,		  fido_cbor_info_algorithm_type,
     fido_cbor_info_algorithm_cose,		 fido_cbor_info_algorithm_count,
     fido_cbor_info_certs_name_ptr,		 fido_cbor_info_certs_value_ptr,
     fido_cbor_info_certs_len,			     fido_cbor_info_cfgcmds_ptr,
     fido_cbor_info_cfgcmds_len,		      fido_cbor_info_aaguid_len,
     fido_cbor_info_attfmts_len,		       fido_cbor_info_encid_len,
     fido_cbor_info_id_len,			    fido_cbor_info_encstate_len,
     fido_cbor_info_state_len,			  fido_cbor_info_extensions_len,
     fido_cbor_info_pin_policy_url_len, 	   fido_cbor_info_protocols_len,
     fido_cbor_info_reset_transports_len,	  fido_cbor_info_transports_len,
     fido_cbor_info_versions_len,		     fido_cbor_info_options_len,
     fido_cbor_info_long_touch_reset,		       fido_cbor_info_maxmsgsiz,
     fido_cbor_info_maxcredbloblen,		   fido_cbor_info_maxcredcntlst,
     fido_cbor_info_maxcredidlen,		    fido_cbor_info_maxlargeblob,
     fido_cbor_info_maxrpid_minpinlen,		       fido_cbor_info_maxpinlen,
     fido_cbor_info_minpinlen,			      fido_cbor_info_pin_policy,
     fido_cbor_info_fwversion,			     fido_cbor_info_uv_attempts,
     fido_cbor_info_uv_modality,	      fido_cbor_info_uv_count_since_pin,
     fido_cbor_info_rk_remaining,  fido_cbor_info_new_pin_required -- FIDO2 CBOR
     Info API

SYNOPSIS
     #include <fido.h>

     fido_cbor_info_t *
     fido_cbor_info_new(void);

     void
     fido_cbor_info_free(fido_cbor_info_t **ci_p);

     int
     fido_dev_get_cbor_info(fido_dev_t *dev, fido_cbor_info_t *ci);

     int
     fido_cbor_info_decrypt(fido_cbor_info_t *ci, const unsigned char *ppuat,
	 size_t ppuat_len);

     const unsigned char *
     fido_cbor_info_aaguid_ptr(const fido_cbor_info_t *ci);

     char **
     fido_cbor_info_attfmts_ptr(const fido_cbor_info_t *ci);

     const uint8_t *
     fido_cbor_info_cfgcmds_ptr(const fido_cbor_info_t *ci);

     const unsigned char *
     fido_cbor_info_encid_ptr(const fido_cbor_info_t *ci);

     const unsigned char *
     fido_cbor_info_id_ptr(const fido_cbor_info_t *ci);

     const unsigned char *
     fido_cbor_info_encstate_ptr(const fido_cbor_info_t *ci);

     const unsigned char *
     fido_cbor_info_state_ptr(const fido_cbor_info_t *ci);

     char **
     fido_cbor_info_extensions_ptr(const fido_cbor_info_t *ci);

     const unsigned char *
     fido_cbor_info_pin_policy_url_ptr(const fido_cbor_info_t *ci);

     const uint8_t *
     fido_cbor_info_protocols_ptr(const fido_cbor_info_t *ci);

     char **
     fido_cbor_info_reset_transports_ptr(const fido_cbor_info_t *ci);

     char **
     fido_cbor_info_transports_ptr(const fido_cbor_info_t *ci);

     char **
     fido_cbor_info_versions_ptr(const fido_cbor_info_t *ci);

     char **
     fido_cbor_info_options_name_ptr(const fido_cbor_info_t *ci);

     const bool *
     fido_cbor_info_options_value_ptr(const fido_cbor_info_t *ci);

     const char *
     fido_cbor_info_algorithm_type(const fido_cbor_info_t *ci, size_t idx);

     int
     fido_cbor_info_algorithm_cose(const fido_cbor_info_t *ci, size_t idx);

     size_t
     fido_cbor_info_algorithm_count(const fido_cbor_info_t *ci);

     char **
     fido_cbor_info_certs_name_ptr(const fido_cbor_info_t *ci);

     const uint64_t *
     fido_cbor_info_certs_value_ptr(const fido_cbor_info_t *ci);

     size_t
     fido_cbor_info_certs_len(const fido_cbor_info_t *ci);

     size_t
     fido_cbor_info_aaguid_len(const fido_cbor_info_t *ci);

     size_t
     fido_cbor_info_attfmts_len(const fido_cbor_info_t *ci);

     size_t
     fido_cbor_info_cfgcmds_len(const fido_cbor_info_t *ci);

     size_t
     fido_cbor_info_encid_len(const fido_cbor_info_t *ci);

     size_t
     fido_cbor_info_id_len(const fido_cbor_info_t *ci);

     size_t
     fido_cbor_info_encstate_len(const fido_cbor_info_t *ci);

     size_t
     fido_cbor_info_state_len(const fido_cbor_info_t *ci);

     size_t
     fido_cbor_info_extensions_len(const fido_cbor_info_t *ci);

     size_t
     fido_cbor_info_pin_policy_url_len(const fido_cbor_info_t *ci);

     size_t
     fido_cbor_info_protocols_len(const fido_cbor_info_t *ci);

     size_t
     fido_cbor_info_reset_transports_len(const fido_cbor_info_t *ci);

     size_t
     fido_cbor_info_transports_len(const fido_cbor_info_t *ci);

     size_t
     fido_cbor_info_versions_len(const fido_cbor_info_t *ci);

     size_t
     fido_cbor_info_options_len(const fido_cbor_info_t *ci);

     bool
     fido_cbor_info_long_touch_reset(const fido_cbor_info_t *ci);

     uint64_t
     fido_cbor_info_maxmsgsiz(const fido_cbor_info_t *ci);

     uint64_t
     fido_cbor_info_maxcredbloblen(const fido_cbor_info_t *ci);

     uint64_t
     fido_cbor_info_maxcredcntlst(const fido_cbor_info_t *ci);

     uint64_t
     fido_cbor_info_maxcredidlen(const fido_cbor_info_t *ci);

     uint64_t
     fido_cbor_info_maxlargeblob(const fido_cbor_info_t *ci);

     uint64_t
     fido_cbor_info_maxrpid_minpinlen(const fido_cbor_info_t *ci);

     uint64_t
     fido_cbor_info_maxpinlen(const fido_cbor_info_t *ci);

     uint64_t
     fido_cbor_info_minpinlen(const fido_cbor_info_t *ci);

     int
     fido_cbor_info_pin_policy(const fido_cbor_info_t *ci);

     uint64_t
     fido_cbor_info_fwversion(const fido_cbor_info_t *ci);

     uint64_t
     fido_cbor_info_uv_attempts(const fido_cbor_info_t *ci);

     uint64_t
     fido_cbor_info_uv_modality(const fido_cbor_info_t *ci);

     int64_t
     fido_cbor_info_uv_count_since_pin(const fido_cbor_info_t *ci);

     int64_t
     fido_cbor_info_rk_remaining(const fido_cbor_info_t *ci);

     bool
     fido_cbor_info_new_pin_required(const fido_cbor_info_t *ci);

DESCRIPTION
     The fido_cbor_info_new() function returns a pointer to a  newly  allocated,
     empty  fido_cbor_info_t  type.   If memory cannot be allocated, NULL is re-
     turned.

     The fido_cbor_info_free() function releases the memory backing *ci_p, where
     *ci_p must have been previously allocated by fido_cbor_info_new().  On  re-
     turn,  *ci_p  is  set  to NULL.  Either ci_p or *ci_p may be NULL, in which
     case fido_cbor_info_free() is a NOP.

     The fido_dev_get_cbor_info() function transmits a CTAP_CBOR_GETINFO command
     to dev and fills ci with attributes retrieved from the command's  response.
     The fido_dev_get_cbor_info() function may block.

     The  fido_cbor_info_decrypt()  function decrypts the encrypted fields of ci
     using the persistent PIN/UV Auth token  referenced  by  ppuat,  which  must
     point to at least ppuat_len bytes.

     The	fido_cbor_info_aaguid_ptr(),	   fido_cbor_info_attfmts_ptr(),
     fido_cbor_info_cfgcmds_ptr(),		     fido_cbor_info_encid_ptr(),
     fido_cbor_info_id_ptr(),			  fido_cbor_info_encstate_ptr(),
     fido_cbor_info_state_ptr(),		fido_cbor_info_extensions_ptr(),
     fido_cbor_info_pin_policy_url_ptr(),	 fido_cbor_info_protocols_ptr(),
     fido_cbor_info_reset_transports_ptr(), fido_cbor_info_transports_ptr(), and
     fido_cbor_info_versions_ptr() functions return pointers to the  authentica-
     tor  attestation GUID, supported attestation formats, supported authentica-
     tor config commands, encrypted identifier, decrypted identifier,  encrypted
     credential  store state, decrypted credential store state, supported exten-
     sions, PIN complexity policy URL, PIN protocol, transports for  authentica-
     tor  reset,  transports, and CTAP version strings of ci.  The corresponding
     length of a given attribute can be obtained by fido_cbor_info_aaguid_len(),
     fido_cbor_info_attfmts_len(),		   fido_cbor_info_cfgcmds_len(),
     fido_cbor_info_encid_len(),   fido_cbor_info_id_len(),  fido_cbor_info_enc-
     state_len(),  fido_cbor_info_state_len(),	fido_cbor_info_extensions_len(),
     fido_cbor_info_pin_policy_url_len(),	 fido_cbor_info_protocols_len(),
     fido_cbor_info_reset_transports_len(), fido_cbor_info_transports_len(),  or
     fido_cbor_info_versions_len().   The  supported  attestation  formats,  en-
     crypted identifier, PIN complexity policy URL, and transports for authenti-
     cator reset attributes are CTAP 2.2 additions.  The supported authenticator
     config commands and encrypted credential store state  attributes  are  CTAP
     2.3 additions.

     The      fido_cbor_info_options_name_ptr()      and      fido_cbor_info_op-
     tions_value_ptr() functions return pointers to the array  of  option  names
     and  their respective values in ci.  The length of the options array is re-
     turned by fido_cbor_info_options_len().

     The fido_cbor_info_algorithm_count() function returns the	number	of  sup-
     ported  algorithms in ci.	The fido_cbor_info_algorithm_cose() function re-
     turns the COSE identifier of algorithm idx in ci, or 0 if the COSE  identi-
     fier is unknown or unset.	The fido_cbor_info_algorithm_type() function re-
     turns  the  type  of  algorithm  idx  in  ci, or NULL if the type is unset.
     Please note that the first algorithm in ci has an idx (index) value of 0.

     The  fido_cbor_info_certs_name_ptr()  and	fido_cbor_info_certs_value_ptr()
     functions return pointers to the array of certification names and their re-
     spective  values in ci.  The length of the certifications array is returned
     by fido_cbor_info_certs_len().

     The fido_cbor_info_maxmsgsiz() function returns the  maximum  message  size
     attribute of ci.

     The fido_cbor_info_maxcredbloblen() function returns the maximum "credBlob"
     length in bytes supported by the authenticator as reported in ci.

     The  fido_cbor_info_maxcredcntlst()  function returns the maximum supported
     number of credentials in a single credential ID list as reported in ci.

     The fido_cbor_info_maxcredidlen() function returns  the  maximum  supported
     length of a credential ID as reported in ci.

     The  fido_cbor_info_maxrpid_minpinlen() function returns the maximum number
     of RP IDs that may be passed  to  fido_dev_set_pin_minlen_rpid(3),  as  re-
     ported in ci.  The minimum PIN length attribute is a CTAP 2.1 addition.  If
     the    attribute	 is   not   advertised	 by   the   authenticator,   the
     fido_cbor_info_maxrpid_minpinlen() function returns zero.

     The fido_cbor_info_maxlargeblob() function returns the  maximum  length  in
     bytes of an authenticator's serialized largeBlob array as reported in ci.

     The  fido_cbor_info_maxpinlen() function returns the maximum PIN length en-
     forced by the authenticator as reported in ci.  The maximum PIN length  at-
     tribute  is a CTAP 2.2 addition.  If the attribute is not advertised by the
     authenticator, the fido_cbor_info_maxpinlen() function returns zero.

     The fido_cbor_info_minpinlen() function returns the minimum PIN length  en-
     forced  by the authenticator as reported in ci.  The minimum PIN length at-
     tribute is a CTAP 2.1 addition.  If the attribute is not advertised by  the
     authenticator, the fido_cbor_info_minpinlen() function returns zero.

     The  fido_cbor_info_pin_policy() function returns information about whether
     an additional PIN complexity policy is enforced by  the  authenticator,  as
     reported by ci. The PIN complexity policy attribute is a CTAP 2.2 addition.
     The  value is 1 if an additional policy is enforced, 0 if no such policy is
     enforced, or -1 if the feature is not supported by the authenticator.

     The fido_cbor_info_fwversion() function returns the  firmware  version  at-
     tribute of ci.

     The fido_cbor_info_uv_attempts() function returns the number of UV attempts
     that  the	platform  may attempt before falling back to PIN authentication.
     If 1, then all fido_dev_get_uv_retry_count(3) retries  are  handled  inter-
     nally  by	the  authenticator  and the platform may only attempt non-PIN UV
     once.  The UV attempts attribute is a CTAP 2.1 addition.  If the  attribute
     is  not  advertised  by the authenticator, the fido_cbor_info_uv_attempts()
     function returns zero.

     The fido_cbor_info_uv_count_since_pin()  function	returns  the  number  of
     built-in  UV  operations since the last PIN entry.  The UV count since last
     PIN entry attribute is a CTAP 2.2 addition.  If the attribute is not adver-
     tised by the authenticator, the  fido_cbor_info_uv_count_since_pin()  func-
     tion returns -1.

     The  fido_cbor_info_uv_modality()	function  returns a bitmask representing
     different UV modes supported by the authenticator, as defined in  the  FIDO
     Registry  of  Predefined Values and reported in ci.  See the FIDO_UV_MODE_*
     definitions in <fido/param.h> for the set of values defined by libfido2 and
     a brief description of each.  The UV modality attribute is a CTAP 2.1 addi-
     tion.  If the  attribute  is  not	advertised  by	the  authenticator,  the
     fido_cbor_info_uv_modality() function returns zero.

     The  fido_cbor_info_rk_remaining() function returns the estimated number of
     additional resident/discoverable credentials that can be stored on the  au-
     thenticator  as reported in ci.  The estimated number of remaining resident
     credentials is a CTAP 2.1 addition.  If the attribute is not advertised  by
     the authenticator, the fido_cbor_info_rk_remaining() function returns -1.

     The fido_cbor_info_new_pin_required() function returns whether a new PIN is
     required	 by    the    authenticator    as    reported	 in    ci.    If
     fido_cbor_info_new_pin_required() returns true,  operations  requiring  PIN
     authentication  will fail until a new PIN is set on the authenticator.  The
     fido_dev_set_pin(3) function can be used to set a new PIN.

     The fido_cbor_info_long_touch_reset() function returns true if a long touch
     is required to reset the authenticator.  The long touch for reset attribute
     is a CTAP 2.2 addition.  If the attribute is not advertised by the  authen-
     ticator, the fido_cbor_info_long_touch_reset() function returns false.

     A	complete  example  of  how  to	use  these functions can be found in the
     example/info.c file shipped with libfido2.

RETURN VALUES
     The error codes returned by fido_dev_get_cbor_info() and fido_cbor_info_de-
     crypt() are defined in <fido/err.h>.  On success, FIDO_OK is returned.

     The	fido_cbor_info_aaguid_ptr(),	     fido_cbor_info_encid_ptr(),
     fido_cbor_info_encstate_ptr(),		fido_cbor_info_extensions_ptr(),
     fido_cbor_info_protocols_ptr(),		fido_cbor_info_transports_ptr(),
     fido_cbor_info_versions_ptr(),    fido_cbor_info_options_name_ptr(),    and
     fido_cbor_info_options_value_ptr() functions return NULL if the  respective
     field  in	ci  is absent.	If not NULL, returned pointers are guaranteed to
     exist until any API function that takes ci without the const  qualifier  is
     invoked.

SEE ALSO
     fido_dev_get_puat(3),   fido_dev_get_uv_retry_count(3),   fido_dev_open(3),
     fido_dev_set_pin(3), fido_dev_set_pin_minlen_rpid(3)

     FIDO Registry of Predefined Values,  https://fidoalliance.org/specs/common-
     specs/fido-registry-v2.2-rd-20210525.html,  FIDO  Alliance, 2021-05-25, Re-
     view Draft, Version 2.2.

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