feat: Update docs for decryption

Author: TejasvOnly

apps/inheritance_app/inheritance_decrypt_data.c

@@ -95,6 +95,80 @@
  * STATIC FUNCTION PROTOTYPES
  *****************************************************************************/
 
+/**
+ * @brief Checks if the given request matches the expected request type.
+ *
+ * @param query Pointer to the inheritance query.
+ * @param which_request The expected request type.
+ * @return true if the request type matches, false otherwise.
+ */
+static bool check_which_request(const inheritance_query_t *query,
+                                pb_size_t which_request);
+
+/**
+ * @brief Validates the request data for decryption.
+ *
+ * @param request Pointer to the decryption request data.
+ * @return true if the request data is valid, false otherwise.
+ */
+static bool validate_request_data(
+    const inheritance_decrypt_data_with_pin_request_t *request);
+
+/**
+ * @brief Handles the initiation of the decryption query.
+ *
+ * @param query Pointer to the inheritance query.
+ * @return true if the initiation is successful, false otherwise.
+ */
+STATIC bool inheritance_handle_initiate_query(inheritance_query_t *query);
+
+/**
+ * @brief Sends the decrypted data as a response.
+ *
+ * @param query Pointer to the inheritance query.
+ * @return true if sending the response is successful, false otherwise.
+ */
+static bool send_decrypted_data(inheritance_query_t *query);
+
+/**
+ * @brief Decrypts the packet containing encrypted data.
+ *
+ * @return true if decryption is successful, false otherwise.
+ */
+static bool decrypt_packet(void);
+
+/**
+ * @brief Deserializes the decrypted packet into individual data items.
+ *
+ * @return true if deserialization is successful, false otherwise.
+ */
+static bool deserialize_packet(void);
+
+/**
+ * @brief Decrypts the message data within the packet.
+ *
+ * @return true if message data decryption is successful, false otherwise.
+ */
+static bool decrypt_message_data(void);
+
+/**
+ * @brief Decrypts the overall data.
+ *
+ * @return true if decryption is successful, false otherwise.
+ */
+static bool decrypt_data(void);
+
+/**
+ * @brief Displays decrypted data or performs related actions based on the data.
+ *
+ * This function processes the decrypted data and either shows it on the device
+ * screen (if the tag indicates display-only) or prepares it for further
+ * response.
+ *
+ * @return true if the operation is successful, false otherwise.
+ */
+static bool show_data(void);
+
 /*****************************************************************************
  * STATIC VARIABLES
  *****************************************************************************/

common/core/core_session.h

@@ -116,6 +116,17 @@ void core_session_parse_start_message(const core_msg_t *core_msg);
  */
 session_error_type_e session_aes_encrypt(uint8_t *InOut_data, uint16_t *len);
 
+/**
+ * @brief Decrypts data using AES-CBC mode.
+ *
+ * This function decrypts the input data using the session key and IV.
+ *
+ * @param InOut_data Pointer to the input data (encrypted) and output data
+ * (decrypted).
+ * @param len Pointer to the length of the data (updated with actual decrypted
+ * length).
+ * @return The session error type indicating the decryption result.
+ */
 session_error_type_e session_aes_decrypt(uint8_t *InOut_data, uint16_t *len);
 
 #endif    // CORE_SESSION

src/card_operations/card_fetch_data.h

@@ -52,15 +52,34 @@ typedef struct {
  *****************************************************************************/
 
 /**
- * @brief Encrypts given secure_data_t with card and stores the encrypted data
- * in the same struct
+ * @brief Fetches and encrypts data for a given wallet ID.
  *
- * @return A card_error_type_e value representing the result of the operation.
+ * This function retrieves plain data associated with a wallet ID, encrypts it,
+ * and stores the encrypted data in the provided secure_data_t structures.
+ *
+ * @param wallet_id Pointer to the wallet ID.
+ * @param msgs Pointer to an array of secure_data_t structures to store the
+ * encrypted data.
+ * @param msg_count Number of secure_data_t structures in the array.
+ * @return The card error type indicating the result of the operation.
  */
-card_error_type_e card_fetch_encrypt_data(uint8_t *wallet_id,
+card_error_type_e card_fetch_encrypt_data(const uint8_t *wallet_id,
                                           secure_data_t *msgs,
                                           size_t msg_count);
 
+/**
+ * @brief Fetches and decrypts data from the card.
+ *
+ * This function retrieves encrypted data associated with a wallet ID from the
+ * card, decrypts it, and stores the plain data in the provided secure_data_t
+ * structures.
+ *
+ * @param wallet_id Pointer to the wallet ID.
+ * @param msgs Pointer to an array of secure_data_t structures to store the
+ * decrypted data.
+ * @param msg_count Number of secure_data_t structures in the array.
+ * @return The card error type indicating the result of the operation.
+ */
 card_error_type_e card_fetch_decrypt_data(const uint8_t *wallet_id,
                                           secure_data_t *msgs,
                                           size_t msg_count);

src/card_operations/card_fetch_encrypt_data.c

@@ -99,7 +99,7 @@
  * GLOBAL FUNCTIONS
  *****************************************************************************/
 
-card_error_type_e card_fetch_encrypt_data(uint8_t *wallet_id,
+card_error_type_e card_fetch_encrypt_data(const uint8_t *wallet_id,
                                           secure_data_t *msgs,
                                           size_t msg_count) {
   card_error_type_e result = CARD_OPERATION_DEFAULT_INVALID;

src/card_operations/card_fetch_wallet_list.h

@@ -57,6 +57,18 @@ card_error_type_e card_fetch_wallet_list(
     const card_fetch_wallet_list_config_t *config,
     card_fetch_wallet_list_response_t *response);
 
+/**
+ * @brief Fetches the wallet name associated with a given wallet ID.
+ *
+ * This function retrieves the list of wallets from the card and searches for
+ * the wallet with the specified wallet ID. If found, it copies the wallet name
+ * to the provided buffer.
+ *
+ * @param wallet_id Pointer to the wallet ID.
+ * @param wallet_name Pointer to the buffer where the wallet name will be
+ * copied.
+ * @return true if the wallet name is successfully fetched, false otherwise.
+ */
 bool card_fetch_wallet_name(const uint8_t *wallet_id, char *wallet_name);
 
 #endif /* CARD_FETCH_WALLET_LIST_H */