[api][services][core] Code cleanup

.gitignore

@@ -16,3 +16,4 @@ __docbook
 .settings/
 *.xml
 *.pu
+_codeql_detected_source_root

api/stse_data_storage.h

@@ -68,7 +68,7 @@ stse_ReturnCode_t stse_data_storage_get_partitioning_table(
  * \param[in]  	length 			Read length in byte
  * \param[in] 	chunk_size 		Read chunk size in byte
  * \param[in]  	protection 		\ref stse_cmd_protection_t command response protection indicator
- * \result 		\ref STSE_OK on success ; \ref stse_ReturnCode_t error code otherwise
+ * \return 		\ref STSE_OK on success ; \ref stse_ReturnCode_t error code otherwise
  * \note 		- A target STSE handler must be initialized using the \ref stse_init routine prior to execute this API function
  * \note 		- If command response protection is required an active session between Host/Companion and STSE must be open
  * \details 	\include{doc} stse_data_storage_read_zone.dox
@@ -91,7 +91,7 @@ stse_ReturnCode_t stse_data_storage_read_data_zone(
  * \param[in]  	length 			Update length in byte
  * \param[in] 	atomicity 		\ref stse_zone_update_atomicity_t atomicity of the update access
  * \param[in]  	protection 		\ref stse_cmd_protection_t command response protection indicator
- * \result 		\ref STSE_OK on success ; \ref stse_ReturnCode_t error code otherwise
+ * \return 		\ref STSE_OK on success ; \ref stse_ReturnCode_t error code otherwise
  * \note 		- A target STSE handler must be initialized using the \ref stse_init routine prior to execute this API function
  * \note 		- If command response protection is required an active session between Host/Companion and STSE must be open
  * \details 	\include{doc} stse_data_storage_update_zone.dox
@@ -115,7 +115,7 @@ stse_ReturnCode_t stse_data_storage_update_data_zone(
  * \param[in]  	length 			Associated data update length in byte (optional : set to 0 if not used)
  * \param[out] 	 new_counter_value 		Pointer to applicative counter value buffer
  * \param[in]  	protection 		\ref stse_cmd_protection_t command response protection indicator
- * \result 		\ref STSE_OK on success ; \ref stse_ReturnCode_t error code otherwise
+ * \return 		\ref STSE_OK on success ; \ref stse_ReturnCode_t error code otherwise
  * \note 		- A target STSE handler must be initialized using the \ref stse_init routine prior to execute this API function
  * \note 		- If command response protection is required an active session between Host/Companion and STSE must be open
  * \details 	\include{doc} stse_data_storage_decrement_counter.dox
@@ -140,7 +140,7 @@ stse_ReturnCode_t stse_data_storage_decrement_counter_zone(
  * \param[in] 	chunk_size 		Associated data read chunk size in byte  (optional : set to 0 if not used)
  * \param[out] 	counter_value 	Pointer to applicative counter value buffer
  * \param[in]  	protection 		\ref stse_cmd_protection_t command response protection indicator
- * \result 		\ref STSE_OK on success ; \ref stse_ReturnCode_t error code otherwise
+ * \return 		\ref STSE_OK on success ; \ref stse_ReturnCode_t error code otherwise
  * \note 		- A target STSE handler must be initialized using the \ref stse_init routine prior to execute this API function
  * \note 		- If command response protection is required an active session between Host/Companion and STSE must be open
  * \details 	\include{doc} stse_data_storage_read_counter.dox
@@ -162,7 +162,7 @@ stse_ReturnCode_t stse_data_storage_read_counter_zone(
  * \param[in]	ac				\ref stse_zone_ac_t new access condition
  * \param[in]	ac_change_right	\ref stse_ac_change_right_t new access change right
  * \param[in]  	protection 		\ref stse_cmd_protection_t command response protection indicator
- * \result 		\ref STSE_OK on success ; \ref stse_ReturnCode_t error code otherwise
+ * \return 		\ref STSE_OK on success ; \ref stse_ReturnCode_t error code otherwise
  * \note 		- A target STSE handler must be initialized using the \ref stse_init routine prior to execute this API function
  * \note 		- If command response protection is required an active session between Host/Companion and STSE must be open
  * \details 	\include{doc} stse_data_storage_change_read_access_condition.dox
@@ -185,7 +185,7 @@ stse_ReturnCode_t stse_data_storage_change_read_access_condition(
  * \param[in]  	length 			Update length in byte
  * \param[in] 	atomicity 		\ref stse_zone_update_atomicity_t atomicity of the update access
  * \param[in]  	protection 		\ref stse_cmd_protection_t command response protection indicator
- * \result 		\ref STSE_OK on success ; \ref stse_ReturnCode_t error code otherwise
+ * \return 		\ref STSE_OK on success ; \ref stse_ReturnCode_t error code otherwise
  * \note 		- A target STSE handler must be initialized using the \ref stse_init routine prior to execute this API function
  * \note 		- If command response protection is required an active session between Host/Companion and STSE must be open
  * \details 	\include{doc} stse_data_storage_change_update_access_condition.dox
@@ -212,7 +212,7 @@ stse_ReturnCode_t stse_data_storage_change_update_access_condition(stse_Handler_
  * \param[in]  	length 			Associated data update length in byte (optional : set to 0 if not used)
  * \param[out] 	new_counter_value 		Pointer to applicative counter value buffer
  * \param[in]  	protection 		\ref stse_cmd_protection_t command response protection indicator
- * \result 		\ref STSE_OK on success ; \ref stse_ReturnCode_t error code otherwise
+ * \return 		\ref STSE_OK on success ; \ref stse_ReturnCode_t error code otherwise
  * \note 		- A target STSE handler must be initialized using the \ref stse_init routine prior to execute this API function
  * \note 		- If command response protection is required an active session between Host/Companion and STSE must be open
  * \details 	\include{doc} stse_data_storage_change_decrement_access_condition.dox

core/stse_generic_typedef.h

@@ -568,6 +568,14 @@ extern const stse_ecc_info_t stse_ecc_info_table[];
     defined(STSE_CONF_ECC_BRAINPOOL_P_256) || defined(STSE_CONF_ECC_BRAINPOOL_P_384) || defined(STSE_CONF_ECC_BRAINPOOL_P_512) || \
     defined(STSE_CONF_ECC_CURVE_25519) || defined(STSE_CONF_ECC_EDWARD_25519)
 
+/**
+ * \brief 		Get ECC key type from curve identifier
+ * \details 	This function resolves the ECC key type from a given curve identifier value
+ * \param[in]	curve_id_length		Length of the curve identifier
+ * \param[in]	pCurve_id_value		Pointer to the curve identifier value
+ * \param[out]	pKey_type			Pointer to store the resolved ECC key type
+ * \return 		\ref STSE_OK on success ; \ref stse_ReturnCode_t error code otherwise
+ */
 stse_ReturnCode_t stse_get_ecc_key_type_from_curve_id(
     PLAT_UI8 curve_id_length,
     const PLAT_UI8 *pCurve_id_value,

core/stse_platform.h

@@ -203,6 +203,17 @@ stse_ReturnCode_t stse_platform_ecc_ecdh(stse_ecc_key_type_t key_type,
     defined(STSE_CONF_USE_SYMMETRIC_KEY_PROVISIONING_WRAPPED) ||          \
     defined(STSE_CONF_USE_SYMMETRIC_KEY_PROVISIONING_WRAPPED_AUTHENTICATED)
 
+/**
+ * \brief 		Encrypt data using NIST AES Key Wrap algorithm
+ * \details 	This platform function implements the NIST SP 800-38F AES Key Wrap encryption
+ * \param[in]	pPayload			Pointer to the payload data to encrypt
+ * \param[in]	payload_length		Length of the payload in bytes
+ * \param[in]	pKey				Pointer to the encryption key
+ * \param[in]	key_length			Length of the key in bytes
+ * \param[out]	pOutput				Pointer to the output buffer for encrypted data
+ * \param[out]	pOutput_length		Pointer to store the output length
+ * \return 		\ref STSE_OK on success ; \ref stse_ReturnCode_t error code otherwise
+ */
 stse_ReturnCode_t stse_platform_nist_kw_encrypt(PLAT_UI8 *pPayload, PLAT_UI32 payload_length,
                                                 PLAT_UI8 *pKey, PLAT_UI8 key_length,
                                                 PLAT_UI8 *pOutput, PLAT_UI32 *pOutput_length);

services/stsafea/stsafea_asymmetric_key_slots.h

@@ -81,13 +81,33 @@ stse_ReturnCode_t stsafea_query_private_key_slots_count(
     stse_Handler_t *pSTSE,
     PLAT_UI8 *pPrivate_key_slot_count);
 
+/**
+ * \brief 		Query private key table information
+ * \details 	This service formats and sends the query private key table command
+ * \param[in] 	pSTSE 					Pointer to STSE Handler
+ * \param[in] 	private_key_slot_count	Number of private key slots
+ * \param[out] 	pChange_right			Pointer to change right value
+ * \param[out] 	pGlobal_usage_limit		Pointer to global usage limit value
+ * \param[out] 	private_key_table_info	Pointer to private key table information structure
+ * \return 		\ref STSE_OK on success ; \ref stse_ReturnCode_t error code otherwise
+ */
 stse_ReturnCode_t stsafea_query_private_key_table(
     stse_Handler_t *pSTSE,
     PLAT_UI8 private_key_slot_count,
     PLAT_UI8 *pChange_right,
     PLAT_UI16 *pGlobal_usage_limit,
     stsafea_private_key_slot_information_t *private_key_table_info);
 
+/**
+ * \brief 		Generate ECC key pair in specified slot
+ * \details 	This service formats and sends the generate ECC key pair command
+ * \param[in] 	pSTSE 			Pointer to STSE Handler
+ * \param[in] 	slot_number		Slot number where to generate the key pair
+ * \param[in] 	key_type		ECC key type to generate
+ * \param[in] 	usage_limit		Usage limit for the generated key
+ * \param[out] 	pPublic_key		Pointer to buffer for the public key
+ * \return 		\ref STSE_OK on success ; \ref stse_ReturnCode_t error code otherwise
+ */
 stse_ReturnCode_t stsafea_generate_ecc_key_pair(
     stse_Handler_t *pSTSE,
     PLAT_UI8 slot_number,

services/stsafea/stsafea_commands.h

@@ -134,57 +134,150 @@ extern const PLAT_UI16 stsafea_maximum_command_length[4];
 
 stse_ReturnCode_t stsafea_get_command_count(stse_Handler_t *pSTSE, PLAT_UI8 *pCommand_count);
 
+/**
+ * \brief 		Get command access control table
+ * \details 	This service retrieves the command access control table from the device
+ * \param[in] 	pSTSE 					Pointer to STSE Handler
+ * \param[in] 	total_command_count		Total number of commands
+ * \param[out] 	pChange_rights			Pointer to change rights structure
+ * \param[out] 	pRecord_table			Pointer to record table array
+ * \return 		\ref STSE_OK on success ; \ref stse_ReturnCode_t error code otherwise
+ */
 stse_ReturnCode_t stsafea_get_command_AC_table(stse_Handler_t *pSTSE,
                                                PLAT_UI8 total_command_count,
                                                stse_cmd_authorization_CR_t *pChange_rights,
                                                stse_cmd_authorization_record_t *pRecord_table);
 
 stse_ReturnCode_t stsafea_perso_info_update(stse_Handler_t *pSTSE);
 
+/**
+ * \brief 		Get command access conditions from personalization info
+ * \details 	This function retrieves the access conditions for a specific command
+ * \param[in] 	pPerso			Pointer to personalization info structure
+ * \param[in] 	command_code	Command code to query
+ * \param[out] 	pProtection		Pointer to store access conditions
+ */
 void stsafea_perso_info_get_cmd_AC(stse_perso_info_t *pPerso,
                                    PLAT_UI8 command_code,
                                    stse_cmd_access_conditions_t *pProtection);
 
+/**
+ * \brief 		Get extended command access conditions from personalization info
+ * \details 	This function retrieves the access conditions for a specific extended command
+ * \param[in] 	pPerso			Pointer to personalization info structure
+ * \param[in] 	command_code	Extended command code to query
+ * \param[out] 	pProtection		Pointer to store access conditions
+ */
 void stsafea_perso_info_get_ext_cmd_AC(stse_perso_info_t *pPerso,
                                        PLAT_UI8 command_code,
                                        stse_cmd_access_conditions_t *pProtection);
 
+/**
+ * \brief 		Get command encryption flag from personalization info
+ * \details 	This function retrieves the encryption flag for a specific command
+ * \param[in] 	pPerso			Pointer to personalization info structure
+ * \param[in] 	command_code	Command code to query
+ * \param[out] 	pEnc_flag		Pointer to store encryption flag
+ */
 void stsafea_perso_info_get_cmd_encrypt_flag(stse_perso_info_t *pPerso,
                                              PLAT_UI8 command_code,
                                              PLAT_UI8 *pEnc_flag);
 
+/**
+ * \brief 		Get response encryption flag from personalization info
+ * \details 	This function retrieves the encryption flag for a specific command response
+ * \param[in] 	pPerso			Pointer to personalization info structure
+ * \param[in] 	command_code	Command code to query
+ * \param[out] 	pEnc_flag		Pointer to store encryption flag
+ */
 void stsafea_perso_info_get_rsp_encrypt_flag(stse_perso_info_t *pPerso,
                                              PLAT_UI8 command_code,
                                              PLAT_UI8 *pEnc_flag);
 
+/**
+ * \brief 		Get extended command encryption flag from personalization info
+ * \details 	This function retrieves the encryption flag for a specific extended command
+ * \param[in] 	pPerso			Pointer to personalization info structure
+ * \param[in] 	command_code	Extended command code to query
+ * \param[out] 	pEnc_flag		Pointer to store encryption flag
+ */
 void stsafea_perso_info_get_ext_cmd_encrypt_flag(stse_perso_info_t *pPerso,
                                                  PLAT_UI8 command_code,
                                                  PLAT_UI8 *pEnc_flag);
 
+/**
+ * \brief 		Get extended response encryption flag from personalization info
+ * \details 	This function retrieves the encryption flag for a specific extended command response
+ * \param[in] 	pPerso			Pointer to personalization info structure
+ * \param[in] 	command_code	Extended command code to query
+ * \param[out] 	pEnc_flag		Pointer to store encryption flag
+ */
 void stsafea_perso_info_get_ext_rsp_encrypt_flag(stse_perso_info_t *pPerso,
                                                  PLAT_UI8 command_code,
                                                  PLAT_UI8 *pEnc_flag);
 
+/**
+ * \brief 		Set command access conditions in personalization info
+ * \details 	This function sets the access conditions for a specific command
+ * \param[in,out] 	pPerso			Pointer to personalization info structure
+ * \param[in] 		command_code	Command code to configure
+ * \param[in] 		protection		Access conditions to set
+ */
 void stsafea_perso_info_set_cmd_AC(stse_perso_info_t *pPerso,
                                    PLAT_UI8 command_code,
                                    stse_cmd_access_conditions_t protection);
 
+/**
+ * \brief 		Set extended command access conditions in personalization info
+ * \details 	This function sets the access conditions for a specific extended command
+ * \param[in,out] 	pPerso			Pointer to personalization info structure
+ * \param[in] 		command_code	Extended command code to configure
+ * \param[in] 		protection		Access conditions to set
+ */
 void stsafea_perso_info_set_ext_cmd_AC(stse_perso_info_t *pPerso,
                                        PLAT_UI8 command_code,
                                        stse_cmd_access_conditions_t protection);
 
+/**
+ * \brief 		Set command encryption flag in personalization info
+ * \details 	This function sets the encryption flag for a specific command
+ * \param[in,out] 	pPerso			Pointer to personalization info structure
+ * \param[in] 		command_code	Command code to configure
+ * \param[in] 		enc_flag		Encryption flag to set
+ */
 void stsafea_perso_info_set_cmd_encrypt_flag(stse_perso_info_t *pPerso,
                                              PLAT_UI8 command_code,
                                              PLAT_UI8 enc_flag);
 
+/**
+ * \brief 		Set response encryption flag in personalization info
+ * \details 	This function sets the encryption flag for a specific command response
+ * \param[in,out] 	pPerso			Pointer to personalization info structure
+ * \param[in] 		command_code	Command code to configure
+ * \param[in] 		enc_flag		Encryption flag to set
+ */
 void stsafea_perso_info_set_rsp_encrypt_flag(stse_perso_info_t *pPerso,
                                              PLAT_UI8 command_code,
                                              PLAT_UI8 enc_flag);
 
+/**
+ * \brief 		Set extended command encryption flag in personalization info
+ * \details 	This function sets the encryption flag for a specific extended command
+ * \param[in,out] 	pPerso			Pointer to personalization info structure
+ * \param[in] 		command_code	Extended command code to configure
+ * \param[in] 		enc_flag		Encryption flag to set
+ */
 void stsafea_perso_info_set_ext_cmd_encrypt_flag(stse_perso_info_t *pPerso,
                                                  PLAT_UI8 command_code,
                                                  PLAT_UI8 enc_flag);
 
+/**
+ * \brief 		Set extended response encryption flag in personalization info
+ * \details 	This function sets the encryption flag for a specific extended command response
+ * \param[in,out] 	pPerso			Pointer to personalization info structure
+ * \param[in] 		command_code	Extended command code to configure
+ * \param[in] 		enc_flag		Encryption flag to set
+ */
 void stsafea_perso_info_set_ext_rsp_encrypt_flag(stse_perso_info_t *pPerso,
                                                  PLAT_UI8 command_code,
                                                  PLAT_UI8 enc_flag);