From ee46bfcbfdf809606ee24ba55c576bc55d4b4a64 Mon Sep 17 00:00:00 2001 From: Ajinkya Rajandekar Date: Tue, 20 Feb 2024 15:05:12 +0000 Subject: [PATCH] Document data structures used --- app/src/apdu.h | 20 ++++++++++++++--- app/src/apdu_sign.h | 39 +++++++++++++++++++++++++--------- app/src/globals.h | 52 +++++++++++++++++++++++++++++---------------- 3 files changed, 80 insertions(+), 31 deletions(-) diff --git a/app/src/apdu.h b/app/src/apdu.h index 467567f78..32d61c109 100644 --- a/app/src/apdu.h +++ b/app/src/apdu.h @@ -83,8 +83,22 @@ typedef void(tz_handler)(command_t *cmd); typedef tz_handler *tz_handler_t; -tz_handler handle_unimplemented; -tz_handler handle_apdu_version; -tz_handler handle_apdu_git; +tz_handler handle_unimplemented; /// handler for unknown commands +tz_handler handle_apdu_version; /// handle version enquiry apdu +tz_handler handle_apdu_git; /// handle git commit enquiry apdu +/** + * @brief Function to handle apdu request for public key. The public key is + * derived only once and stored in the RAM, in order to avoid repeated + * derivation calculations. This function can be called with or without + * prompt. + * + */ tz_handler handle_apdu_get_public_key; +/** + * @brief Parse the received command and prompt user for appropriate action. + * Triggers blindsigning and/or expert mode workflows based on transaction + * involved. Stream based parser helps decode arbitararily large transaction, + * screen by screen. + * + */ tz_handler handle_apdu_sign; diff --git a/app/src/apdu_sign.h b/app/src/apdu_sign.h index 0880a6bed..1b6dbd84c 100644 --- a/app/src/apdu_sign.h +++ b/app/src/apdu_sign.h @@ -29,38 +29,57 @@ #include "keys.h" #include "parser/parser_state.h" +/** + * @brief Save hash of the transaction to be signed. + * + */ typedef struct { - cx_blake2b_t state; - uint8_t final_hash[SIGN_HASH_SIZE]; + cx_blake2b_t state; /// Ledger-sdk blake2b state containing hash header + /// and blake2b state info. + uint8_t final_hash[SIGN_HASH_SIZE]; /// Final hash of the transaction. } apdu_hash_state_t; +/** + * @brief Represents state of sign transaction. + * + */ typedef enum { - SIGN_ST_IDLE, - SIGN_ST_WAIT_DATA, - SIGN_ST_WAIT_USER_INPUT + SIGN_ST_IDLE, /// IDLE + SIGN_ST_WAIT_DATA, /// Waiting for more data from apdu interface + SIGN_ST_WAIT_USER_INPUT /// Waiting for user action } sign_step_t; +/** + * @brief Steps in a blind signing of a transaction. + * + */ typedef enum { BLINDSIGN_ST_OPERATION, BLINDSIGN_ST_HASH, BLINDSIGN_ST_ACCEPT_REJECT, } blindsign_step_t; +/** + * @brief Struct to track state/info about current sign operation. + * + */ typedef struct { - uint8_t packet_index; + uint8_t packet_index; /// Index of the packet currently being processed. - sign_step_t step; - bool return_hash; - bool received_last_msg; - uint8_t tag; + sign_step_t step; /// Current step of the sign operation. + bool return_hash; /// Whether to return the hash of the transaction. + bool received_last_msg; /// Whether the last message has been received. + uint8_t tag; /// Type of tezos operation to sign. union { + /// @brief clear signing state info. struct { size_t total_length; tz_parser_state parser_state; uint8_t last_field_index; bool received_msg; } clear; + /// @brief blindsigning state info. struct { blindsign_step_t step; } blind; diff --git a/app/src/globals.h b/app/src/globals.h index 2ca386f82..7d4b0846f 100644 --- a/app/src/globals.h +++ b/app/src/globals.h @@ -58,7 +58,10 @@ void toggle_blindsigning(void); #define MAX_APDU_SIZE 235 #define MAX_SIGNATURE_SIZE 100 - +/** + * @brief Home screen pages in order + * + */ typedef enum { #ifdef HAVE_BAGL SCREEN_HOME = 0, @@ -71,24 +74,33 @@ typedef enum { SCREEN_QUIT, } screen_t; +/** + * @brief State of the app + * + */ typedef enum { - ST_IDLE, - ST_CLEAR_SIGN, - ST_BLIND_SIGN, - ST_PROMPT, - ST_SWAP_SIGN, - ST_ERROR + ST_IDLE, /// Idle state + ST_CLEAR_SIGN, /// Clearsigning an operation + ST_BLIND_SIGN, /// blindisigning an operation + ST_PROMPT, /// Waiting for user prompt + ST_SWAP_SIGN, /// Performing swap operations + ST_ERROR /// In error state. } main_step_t; +/** + * @brief Global structure holding state of operations and buffer of the data + * to be processed. + * + */ typedef struct { /* State */ - main_step_t step; - tz_ui_stream_t stream; - bip32_path_with_curve_t path_with_curve; + main_step_t step; /// Current operational state of app. + tz_ui_stream_t stream; /// UX and display related information + bip32_path_with_curve_t path_with_curve; /// Derivation path union { struct { - apdu_hash_state_t hash; - apdu_sign_state_t sign; + apdu_hash_state_t hash; /// Transaction hash + apdu_sign_state_t sign; /// state of sign operation. } apdu; /** Warning: Use this pubkey only when apdu-hash/sign * is not being used. @@ -97,19 +109,20 @@ typedef struct { * */ cx_ecfp_public_key_t pubkey; } keys; - char line_buf[TZ_UI_STREAM_CONTENTS_SIZE + 1]; + char line_buf[TZ_UI_STREAM_CONTENTS_SIZE + + 1]; /// Buffer to store incoming data. #ifdef HAVE_BAGL struct { bagl_element_t bagls[5 + TZ_SCREEN_LINES_11PX]; - } ux; + } ux; /// Config for history screens for nano devices. #endif } globals_t; /* Settings */ typedef struct { - bool blindsigning; - bool expert_mode; -} settings_t; + bool blindsigning; /// enable blindsigning + bool expert_mode; /// enable expert mode +} settings_t; /// Special settings available in the app. extern globals_t global; @@ -117,5 +130,8 @@ extern const settings_t N_settings_real; #define N_settings (*(volatile settings_t *)PIC(&N_settings_real)) extern unsigned int app_stack_canary; // From SDK - +/** + * @brief IO buffer. + * + */ extern unsigned char G_io_seproxyhal_spi_buffer[IO_SEPROXYHAL_BUFFER_SIZE_B];