authentication: fido2: hide internal symbols from the API docs

A number of symbols in the public FIDO2 headers are implementation
details of the subsystem core. They are not part of the application API,
and they are not part of the contract with out-of-tree transport,
storage, user presence or attestation backends either.

Wrap them in @cond INTERNAL_HIDDEN blocks so they no longer show up in
the generated API documentation:

- CTAP2 status and command codes (enum fido2_status, enum fido2_cmd).
  The core casts the status to a raw response byte before handing the
  buffer to a transport, and dispatches on the raw command byte, so
  neither appears in any public signature.
- struct fido2_device_info, built by the core and consumed by the
  internal CBOR encoder, together with the constants that only exist to
  size or describe it: FIDO2_AAGUID_SIZE, FIDO2_MAX_VERSIONS,
  FIDO2_MAX_EXTENSIONS and FIDO2_TRANSPORT_{USB,BLE,NFC}.
- The credential ID and authenticatorData layout constants
  (FIDO2_DISCOVERABLE_CRED_ID_SIZE, FIDO2_NON_DISCOVERABLE_CRED_ID_SIZE,
  FIDO2_AUTH_DATA_HEADER_SIZE, FIDO2_ATTESTED_CRED_DATA_MAX_SIZE,
  FIDO2_AUTH_DATA_MAX_SIZE) and the authenticatorData flags
  (AUTH_DATA_FLAG_*).
- The COSE/ECDH key encoding constants
  (FIDO2_P256_UNCOMPRESSED_KEY_SIZE, FIDO2_P256_COORD_SIZE,
  FIDO2_EC_POINT_UNCOMPRESSED).

What a backend implementer needs stays documented: struct
fido2_credential and the macros sizing its fields, FIDO2_SHA256_SIZE,
FIDO2_PIN_HASH_SIZE, FIDO2_ECDSA_SIG_MAX_SIZE (used by an attestation
backend to size its signature buffer, as the in-tree self attestation
one does), FIDO2_EXT_*, enum fido2_cred_protect and enum fido2_cose_alg.

While at it, drop a stray "8" from the FIDO2_AUTH_DATA_MAX_SIZE brief
and add the missing @brief to FIDO2_ATTESTATION_FMT_MAX_LEN.

Signed-off-by: Benjamin Cabé <benjamin@zephyrproject.org>
Assisted-by: Claude:opus-5

Author: kartben

include/zephyr/authentication/fido2/fido2_attestation.h

@@ -30,7 +30,7 @@ extern "C" {
 #define FIDO2_ATTESTATION_FMT_PACKED  "packed"
 /** @brief No attestation */
 #define FIDO2_ATTESTATION_FMT_NONE    "none"
-/** Maximum attestation format identifier length. */
+/** @brief Maximum attestation format identifier length */
 #define FIDO2_ATTESTATION_FMT_MAX_LEN 32
 
 /**

include/zephyr/authentication/fido2/fido2_types.h

@@ -46,15 +46,20 @@ extern "C" {
 /** @brief Maximum user ID size in bytes */
 #define FIDO2_USER_ID_MAX_SIZE 64
 
-/** @brief AAGUID size in bytes */
-#define FIDO2_AAGUID_SIZE 16
-
 /** @brief SHA-256 hash size */
 #define FIDO2_SHA256_SIZE 32
 
 /** @brief PIN hash size */
 #define FIDO2_PIN_HASH_SIZE 16
 
+/** @brief ASN.1-encoded ECDSA signature length */
+#define FIDO2_ECDSA_SIG_MAX_SIZE 72
+
+/** @cond INTERNAL_HIDDEN */
+
+/** @brief AAGUID size in bytes */
+#define FIDO2_AAGUID_SIZE 16
+
 /** @brief Size of a discoverable credential ID */
 #define FIDO2_DISCOVERABLE_CRED_ID_SIZE 32
 
@@ -68,7 +73,7 @@ extern "C" {
 #define FIDO2_ATTESTED_CRED_DATA_MAX_SIZE                                                          \
 	(FIDO2_AAGUID_SIZE + 2 + FIDO2_CREDENTIAL_ID_MAX_SIZE + FIDO2_COSE_KEY_MAX_SIZE)
 
-/** @brief Maximum authenticatorData size 8 */
+/** @brief Maximum authenticatorData size */
 #define FIDO2_AUTH_DATA_MAX_SIZE (FIDO2_AUTH_DATA_HEADER_SIZE + FIDO2_ATTESTED_CRED_DATA_MAX_SIZE)
 
 /** @brief Maximum number of supported extensions */
@@ -86,8 +91,7 @@ extern "C" {
 /** @brief EC point prefix */
 #define FIDO2_EC_POINT_UNCOMPRESSED 0x04
 
-/** @brief ASN.1-encoded ECDSA signature length */
-#define FIDO2_ECDSA_SIG_MAX_SIZE 72
+/** @endcond */
 
 /** @brief Credential extension HMAC secret */
 #define FIDO2_EXT_HMAC_SECRET     BIT(0)
@@ -98,6 +102,8 @@ extern "C" {
 /** @brief Credential extension thirdPartyPayment */
 #define FIDO2_EXT_THIRD_PARTY_PAY BIT(3)
 
+/** @cond INTERNAL_HIDDEN */
+
 /** @brief Transport USB */
 #define FIDO2_TRANSPORT_USB BIT(0)
 /** @brief Transport BLE */
@@ -178,6 +184,8 @@ enum fido2_cmd {
 	FIDO2_CMD_SELECTION = 0x0B,          /**< Authenticator selection */
 };
 
+/** @endcond */
+
 /** @brief Credential protection levels */
 enum fido2_cred_protect {
 	/** UV optional; credential usable without verification */
@@ -230,6 +238,8 @@ struct fido2_credential {
 	uint8_t cred_protect;
 };
 
+/** @cond INTERNAL_HIDDEN */
+
 /**
  * @brief Device information returned by authenticatorGetInfo.
  */
@@ -277,6 +287,8 @@ struct fido2_device_info {
 	uint8_t min_pin_length;
 };
 
+/** @endcond */
+
 #ifdef __cplusplus
 }
 #endif