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 Write the initialization vector. 65 */ 66 void ds_hal_configure_iv(const uint32_t *iv); 67 68 /** 69 * @brief Write the message which should be signed. 70 * 71 * @param msg Pointer to the message. 72 * @param size Length of signature result in bytes. It is the RSA signature length in bytes. 73 */ 74 void ds_hal_write_message(const uint8_t *msg, size_t size); 75 76 /** 77 * @brief Write the encrypted private key parameters. 78 */ 79 void ds_hal_write_private_key_params(const uint8_t *block); 80 81 /** 82 * @brief Begin signing procedure. 83 */ 84 void ds_hal_start_sign(void); 85 86 /** 87 * @brief Check whether the hardware is busy with an operation. 88 * 89 * @return True if the hardware has finished the signing procedure, otherwise false. 90 */ 91 bool ds_hal_busy(void); 92 93 /** 94 * @brief Check and read the signature from the hardware. 95 * 96 * @return 97 * - DS_SIGNATURE_OK if no issue is detected with the signature. 98 * - DS_SIGNATURE_PADDING_FAIL if the padding of the private key parameters is wrong. 99 * - DS_SIGNATURE_MD_FAIL if the message digest check failed. This means that the message digest calculated using 100 * the private key parameters fails, i.e., the integrity of the private key parameters is not protected. 101 * - DS_SIGNATURE_PADDING_AND_MD_FAIL if both padding and message digest check fail. 102 */ 103 ds_signature_check_t ds_hal_read_result(uint8_t *result, size_t size); 104 105 #ifdef __cplusplus 106 } 107 #endif 108
