1 // Copyright 2020 Espressif Systems (Shanghai) PTE LTD 2 // 3 // Licensed under the Apache License, Version 2.0 (the "License"); 4 // you may not use this file except in compliance with the License. 5 // You may obtain a copy of the License at 6 // 7 // http://www.apache.org/licenses/LICENSE-2.0 8 // 9 // Unless required by applicable law or agreed to in writing, software 10 // distributed under the License is distributed on an "AS IS" BASIS, 11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 // See the License for the specific language governing permissions and 13 // limitations under the License. 14 15 /******************************************************************************* 16 * NOTICE 17 * The hal is not public api, don't use it in application code. 18 * See readme.md in soc/include/hal/readme.md 19 ******************************************************************************/ 20 21 #pragma once 22 23 #if CONFIG_IDF_TARGET_ESP32 24 #error "ESP32 doesn't have a DS peripheral" 25 #endif 26 27 #include <stdint.h> 28 #include <stddef.h> 29 #include <stdbool.h> 30 31 #ifdef __cplusplus 32 extern "C" { 33 #endif 34 35 /** 36 * The result when checking whether the key to decrypt the RSA parameters is ready. 37 */ 38 typedef enum { 39 DS_KEY_INPUT_OK = 0, /**< The decryption key is ready. */ 40 DS_NO_KEY_INPUT, /**< Dependent peripheral providing key hasn't been activated. */ 41 DS_OTHER_WRONG, /**< Dependent peripheral running but problem receiving the key. */ 42 } ds_key_check_t; 43 44 typedef enum { 45 DS_SIGNATURE_OK = 0, /**< Signature is valid and can be read. */ 46 DS_SIGNATURE_PADDING_FAIL = 1, /**< Padding invalid, signature can be read if user wants it. */ 47 DS_SIGNATURE_MD_FAIL = 2, /**< Message digest check failed, signature invalid. */ 48 DS_SIGNATURE_PADDING_AND_MD_FAIL = 3, /**< Both padding and MD check failed. */ 49 } ds_signature_check_t; 50 51 /** 52 * @brief Start the whole signing process after the input key is ready. 53 * 54 * Call this before using any of the functions below. The input key is ready must be ready at this point. 55 */ 56 void ds_hal_start(void); 57 58 /** 59 * @brief Finish the whole signing process. Call this after the signature is read or in case of an error. 60 */ 61 void ds_hal_finish(void); 62 63 /** 64 * @brief Check whether the key input (HMAC on ESP32-C3) is correct. 65 */ 66 ds_key_check_t ds_hal_check_decryption_key(void); 67 68 /** 69 * @brief Write the initialization vector. 70 */ 71 void ds_hal_configure_iv(const uint32_t *iv); 72 73 /** 74 * @brief Write the message which should be signed. 75 * 76 * @param msg Pointer to the message. 77 * @param size Length of signature result in bytes. It is the RSA signature length in bytes. 78 */ 79 void ds_hal_write_message(const uint8_t *msg, size_t size); 80 81 /** 82 * @brief Write the encrypted private key parameters. 83 */ 84 void ds_hal_write_private_key_params(const uint8_t *block); 85 86 /** 87 * @brief Begin signing procedure. 88 */ 89 void ds_hal_start_sign(void); 90 91 /** 92 * @brief Check whether the hardware is busy with an operation. 93 * 94 * @return True if the hardware has finished the signing procedure, otherwise false. 95 */ 96 bool ds_hal_busy(void); 97 98 /** 99 * @brief Check and read the signature from the hardware. 100 * 101 * @return 102 * - DS_SIGNATURE_OK if no issue is detected with the signature. 103 * - DS_SIGNATURE_PADDING_FAIL if the padding of the private key parameters is wrong. 104 * - DS_SIGNATURE_MD_FAIL if the message digest check failed. This means that the message digest calculated using 105 * the private key parameters fails, i.e., the integrity of the private key parameters is not protected. 106 * - DS_SIGNATURE_PADDING_AND_MD_FAIL if both padding and message digest check fail. 107 */ 108 ds_signature_check_t ds_hal_read_result(uint8_t *result, size_t size); 109 110 #ifdef __cplusplus 111 } 112 #endif 113