Add references and decritpions to API 52/308352/2
authorDongsun Lee <ds73.lee@samsung.com>
Thu, 21 Mar 2024 07:58:19 +0000 (16:58 +0900)
committerDongsun Lee <ds73.lee@samsung.com>
Fri, 22 Mar 2024 01:42:44 +0000 (10:42 +0900)
Change-Id: Ifee871537be2642236244788b4a2d4ca76c41da3

include/webauthn-types.h
include/webauthn.h

index a590357..e528b16 100644 (file)
@@ -71,12 +71,15 @@ WEBAUTHN_API const char * wauthn_error_to_string(int error);
 
 /**
  * @brief WebAuthn authenticator transports.
- *
  * @since_tizen 9.0
+ *
+ * @remarks Refer to the following W3C specification for more information.
+ *          https://www.w3.org/TR/webauthn-3/#enum-transport
+ *
  * @remarks Multiple transport values can be combined using bit-wise operation.
  */
 typedef enum __wauthn_authenticator_transport {
-    WAUTHN_TRANSPORT_NONE                   = 0x00000000,
+    WAUTHN_TRANSPORT_NONE                   = 0x00000000, /**< No tranport specificed */
     WAUTHN_TRANSPORT_USB                    = 0x00000001, /**< "usb" */
     WAUTHN_TRANSPORT_NFC                    = 0x00000002, /**< "nfc" */
     WAUTHN_TRANSPORT_BLE                    = 0x00000004, /**< "ble" */
@@ -89,6 +92,10 @@ typedef enum __wauthn_authenticator_transport {
  * @brief WebAuthn hash algorithms.
  *        Currently one hash algorithm is used, namely "SHA-256".
  * @since_tizen 9.0
+ *
+ * @remarks Refer to the following W3C specification for more information.
+ *          https://www.w3.org/TR/webauthn-3/#collectedclientdata-hash-of-the-serialized-client-data
+ *
  */
 typedef enum __wauthn_hash_algorithm {
     WAUTHN_HASH_ALGORITHM_SHA_256           = 1, /**< "SHA-256" */
@@ -97,6 +104,10 @@ typedef enum __wauthn_hash_algorithm {
 /**
  * @brief WebAuthn COSE(CBOR Object Signing and Encryption) algorithms.
  * @since_tizen 9.0
+ *
+ * @remarks Refer to the following W3C specification for more information.
+ *          https://www.w3.org/TR/webauthn-3/#sctn-alg-identifier
+ *
  */
 typedef enum __wauthn_cose_algorithm {
     WAUTHN_COSE_ALGORITHM_ECDSA_P256_WITH_SHA256        = -7,   /**< "ES256" */
@@ -114,6 +125,10 @@ typedef enum __wauthn_cose_algorithm {
 /**
  * @brief WebAuthn attestation preference.
  * @since_tizen 9.0
+ *
+ * @remarks Refer to the following W3C specification for more information.
+ *          https://www.w3.org/TR/webauthn-3/#enumdef-attestationconveyancepreference
+ *
  */
 typedef enum __wauthn_attestation_pref {
     AP_NONE                     = 0, /**< none */
@@ -125,6 +140,10 @@ typedef enum __wauthn_attestation_pref {
 /**
  * @brief WebAuthn public key credential hint value.
  * @since_tizen 9.0
+ *
+ * @remarks Refer to the following W3C specification for more information.
+ *          https://www.w3.org/TR/webauthn-3/#enumdef-publickeycredentialhints
+ *
  */
 typedef enum __wauthn_pubkey_cred_hint {
     PCH_NONE                    = 0, /**< none */
@@ -136,6 +155,10 @@ typedef enum __wauthn_pubkey_cred_hint {
 /**
  * @brief WebAuthn user verification requirement value.
  * @since_tizen 9.0
+ *
+ * @remarks Refer to the following W3C specification for more information.
+ *          https://www.w3.org/TR/webauthn-3/#enumdef-userverificationrequirement
+ *
  */
 typedef enum __wauthn_user_verification_requirement {
     UVR_NONE                    = 0, /**< none */
@@ -147,6 +170,10 @@ typedef enum __wauthn_user_verification_requirement {
 /**
  * @brief WebAuthn resident key requirement value
  * @since_tizen 9.0
+ *
+ * @remarks Refer to the following W3C specification for more information.
+ *          https://www.w3.org/TR/webauthn-3/#enum-residentKeyRequirement
+ *
  */
 typedef enum __wauthn_resident_key_requirement {
     RKR_NONE                    = 0, /**< none */
@@ -158,6 +185,9 @@ typedef enum __wauthn_resident_key_requirement {
 /**
  * @brief WebAuthn authentication attachment value
  * @since_tizen 9.0
+ *
+ * @remarks Refer to the following W3C specification for more information.
+ *          https://www.w3.org/TR/webauthn-3/#enumdef-authenticatorattachment
  */
 typedef enum __wauthn_authenticator_attachment {
     AA_NONE                     = 0, /**< none */
@@ -169,6 +199,9 @@ typedef enum __wauthn_authenticator_attachment {
  * @brief WebAuthn credential type.
  *        Currently one credential type is defined, namely "public-key".
  * @since_tizen 9.0
+ *
+ * @remarks Refer to the following W3C specification for more information.
+ *          https://www.w3.org/TR/webauthn-3/#enumdef-publickeycredentialtype
  */
 typedef enum __wauthn_pubkey_cred_type {
     PCT_PUBLIC_KEY              = 1, /**< public-key */
@@ -179,72 +212,115 @@ typedef enum __wauthn_pubkey_cred_type {
  * @since_tizen 9.0
  */
 typedef struct __wauthn_const_buffer {
-    const unsigned char *data; /**< Byte array containing binary data */
-    size_t size; /**< The size of the binary data */
+    const unsigned char *data; /**<
+        Byte array containing binary data */
+    size_t size; /**<
+        The size of the binary data */
 } wauthn_const_buffer_s;
 
 /**
  * @brief The structure for response of wauthn_make_credential.
  * @since_tizen 9.0
+ *
+ * @remarks Refer to the following W3C specification for more information.
+ *          https://www.w3.org/TR/webauthn-3/#authenticatorattestationresponse
+ *
  * @see wauthn_make_credential()
  * @see #wauthn_pubkey_credential_attestaion_s
  * @see #wauthn_authenticator_transport_e
  * @see #wauthn_cose_algorithm_e
  */
 typedef struct __wauthn_authenticator_attestation_response {
-    wauthn_const_buffer_s *client_data_json;
-    wauthn_const_buffer_s *attestation_object; /**< The CBOR encoded Attestation Object to be returned to the RP */
-    unsigned int transports; /**< To represent multiple transports,
-                                #wauthn_authenticator_transport_e can be ORed multiple times */
-    wauthn_const_buffer_s *authenticator_data;
-    wauthn_const_buffer_s *subject_pubkey_info;
-    wauthn_cose_algorithm_e pubkey_alg;
+    wauthn_const_buffer_s *client_data_json; /**<
+        JSON-compatible serialization of client data*/
+    wauthn_const_buffer_s *attestation_object; /**<
+        The CBOR encoded Attestation Object to be returned to the RP */
+    unsigned int transports; /**<
+        To represent multiple transports, #wauthn_authenticator_transport_e
+        can be ORed multiple times */
+    wauthn_const_buffer_s *authenticator_data; /**<
+        the authenticator data contained within attestation_object.
+        For more information, refer to https://www.w3.org/TR/webauthn-3/#sctn-authenticator-data */
+    wauthn_const_buffer_s *subject_pubkey_info; /**<
+        DER SubjectPublicKeyInfo of the new credential, or null if this is not available.
+        For more information, refer to https://datatracker.ietf.org/doc/html/rfc5280#section-4.1.2.7 */
+    wauthn_cose_algorithm_e pubkey_alg; /**<
+        The COSEAlgorithmIdentifier of the new credential.*/
 } wauthn_authenticator_attestation_response_s;
 
 /**
  * @brief The structure for response of wauthn_get_assersion.
  * @since_tizen 9.0
+ *
+ * @remarks Refer to the following W3C specification for more information.
+ *          https://www.w3.org/TR/webauthn-3/#authenticatorassertionresponse
+ *
  * @see wauthn_get_assersion()
  * @see #wauthn_pubkey_credential_assertion_s
  */
 typedef struct __wauthn_authenticator_assertion_response {
-    wauthn_const_buffer_s *client_data_json;
-    wauthn_const_buffer_s *authenticator_data;
-    wauthn_const_buffer_s *signature;
-    wauthn_const_buffer_s *user_handle;
-    wauthn_const_buffer_s *attestation_object;
+    wauthn_const_buffer_s *client_data_json; /**<
+        JSON-compatible serialization of client data*/
+    wauthn_const_buffer_s *authenticator_data; /**<
+        the authenticator data contained within attestation_object.
+        For more information, refer to https://www.w3.org/TR/webauthn-3/#sctn-authenticator-data .*/
+    wauthn_const_buffer_s *signature; /**<
+        the raw signature returned from the authenticator.
+        For more information, refer to https://www.w3.org/TR/webauthn-3/#sctn-op-get-assertion .*/
+    wauthn_const_buffer_s *user_handle; /**<
+        the user handle returned from the authenticator,
+        or null if the authenticator did not return a user handle*/
+    wauthn_const_buffer_s *attestation_object; /**<
+        This OPTIONAL attribute contains an attestation object,
+        if the authenticator supports attestation in assertions. */
 } wauthn_authenticator_assertion_response_s;
 
 /**
  * @brief The structure for a RP entity.
  * @since_tizen 9.0
+ *
+ * @remarks Refer to the following W3C specification for more information.
+ *          https://www.w3.org/TR/webauthn-3/#dictdef-publickeycredentialrpentity
  */
 typedef struct __wauthn_rp_entity {
-    const char *name; /**< The name of RP */
-    const char *id; /**< The RPID */
+    const char *name; /**<
+        The name of RP */
+    const char *id; /**<
+        The RPID */
 } wauthn_rp_entity_s;
 
 /**
  * @brief The structure for a user entity.
  * @since_tizen 9.0
+ *
+ * @remarks Refer to the following W3C specification for more information.
+ *          https://www.w3.org/TR/webauthn-3/#dictdef-publickeycredentialuserentity
  */
 typedef struct __wauthn_user_entity {
     const char *name;
-    wauthn_const_buffer_s *id; /**< The ID of the user account. An ID is a byte sequence with a maximum size of
-                         64 bytes, and is not meant to be displayed to the user */
-    const char *display_name; /**< A human-palatable name for the user account, intended only for display */
+    wauthn_const_buffer_s *id; /**<
+        The ID of the user account. An ID is a byte sequence with a maximum size of 64 bytes,
+        and is not meant to be displayed to the user */
+    const char *display_name; /**<
+        A human-palatable name for the user account, intended only for display */
 } wauthn_user_entity_s;
 
 
 /**
  * @brief The structure for a parameter for credential generation.
  * @since_tizen 9.0
+ *
+ * @remarks Refer to the following W3C specification for more information.
+ *          https://www.w3.org/TR/webauthn-3/#dictdef-publickeycredentialparameters
+ *
  * @see #wauthn_pubkey_cred_type_e
  * @see #wauthn_cose_algorithm_e
  */
 typedef struct __wauthn_pubkey_cred_param {
-    wauthn_pubkey_cred_type_e type; /**< Well-known credential type specifying a credential to create */
-    wauthn_cose_algorithm_e alg; /**< Well-known COSE algorithm specifying the algorithm to use for the credential */
+    wauthn_pubkey_cred_type_e type; /**<
+        Well-known credential type specifying a credential to create */
+    wauthn_cose_algorithm_e alg; /**<
+        Well-known COSE algorithm specifying the algorithm to use for the credential */
 } wauthn_pubkey_cred_param_s;
 
 /**
@@ -253,21 +329,29 @@ typedef struct __wauthn_pubkey_cred_param {
  * @see #wauthn_pubkey_cred_param_s
  */
 typedef struct __wauthn_pubkey_cred_params {
-    size_t size;
-    wauthn_pubkey_cred_param_s *params;
+    size_t size;  /**<
+        the number of params */
+    wauthn_pubkey_cred_param_s *params; /**<
+        the sequenece of #wauthn_pubkey_cred_param_s */
 } wauthn_pubkey_cred_params_s;
 
 /**
  * @brief The structure for a publickey credential descriptor.
  * @since_tizen 9.0
+ *
+ * @remarks Refer to the following W3C specification for more information.
+ *          https://www.w3.org/TR/webauthn-3/#dictdef-publickeycredentialdescriptor
+ *
  * @see #wauthn_pubkey_cred_type_e
  * @see #wauthn_authenticator_transport_e
  */
 typedef struct __wauthn_pubkey_cred_descriptor {
-    wauthn_pubkey_cred_type_e type;
-    wauthn_const_buffer_s *id;
-    unsigned int transports; /**< To represent multiple transports,
-                                #wauthn_authenticator_transport_e can be ORed multiple times */
+    wauthn_pubkey_cred_type_e type; /**<
+        the type of the public key credential */
+    wauthn_const_buffer_s *id; /**<
+        the credential ID of the public key credential */
+    unsigned int transports; /**<
+        To represent multiple transports, #wauthn_authenticator_transport_e can be ORed multiple times */
 } wauthn_pubkey_cred_descriptor_s;
 
 /**
@@ -276,8 +360,10 @@ typedef struct __wauthn_pubkey_cred_descriptor {
  * @see #wauthn_pubkey_cred_descriptor_s
  */
 typedef struct __wauthn_pubkey_cred_descriptors {
-    size_t size;
-    wauthn_pubkey_cred_descriptor_s *descriptors;
+    size_t size; /**<
+        the number of descriptors */
+    wauthn_pubkey_cred_descriptor_s *descriptors; /**<
+        the sequenece of #wauthn_pubkey_cred_descriptor_s */
 } wauthn_pubkey_cred_descriptors_s;
 
 /**
@@ -296,25 +382,39 @@ typedef struct __wauthn_authentication_ext {
 /**
  * @brief The list structure for authentication extensions.
  * @since_tizen 9.0
+ *
+ * @remarks Refer to the following W3C specification for more information.
+ *          https://www.w3.org/TR/webauthn-3/#client-extension-input
+ *
  * @see #wauthn_authentication_ext_s
  */
 typedef struct __wauthn_authentication_exts {
-    size_t size;
-    wauthn_authentication_ext_s *extensions;
+    size_t size; /**<
+        the number of extensions */
+    wauthn_authentication_ext_s *extensions; /**<
+        the sequenece of #wauthn_authentication_ext_s */
 } wauthn_authentication_exts_s;
 
 /**
  * @brief The structure for an authenticator selection criteria.
  * @since_tizen 9.0
+ *
+ * @remarks Refer to the following W3C specification for more information.
+ *          https://www.w3.org/TR/webauthn-3/#dictdef-authenticatorselectioncriteria
+ *
  * @see #wauthn_authenticator_attachment_e
  * @see #wauthn_resident_key_requirement_e
  * @see #wauthn_user_verification_requirement_e
  */
 typedef struct __wauthn_authenticator_sel_cri {
-    wauthn_authenticator_attachment_e attachment;
-    wauthn_resident_key_requirement_e resident_key;
-    bool require_resident_key;
-    wauthn_user_verification_requirement_e user_verification;
+    wauthn_authenticator_attachment_e attachment; /**<
+        Authenticator attachment modality*/
+    wauthn_resident_key_requirement_e resident_key; /**<
+        Specifies the extent to which the Relying Party desires to create a client-side discoverable credentialy*/
+    bool require_resident_key; /**<
+        Relying Parties SHOULD set it to true if, and only if, residentKey is set to required.*/
+    wauthn_user_verification_requirement_e user_verification; /**<
+        Specifies the Relying Party's requirements regarding user verification. */
 } wauthn_authenticator_sel_cri_s;
 
 /**
@@ -323,13 +423,31 @@ typedef struct __wauthn_authenticator_sel_cri {
  * @see #wauthn_pubkey_cred_hint_e
  */
 typedef struct __wauthn_pubkey_cred_hints {
-    size_t size;
-    wauthn_pubkey_cred_hint_e *hints;
+    size_t size; /**<
+        the number of hints */
+    wauthn_pubkey_cred_hint_e *hints; /**<
+        the sequenece of #wauthn_pubkey_cred_hint_e */
 } wauthn_pubkey_cred_hints_s;
 
 /**
  * @brief The structure for a linked device data.
  * @since_tizen 9.0
+ *
+ * @remarks The linked device data is used for state assisited transaction.
+ *          From the successful QR initiated transcation, the linked device data
+ *          might be returned from an authenticator to a webauthn client
+ *          via #wauthn_pubkey_credential_attestaion_s or #wauthn_pubkey_credential_assertion_s.
+ *          Then the client can store the linked device data and use it in the next call
+ *          for #wauthn_pubkey_cred_creation_options_s or #wauthn_pubkey_cred_request_options_s.
+ *          Then the stated assisted transction will start instead of QR initiated transtion.
+ *
+ * @remarks For more information, find a section with the keyword, "linking map",
+ *          from the following specification.
+ *          https://fidoalliance.org/specs/fido-v2.2-rd-20230321/fido-client-to-authenticator-protocol-v2.2-rd-20230321.html
+
+ * @remarks For more information about state assisted transaction, refer to the following.
+ *          https://fidoalliance.org/specs/fido-v2.2-rd-20230321/fido-client-to-authenticator-protocol-v2.2-rd-20230321.html#hybrid-state-assisted
+ *
  */
 typedef struct __wauthn_hybrid_linked_data {
     wauthn_const_buffer_s *contact_id;           // cbor:"1"
@@ -345,15 +463,31 @@ typedef struct __wauthn_hybrid_linked_data {
 /**
  * @brief The list structure for attestation formats.
  * @since_tizen 9.0
+ *
+ * @remarks The attestation formats are a sequence of strings that expresses
+ *          the Relying Party's preference for attestation statement formats,
+ *          from most to least preferable.
+ * @remarks Each wauthn_const_buffer_s has a string of an attestation format
+ *          such as packed, android-key, fido-u2f, apple, none, and so on.
+ *
+ * @remarks Refer to the following W3C specification for more information.
+ *          https://www.w3.org/TR/webauthn-3/#attestation-statement-format-identifier
+ *
  */
 typedef struct __wauthn_attestation_formats {
-    size_t size;
-    wauthn_const_buffer_s *attestation_formats;
+    size_t size; /**<
+        the number of attestation_formats */
+    wauthn_const_buffer_s *attestation_formats; /**<
+        the sequenece of #wauthn_const_buffer_s */
 } wauthn_attestation_formats_s;
 
 /**
  * @brief The structure for a make credential option.
  * @since_tizen 9.0
+ *
+ * @remarks Refer to the following W3C specification for more information.
+ *          https://www.w3.org/TR/webauthn-3/#dictdef-publickeycredentialcreationoptions
+ *
  * @see wauthn_make_credential()
  * @see #wauthn_rp_entity_s
  * @see #wauthn_user_entity_s
@@ -368,29 +502,22 @@ typedef struct __wauthn_attestation_formats {
  */
 typedef struct __wauthn_pubkey_cred_creation_options {
     wauthn_rp_entity_s *rp; /**< This member contains a name and
-                            an identifier for the Relying Party
-                            responsible for the request */
+        an identifier for the Relying Party responsible for the request */
     wauthn_user_entity_s *user; /**< This member contains names and
-                                an identifier for the user account
-                                performing the registration */
+        an identifier for the user account performing the registration */
     wauthn_pubkey_cred_params_s *pubkey_cred_params; /**< This member lists the key types and
-                                                     signature algorithms the Relying Party
-                                                     supports, ordered from most preferred
-                                                     to least preferred */
+        signature algorithms the Relying Party supports, ordered from most preferred
+        to least preferred */
     unsigned long timeout; /**< This member specifies a time, in milliseconds,
         that the Relying Party is willing to wait for the call to complete.
         This is treated as a hint, and MAY be overridden by the client.
         The value, '0', means no timeout is set. (optional) */
     wauthn_pubkey_cred_descriptors_s *exclude_credentials; /**< The Relying Party SHOULD use
-                                                           this member to list any existing
-                                                           credentials mapped to this user
-                                                           account (as identified by user.id)
-                                                           (optional) */
+        this member to list any existing credentials mapped to this user account
+        (as identified by user.id). (optional) */
     wauthn_authenticator_sel_cri_s *authenticator_selection; /**< The Relying Party MAY use
-                                                             this member to specify capabilities
-                                                             and settings that the authenticator
-                                                             MUST or SHOULD satisfy to participate
-                                                             in this operation (optional)*/
+        this member to specify capabilities and settings that the authenticator
+        MUST or SHOULD satisfy to participate in this operation. (optional)*/
     wauthn_pubkey_cred_hints_s *hints; /**<
         This member contains zero or more elements from #wauthn_pubkey_cred_hint_e to
         guide the user agent in interacting with the user. (optional)*/
@@ -409,6 +536,10 @@ typedef struct __wauthn_pubkey_cred_creation_options {
 /**
  * @brief The structure for a get assertion option.
  * @since_tizen 9.0
+ *
+ * @remarks Refer to the following W3C specification for more information.
+ *          https://www.w3.org/TR/webauthn-3/#dictionary-assertion-options
+ *
  * @see wauthn_get_assertion()
  * @see #wauthn_pubkey_cred_descriptors_s
  * @see #wauthn_user_verification_requirement_e
@@ -421,11 +552,11 @@ typedef struct __wauthn_pubkey_cred_creation_options {
 typedef struct __wauthn_pubkey_cred_request_options {
     unsigned long timeout; /**< This member specifies a time, in milliseconds,
         that the Relying Party is willing to wait for the call to complete.
-        The value, '0', means no timeout is set. (optional)*/
+        This is treated as a hint, and MAY be overridden by the client.
+        The value, '0', means no timeout is set. (optional) */
     const char *rpId; /**< This member specifies the RP ID claimed by the Relying Party (optional)*/
     wauthn_pubkey_cred_descriptors_s *allow_credentials; /**< This member is used by the client
-                                                         to find authenticators eligible for this
-                                                         authentication ceremony (optional)*/
+        to find authenticators eligible for this authentication ceremony. (optional)*/
     wauthn_user_verification_requirement_e user_verification; /**<
         This member specifies the Relying Party's requirements regarding
         user verification for the wauthn_get_assertion() operation.
@@ -449,6 +580,11 @@ typedef struct __wauthn_pubkey_cred_request_options {
 /**
  * @brief The structure for a publickey_credential response for wauthn_make_credential().
  * @since_tizen 9.0
+ *
+ * @remarks Refer to the following W3C specification for more information.
+ *          https://www.w3.org/TR/webauthn-3/#iface-pkcredential
+ *          https://www.w3.org/TR/webauthn-3/#sctn-credentialcreationoptions-extension
+ *
  * @see wauthn_make_credential()
  * @see #wauthn_pubkey_cred_type_e
  * @see #wauthn_authenticator_attestation_response_s
@@ -457,18 +593,31 @@ typedef struct __wauthn_pubkey_cred_request_options {
  * @see #wauthn_hybrid_linked_data_s
  */
 typedef struct __wauthn_pubkey_credential_attestaion {
-    wauthn_const_buffer_s *id;
-    wauthn_pubkey_cred_type_e type;
-    wauthn_const_buffer_s *rawId;
-    wauthn_authenticator_attestation_response_s *response;
-    wauthn_authenticator_attachment_e authenticator_attachment;
-    wauthn_authentication_exts_s *extensions;
-    wauthn_hybrid_linked_data_s *linked_device;
+    wauthn_const_buffer_s *id; /**<
+        The based64url encoding of credential’s identifier.*/
+    wauthn_pubkey_cred_type_e type; /**<
+        The credential’s type.*/
+    wauthn_const_buffer_s *rawId; /**<
+        The raw value of credential’s identifier.*/
+    wauthn_authenticator_attestation_response_s *response; /**<
+        Authenticator's response. */
+    wauthn_authenticator_attachment_e authenticator_attachment; /**<
+        Authenticator attachment modality.*/
+    wauthn_authentication_exts_s *extensions; /**<
+        the results of processing client extensions requested by the Relying Party
+        upon the Relying Party's invocation of #wauthn_make_credential(). (optional)*/
+    wauthn_hybrid_linked_data_s *linked_device; /**<
+        Linked Device Connection Info (optional) */
 } wauthn_pubkey_credential_attestaion_s;
 
 /**
  * @brief The structure for a publickey_credential response for wauthn_get_assertion().
  * @since_tizen 9.0
+ *
+ * @remarks Refer to the following W3C specification for more information.
+ *          https://www.w3.org/TR/webauthn-3/#iface-pkcredential
+ *          https://www.w3.org/TR/webauthn-3/#sctn-credentialrequestoptions-extension
+ *
  * @see wauthn_get_assertion()
  * @see #wauthn_pubkey_cred_type_e
  * @see #wauthn_authenticator_assertion_response_s
@@ -477,23 +626,37 @@ typedef struct __wauthn_pubkey_credential_attestaion {
  * @see #wauthn_hybrid_linked_data_s
  */
 typedef struct __wauthn_pubkey_credential_assertion {
-    wauthn_const_buffer_s *id;
-    wauthn_pubkey_cred_type_e type;
-    wauthn_const_buffer_s *rawId;
-    wauthn_authenticator_assertion_response_s *response;
-    wauthn_authenticator_attachment_e authenticator_attachment;
-    wauthn_authentication_exts_s *extensions;
-    wauthn_hybrid_linked_data_s *linked_device;
+    wauthn_const_buffer_s *id; /**<
+        The based64url encoding of credential’s identifier.*/
+    wauthn_pubkey_cred_type_e type; /**<
+        The credential’s type.*/
+    wauthn_const_buffer_s *rawId; /**<
+        The raw value of credential’s identifier.*/
+    wauthn_authenticator_assertion_response_s *response;; /**<
+        Authenticator's response. */
+    wauthn_authenticator_attachment_e authenticator_attachment; /**<
+        Authenticator attachment modality.*/
+    wauthn_authentication_exts_s *extensions; /**<
+        The results of processing client extensions requested by the Relying Party
+        upon the Relying Party's invocation of #wauthn_get_assertion(). (optional)*/
+    wauthn_hybrid_linked_data_s *linked_device; /**<
+        Linked Device Connection Info (optional) */
 } wauthn_pubkey_credential_assertion_s;
 
 /**
  * @brief The structure for a client data json.
  * @since_tizen 9.0
+ *
+ * @remarks Refer to the following W3C specification about how to encode the client_data_json.
+ *          https://www.w3.org/TR/webauthn-3/#collectedclientdata-json-compatible-serialization-of-client-data
+ *
  * @see #wauthn_hash_algorithm_e
  */
 typedef struct __wauthn_client_data {
-    wauthn_const_buffer_s *client_data_json;// UTF-8 encoded JSON serialization of the client data
-    wauthn_hash_algorithm_e hash_alg; // Hash algorithm used to hash the client_data_json field
+    wauthn_const_buffer_s *client_data_json; /**<
+        UTF-8 encoded JSON serialization of the client data */
+    wauthn_hash_algorithm_e hash_alg; /**<
+        Hash algorithm used to hash the client_data_json field */
 } wauthn_client_data_s;
 
 /**
@@ -582,8 +745,10 @@ typedef void (*wauthn_cb_ga_on_response)(const wauthn_pubkey_credential_assertio
  * @see wauthn_cb_mc_on_response()
  */
 typedef struct __wauthn_mc_callbacks {
-    wauthn_cb_display_qrcode qrcode_callback; /**< call back function for displaying QR code*/
-    wauthn_cb_mc_on_response response_callback; /**< call back function for getting the final response*/
+    wauthn_cb_display_qrcode qrcode_callback; /**<
+        call back function for displaying QR code*/
+    wauthn_cb_mc_on_response response_callback; /**<
+        call back function for getting the final response*/
     void *user_data; /**< user data to be passed to qrcode_callback and response_callback*/
 } wauthn_mc_callbacks_s;
 
@@ -595,9 +760,12 @@ typedef struct __wauthn_mc_callbacks {
  * @see wauthn_cb_ga_on_response()
  */
 typedef struct __wauthn_ga_callbacks {
-    wauthn_cb_display_qrcode qrcode_callback; /**< call back function for displaying QR code*/
-    wauthn_cb_ga_on_response response_callback; /**< call back function for getting the final response*/
-    void *user_data; /**< user data to be passed to qrcode_callback and response_callback*/
+    wauthn_cb_display_qrcode qrcode_callback; /**<
+        call back function for displaying QR code*/
+    wauthn_cb_ga_on_response response_callback; /**<
+        call back function for getting the final response*/
+    void *user_data; /**<
+        user data to be passed to qrcode_callback and response_callback*/
 } wauthn_ga_callbacks_s;
 
 
index e94b8c5..fc0d893 100644 (file)
@@ -81,9 +81,10 @@ WEBAUTHN_API int wauthn_supported_authenticators(unsigned int *supported);
  *
  * @since_tizen 9.0
  *
- * @remarks [TBD] something important to remember
+ * @remarks Refer to the following W3C specification for more information.
+ *           https://www.w3.org/TR/webauthn-3/#sctn-createCredential
  *
- * @param[in]  client_data UTF-8 encoded JSON serialization of the client data
+ * @param[in]  client_data UTF-8 encoded JSON serialization of the client data.
  * @param[in]  options This argument is a #wauthn_pubkey_cred_creation_options_s object specifying the
  *                     desired attributes of the to-be-created public key credential
  * @param[in]  callbacks The callback functions to be invoked
@@ -111,7 +112,8 @@ WEBAUTHN_API int wauthn_make_credential( const wauthn_client_data_s *client_data
  *
  * @since_tizen 9.0
  *
- * @remarks [TBD] Something important to remember
+ * @remarks Refer to the following W3C specification for more information.
+ *           https://www.w3.org/TR/webauthn-3/#sctn-getAssertion
  *
  * @param[in]  client_data UTF-8 encoded JSON serialization of the client data
  * @param[in]  options This argument is a #wauthn_pubkey_cred_request_options_s object specifying the