1 /***************************************************************************//** 2 * @file 3 * @brief Silicon Labs Secure Engine Manager API. 4 ******************************************************************************* 5 * # License 6 * <b>Copyright 2020 Silicon Laboratories Inc. www.silabs.com</b> 7 ******************************************************************************* 8 * 9 * SPDX-License-Identifier: Zlib 10 * 11 * The licensor of this software is Silicon Laboratories Inc. 12 * 13 * This software is provided 'as-is', without any express or implied 14 * warranty. In no event will the authors be held liable for any damages 15 * arising from the use of this software. 16 * 17 * Permission is granted to anyone to use this software for any purpose, 18 * including commercial applications, and to alter it and redistribute it 19 * freely, subject to the following restrictions: 20 * 21 * 1. The origin of this software must not be misrepresented; you must not 22 * claim that you wrote the original software. If you use this software 23 * in a product, an acknowledgment in the product documentation would be 24 * appreciated but is not required. 25 * 2. Altered source versions must be plainly marked as such, and must not be 26 * misrepresented as being the original software. 27 * 3. This notice may not be removed or altered from any source distribution. 28 * 29 ******************************************************************************/ 30 #ifndef SL_SE_MANAGER_ATTESTATION_H 31 #define SL_SE_MANAGER_ATTESTATION_H 32 33 #include "em_device.h" 34 35 #if (defined(SEMAILBOX_PRESENT) \ 36 && (_SILICON_LABS_SECURITY_FEATURE == _SILICON_LABS_SECURITY_FEATURE_VAULT)) \ 37 || defined(DOXYGEN) 38 39 /// @addtogroup sl_se_manager 40 /// @{ 41 42 /***************************************************************************//** 43 * @addtogroup sl_se_manager_attestation Attestation 44 * 45 * @brief 46 * System and configuration attestation 47 * 48 * @details 49 * API for retrieveing attestation tokens from the SE. 50 * 51 * @{ 52 ******************************************************************************/ 53 54 #include "sl_se_manager_key_handling.h" 55 #include "sl_se_manager_types.h" 56 #include "em_se.h" 57 #include "sl_status.h" 58 #include <stdint.h> 59 #include <stdbool.h> 60 #include <stddef.h> 61 62 #ifdef __cplusplus 63 extern "C" { 64 #endif 65 66 // ----------------------------------------------------------------------------- 67 // Defines 68 69 /// 32 byte challenge size 70 #define SL_SE_ATTESTATION_CHALLENGE_SIZE_32 (32U) 71 /// 48 byte challenge size 72 #define SL_SE_ATTESTATION_CHALLENGE_SIZE_48 (48U) 73 /// 64 byte challenge size 74 #define SL_SE_ATTESTATION_CHALLENGE_SIZE_64 (64U) 75 76 // ----------------------------------------------------------------------------- 77 // Prototypes 78 79 /***************************************************************************//** 80 * @brief 81 * Get the PSA initial attest token from the SE 82 * 83 * @param[in] cmd_ctx 84 * Pointer to an SE command context object. 85 * 86 * @param[in] auth_challenge 87 * Buffer with a challenge object selected by the caller. 88 * 89 * @param[in] challenge_size 90 * Size of the challenge object in bytes. Must be either 32, 48 or 64. 91 * 92 * @param[out] token_buf 93 * Buffer where the output token will be stored. 94 * 95 * @param[in] token_buf_size 96 * Size of token_buf in bytes. Must be at least the size found by calling 97 * \ref sl_se_attestation_get_psa_iat_token_size with equivalent arguments, 98 * and padded to word alignment. 99 * 100 * @param[out] token_size 101 * Number of bytes actually used in token_buf. 102 * 103 * @warning 104 * Once a nonce/challenge has been used, the same challenge should not be used 105 * ever again, to prevent replay attacks. 106 * 107 * @warning 108 * The output will be length-extended to the next word-multiple. 109 * 110 * @return 111 * Status code, @ref sl_status.h. 112 ******************************************************************************/ 113 sl_status_t sl_se_attestation_get_psa_iat_token(sl_se_command_context_t *cmd_ctx, 114 const uint8_t *auth_challenge, 115 size_t challenge_size, 116 uint8_t *token_buf, 117 size_t token_buf_size, 118 size_t *token_size); 119 120 /***************************************************************************//** 121 * @brief 122 * Get the size of a PSA initial attest token with the given nonce 123 * 124 * @param[in] cmd_ctx 125 * Pointer to an SE command context object. 126 * 127 * @param[in] challenge_size 128 * Size of the challenge object in bytes. Must be either 32, 48 or 64. 129 * 130 * @param[out] token_size 131 * Pointer to output word. Result is stored here. 132 * 133 * @return 134 * Status code, @ref sl_status.h. 135 ******************************************************************************/ 136 sl_status_t sl_se_attestation_get_psa_iat_token_size(sl_se_command_context_t *cmd_ctx, 137 size_t challenge_size, 138 size_t *token_size); 139 140 /***************************************************************************//** 141 * @brief 142 * Get an attested (signed) security configuration token from the SE 143 * 144 * @param[in] cmd_ctx 145 * Pointer to an SE command context object. 146 * 147 * @param[in] auth_challenge 148 * Buffer with a challenge object selected by the caller. 149 * 150 * @param[in] challenge_size 151 * Size of the challenge object in bytes. Must be 32. 152 * 153 * @param[out] token_buf 154 * Buffer where the output token will be stored. 155 * 156 * @param[in] token_buf_size 157 * Size of token_buf in bytes. Must be at least the size found by calling 158 * \ref sl_se_attestation_get_config_token_size with equivalent arguments, 159 * and padded to word alignment. 160 * 161 * @param[out] token_size 162 * Number of bytes actually used in token_buf. 163 * 164 * @warning 165 * Once a nonce/challenge has been used, the same challenge should not be used 166 * ever again, to prevent replay attacks. 167 * 168 * @warning 169 * The output will be length-extended to the next word-multiple. 170 * 171 * @return 172 * Status code, @ref sl_status.h. 173 ******************************************************************************/ 174 sl_status_t sl_se_attestation_get_config_token(sl_se_command_context_t *cmd_ctx, 175 const uint8_t *auth_challenge, 176 size_t challenge_size, 177 uint8_t *token_buf, 178 size_t token_buf_size, 179 size_t *token_size); 180 181 /***************************************************************************//** 182 * @brief 183 * Get the size of a security configuration token 184 * 185 * @param[in] cmd_ctx 186 * Pointer to an SE command context object. 187 * 188 * @param[in] challenge_size 189 * Size of the challenge object in bytes. Must be 32. 190 * 191 * @param[out] token_size 192 * Pointer to output word. Result is stored here. 193 * 194 * @return 195 * Status code, @ref sl_status.h. 196 ******************************************************************************/ 197 sl_status_t sl_se_attestation_get_config_token_size(sl_se_command_context_t *cmd_ctx, 198 size_t challenge_size, 199 size_t *token_size); 200 201 #ifdef __cplusplus 202 } 203 #endif 204 205 /// @} (end addtogroup sl_se_manager_attestation) 206 /// @} (end addtogroup sl_se_manager) 207 208 #endif // SEMAILBOX_PRESENT && VAULT 209 210 #endif // SL_SE_MANAGER_ATTESTATION_H 211
