1 /***************************************************************************//** 2 * @file 3 * @brief Silicon Labs Secure Engine Manager internal 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 SE_MANAGER_INTERNAL_H 31 #define SE_MANAGER_INTERNAL_H 32 33 #include "sli_se_manager_features.h" 34 35 #if defined(SLI_MAILBOX_COMMAND_SUPPORTED) || defined(SLI_VSE_MAILBOX_COMMAND_SUPPORTED) 36 37 #include "sl_status.h" 38 #include "em_se.h" 39 #include "sl_se_manager.h" 40 #include "sl_se_manager_key_handling.h" 41 42 #ifdef __cplusplus 43 extern "C" { 44 #endif 45 46 // ----------------------------------------------------------------------------- 47 // Defines 48 49 // ------------------------------- 50 // SE status codes 51 52 /// Response status codes for the Secure Engine 53 #define SLI_SE_RESPONSE_MASK 0x000F0000UL 54 /// Command executed successfully or signature was successfully validated. 55 #define SLI_SE_RESPONSE_OK 0x00000000UL 56 57 /// Command was not recognized as a valid command, or is not allowed in the 58 /// current context. 59 #define SLI_SE_RESPONSE_INVALID_COMMAND 0x00010000UL 60 /// User did not provide the required credentials to be allowed to execute the 61 /// command. 62 #define SLI_SE_RESPONSE_AUTHORIZATION_ERROR 0x00020000UL 63 /// Signature validation command (e.g. SE_COMMAND_SIGNATURE_VERIFY) failed to 64 /// verify the given signature as being correct. 65 #define SLI_SE_RESPONSE_INVALID_SIGNATURE 0x00030000UL 66 /// A command started in non-secure mode is trying to access secure memory. 67 #define SLI_SE_RESPONSE_BUS_ERROR 0x00040000UL 68 /// Internal error 69 #define SLI_SE_RESPONSE_INTERNAL_ERROR 0x00050000UL 70 /// An internal error was raised and the command did not execute. 71 #define SLI_SE_RESPONSE_CRYPTO_ERROR 0x00060000UL 72 /// One of the passed parameters is deemed invalid (e.g. out of bounds). 73 #define SLI_SE_RESPONSE_INVALID_PARAMETER 0x00070000UL 74 /// Failure while checking the host for secure boot 75 #define SLI_SE_RESPONSE_SECUREBOOT_ERROR 0x00090000UL 76 /// Failure during selftest 77 #define SLI_SE_RESPONSE_SELFTEST_ERROR 0x000A0000UL 78 /// Feature/item not initialized or not present 79 #define SLI_SE_RESPONSE_NOT_INITIALIZED 0x000B0000UL 80 /// Abort status code is given when no operation is attempted. 81 #define SLI_SE_RESPONSE_ABORT 0x00FF0000UL 82 #if defined(CRYPTOACC_PRESENT) 83 /// Root Code Mailbox is invalid. 84 #define SLI_SE_RESPONSE_MAILBOX_INVALID 0x00FE0000UL 85 #endif // CRYPTOACC_PRESENT 86 87 // ------------------------------- 88 // SE command words 89 // Commands are grouped based on availability 90 91 #define SLI_SE_COMMAND_CHECK_SE_IMAGE 0x43020000UL 92 #define SLI_SE_COMMAND_APPLY_SE_IMAGE 0x43030000UL 93 #define SLI_SE_COMMAND_STATUS_SE_IMAGE 0x43040000UL 94 #define SLI_SE_COMMAND_CHECK_HOST_IMAGE 0x43050001UL 95 #define SLI_SE_COMMAND_APPLY_HOST_IMAGE 0x43060001UL 96 #define SLI_SE_COMMAND_STATUS_HOST_IMAGE 0x43070000UL 97 98 #define SLI_SE_COMMAND_READ_OTP 0xFE040000UL 99 100 #define SLI_SE_COMMAND_INIT_OTP 0xFF000001UL 101 #define SLI_SE_COMMAND_INIT_PUBKEY 0xFF070001UL 102 #define SLI_SE_COMMAND_READ_PUBKEY 0xFF080001UL 103 104 #define SLI_SE_COMMAND_READ_PUBKEY 0xFF080001UL 105 #define SLI_SE_COMMAND_READ_OTP 0xFE040000UL 106 107 #define SLI_SE_COMMAND_DBG_LOCK_APPLY 0x430C0000UL 108 109 // Commands limited to SE devices 110 #if defined(SLI_MAILBOX_COMMAND_SUPPORTED) 111 #define SLI_SE_COMMAND_CREATE_KEY 0x02000000UL 112 #define SLI_SE_COMMAND_READPUB_KEY 0x02010000UL 113 114 #define SLI_SE_COMMAND_HASH 0x03000000UL 115 #define SLI_SE_COMMAND_HASHUPDATE 0x03010000UL 116 #define SLI_SE_COMMAND_HMAC 0x03020000UL 117 #define SLI_SE_COMMAND_HASHFINISH 0x03030000UL 118 119 #define SLI_SE_COMMAND_AES_ENCRYPT 0x04000000UL 120 #define SLI_SE_COMMAND_AES_DECRYPT 0x04010000UL 121 #define SLI_SE_COMMAND_AES_GCM_ENCRYPT 0x04020000UL 122 #define SLI_SE_COMMAND_AES_GCM_DECRYPT 0x04030000UL 123 #define SLI_SE_COMMAND_AES_CMAC 0x04040000UL 124 #define SLI_SE_COMMAND_AES_CCM_ENCRYPT 0x04050000UL 125 #define SLI_SE_COMMAND_AES_CCM_DECRYPT 0x04060000UL 126 127 #define SLI_SE_COMMAND_SIGNATURE_SIGN 0x06000000UL 128 #define SLI_SE_COMMAND_SIGNATURE_VERIFY 0x06010000UL 129 #define SLI_SE_COMMAND_EDDSA_SIGN 0x06020000UL 130 #define SLI_SE_COMMAND_EDDSA_VERIFY 0x06030000UL 131 132 #define SLI_SE_COMMAND_TRNG_GET_RANDOM 0x07000000UL 133 134 #define SLI_SE_COMMAND_JPAKE_R1_GENERATE 0x0B000000UL 135 #define SLI_SE_COMMAND_JPAKE_R1_VERIFY 0x0B000100UL 136 #define SLI_SE_COMMAND_JPAKE_R2_GENERATE 0x0B010000UL 137 #define SLI_SE_COMMAND_JPAKE_R2_VERIFY 0x0B010100UL 138 #define SLI_SE_COMMAND_JPAKE_GEN_SESSIONKEY 0x0B020000UL 139 140 #define SLI_SE_COMMAND_DH 0x0E000000UL 141 142 #define SLI_SE_COMMAND_STATUS_SE_VERSION 0x43080000UL 143 #define SLI_SE_COMMAND_STATUS_OTP_VERSION 0x43080100UL 144 #define SLI_SE_COMMAND_WRITE_USER_DATA 0x43090000UL 145 #define SLI_SE_COMMAND_ERASE_USER_DATA 0x430A0000UL 146 #define SLI_SE_COMMAND_DBG_LOCK_ENABLE_SECURE 0x430D0000UL 147 #define SLI_SE_COMMAND_DBG_LOCK_DISABLE_SECURE 0x430E0000UL 148 #define SLI_SE_COMMAND_DEVICE_ERASE 0x430F0000UL 149 #define SLI_SE_COMMAND_DEVICE_ERASE_DISABLE 0x43100000UL 150 #define SLI_SE_COMMAND_DBG_LOCK_STATUS 0x43110000UL 151 #define SLI_SE_COMMAND_DBG_SET_RESTRICTIONS 0x43120000UL 152 #define SLI_SE_COMMAND_PROTECTED_REGISTER 0x43210000UL 153 #if defined(SLI_SE_COMMAND_STATUS_READ_RSTCAUSE_AVAILABLE) 154 // SLI_SE_COMMAND_STATUS_READ_RSTCAUSE is only available on xG21 devices (series-2-config-1) 155 #define SLI_SE_COMMAND_STATUS_READ_RSTCAUSE 0x43220000UL 156 #endif // SLI_SE_COMMAND_STATUS_READ_RSTCAUSE_AVAILABLE 157 #define SLI_SE_COMMAND_READ_USER_CERT_SIZE 0x43FA0000UL 158 #define SLI_SE_COMMAND_READ_USER_CERT 0x43FB0000UL 159 160 #define SLI_SE_COMMAND_ENTER_ACTIVE_MODE 0x45000000UL 161 #define SLI_SE_COMMAND_EXIT_ACTIVE_MODE 0x45010000UL 162 163 #if (_SILICON_LABS_SECURITY_FEATURE == _SILICON_LABS_SECURITY_FEATURE_VAULT) 164 #define SLI_SE_COMMAND_ATTEST_PSA_IAT 0x0A030000UL 165 #define SLI_SE_COMMAND_ATTEST_CONFIG 0x0A040000UL 166 #endif // _SILICON_LABS_SECURITY_FEATURE_VAULT) 167 168 #define SLI_SE_COMMAND_GET_CHALLENGE 0xFD000001UL 169 #define SLI_SE_COMMAND_ROLL_CHALLENGE 0xFD000101UL 170 #define SLI_SE_COMMAND_OPEN_DEBUG 0xFD010001UL 171 172 #define SLI_SE_COMMAND_READ_SERIAL 0xFE000000UL 173 #define SLI_SE_COMMAND_GET_STATUS 0xFE010000UL 174 #define SLI_SE_COMMAND_READ_PUBKEYBOOT 0xFE020001UL 175 #define SLI_SE_COMMAND_SET_UPGRADEFLAG_SE 0xFE030000UL 176 #define SLI_SE_COMMAND_SET_UPGRADEFLAG_HOST 0xFE030001UL 177 #define SLI_SE_COMMAND_READ_TAMPER_RESET_CAUSE 0xFE050000UL 178 179 #define SLI_SE_COMMAND_INIT_PUBKEY_SIGNATURE 0xFF090001UL 180 #define SLI_SE_COMMAND_READ_PUBKEY_SIGNATURE 0xFF0A0001UL 181 #define SLI_SE_COMMAND_INIT_AES_128_KEY 0xFF0B0001UL 182 #endif // SLI_MAILBOX_COMMAND_SUPPORTED 183 184 // Commands limited to SE Vault High devices 185 #if (_SILICON_LABS_SECURITY_FEATURE == _SILICON_LABS_SECURITY_FEATURE_VAULT) 186 #define SLI_SE_COMMAND_WRAP_KEY 0x01000000UL 187 #define SLI_SE_COMMAND_UNWRAP_KEY 0x01020000UL 188 #define SLI_SE_COMMAND_DELETE_KEY 0x01050000UL 189 #define SLI_SE_COMMAND_TRANSFER_KEY 0x01060000UL 190 191 #define SLI_SE_COMMAND_DERIVE_KEY_PBKDF2_HMAC 0x02020002UL 192 #define SLI_SE_COMMAND_DERIVE_KEY_HKDF 0x02020003UL 193 #define SLI_SE_COMMAND_DERIVE_KEY_PBKDF2_CMAC 0x02020010UL 194 195 #define SLI_SE_COMMAND_CHACHAPOLY_ENCRYPT 0x0C000000UL 196 #define SLI_SE_COMMAND_CHACHAPOLY_DECRYPT 0x0C010000UL 197 #define SLI_SE_COMMAND_CHACHA20_ENCRYPT 0x0C020000UL 198 #define SLI_SE_COMMAND_CHACHA20_DECRYPT 0x0C030000UL 199 #define SLI_SE_COMMAND_POLY1305_KEY_MAC 0x0C040000UL 200 201 #define SLI_SE_COMMAND_DISABLE_TAMPER 0xFD020001UL 202 #endif // _SILICON_LABS_SECURITY_FEATURE_VAULT 203 204 // ------------------------------- 205 // SE command options 206 // Commands are grouped based on availability 207 208 /// Secure boot pubkey 209 #define SLI_SE_KEY_TYPE_BOOT 0x00000100UL 210 /// Secure authorization (debug) pubkey 211 #define SLI_SE_KEY_TYPE_AUTH 0x00000200UL 212 213 // Options limited to SE devices 214 #if defined(SLI_MAILBOX_COMMAND_SUPPORTED) 215 /// Root pubkey 216 #define SLI_SE_KEY_TYPE_ROOT 0x00000300UL 217 #if (_SILICON_LABS_SECURITY_FEATURE == _SILICON_LABS_SECURITY_FEATURE_VAULT) 218 /// Attestation pubkey 219 #define SLI_SE_KEY_TYPE_ATTEST 0x00000400UL 220 #endif // _SILICON_LABS_SECURITY_FEATURE_VAULT 221 /// BGL encryption key 222 #define SLI_SE_IMMUTABLE_KEY_TYPE_AES_128 0x00000500UL 223 224 /// Use MD5 as hash algorithm 225 #define SLI_SE_COMMAND_OPTION_HASH_MD5 0x00000100UL 226 /// Use SHA1 as hash algorithm 227 #define SLI_SE_COMMAND_OPTION_HASH_SHA1 0x00000200UL 228 /// Use SHA224 as hash algorithm 229 #define SLI_SE_COMMAND_OPTION_HASH_SHA224 0x00000300UL 230 /// Use SHA256 as hash algorithm 231 #define SLI_SE_COMMAND_OPTION_HASH_SHA256 0x00000400UL 232 233 /// Execute algorithm in ECB mode 234 #define SLI_SE_COMMAND_OPTION_MODE_ECB 0x00000100UL 235 /// Execute algorithm in CBC mode 236 #define SLI_SE_COMMAND_OPTION_MODE_CBC 0x00000200UL 237 /// Execute algorithm in CTR mode 238 #define SLI_SE_COMMAND_OPTION_MODE_CTR 0x00000300UL 239 /// Execute algorithm in CFB mode 240 #define SLI_SE_COMMAND_OPTION_MODE_CFB 0x00000400UL 241 242 /// Run the whole algorithm, all data present 243 #define SLI_SE_COMMAND_OPTION_CONTEXT_WHOLE 0x00000000UL 244 /// Start the algorithm, but get a context to later add more data 245 #define SLI_SE_COMMAND_OPTION_CONTEXT_START 0x00000001UL 246 /// End the algorithm, get the result 247 #define SLI_SE_COMMAND_OPTION_CONTEXT_END 0x00000002UL 248 /// Add more data input to the algorithm. Need to supply previous context, 249 /// and get a context back 250 #define SLI_SE_COMMAND_OPTION_CONTEXT_ADD 0x00000003UL 251 252 /// Magic paramater for deleting user data 253 #define SLI_SE_COMMAND_OPTION_ERASE_UD 0xDE1E7EADUL 254 #define SLI_SE_COMMAND_CERT_BATCH 0x00000100UL 255 #define SLI_SE_COMMAND_CERT_SE 0x00000200UL 256 #define SLI_SE_COMMAND_CERT_HOST 0x00000300UL 257 258 #if (_SILICON_LABS_SECURITY_FEATURE == _SILICON_LABS_SECURITY_FEATURE_VAULT) 259 /// Use SHA384 as hash algorithm 260 #define SLI_SE_COMMAND_OPTION_HASH_SHA384 0x00000500UL 261 /// Use SHA512 as hash algorithm 262 #define SLI_SE_COMMAND_OPTION_HASH_SHA512 0x00000600UL 263 #endif // _SILICON_LABS_SECURITY_FEATURE_VAULT 264 #endif // SLI_MAILBOX_COMMAND_SUPPORTED 265 266 // ------------------------------- 267 // Other defines 268 269 #if defined(SLI_MAILBOX_COMMAND_SUPPORTED) 270 // Due to a problem with the countermeasures applied to 271 // accelerated point multiplication over elliptic curves, 272 // it is possible that random errors are encountered (this 273 // is extremely unilkely for truly random keys). 274 // As a workaround for this, the affected commands will 275 // retry the operation in order to reduce the probability 276 // that the error code was returned incorrectly. This helps 277 // lower the error probability further when using purposely 278 // small or large scalars, for example during testing. 279 #define SLI_SE_MAX_POINT_MULT_RETRIES 3U 280 #endif 281 282 // ------------------------------- 283 // Function-like macros 284 285 /***************************************************************************//** 286 * @brief 287 * Helper macro to init/reset the SE command struct of an SE command context 288 * 289 * @param[in] cmd_ctx 290 * Pointer to SE context containing the command to initialize/reset 291 * 292 * @param[out] command_word 293 * Command word to set in the SE command. 294 * 295 ******************************************************************************/ 296 #define sli_se_command_init(cmd_ctx, command_word) \ 297 cmd_ctx->command.command = command_word; \ 298 cmd_ctx->command.data_in = NULL; \ 299 cmd_ctx->command.data_out = NULL; \ 300 cmd_ctx->command.num_parameters = 0; 301 302 #if defined(SLI_MAILBOX_COMMAND_SUPPORTED) 303 /***************************************************************************//** 304 * @brief 305 * Helper macros to add key parameters and input/output blocks to SE commands 306 * 307 * @param[in] cmd_ctx 308 * Pointer to SE context 309 * @param[in] key 310 * Pointer to sl_se_key_descriptor_t structure 311 * @param[out] status 312 * SL_Status_T 313 * 314 ******************************************************************************/ 315 316 // Add keyspec to command for given key 317 #define sli_add_key_parameters(cmd_ctx, key, status) { \ 318 uint32_t keyspec; \ 319 (status) = sli_se_key_to_keyspec((key), &keyspec); \ 320 if ((status) != SL_STATUS_OK) { \ 321 return (status); \ 322 } \ 323 SE_addParameter(&cmd_ctx->command, keyspec); \ 324 } 325 326 // Add key metadata buffers to command for given key 327 #define sli_add_key_metadata(cmd_ctx, key, status) \ 328 /* Auth data */ \ 329 SE_DataTransfer_t auth_buffer; \ 330 (status) = sli_se_get_auth_buffer((key), &auth_buffer); \ 331 if ((status) != SL_STATUS_OK) { \ 332 return (status); \ 333 } \ 334 SE_addDataInput(&cmd_ctx->command, &auth_buffer); 335 336 // Add key metadata buffers with custom auth buffer to command for given key 337 #define sli_add_key_metadata_custom(cmd_ctx, auth_data_buf, key, status) \ 338 /* Auth data */ \ 339 SE_DataTransfer_t auth_data_buf; \ 340 (status) = sli_se_get_auth_buffer((key), &auth_data_buf); \ 341 if ((status) != SL_STATUS_OK) { \ 342 return (status); \ 343 } \ 344 SE_addDataInput(&cmd_ctx->command, &auth_data_buf); 345 346 // Add key input buffer to given command 347 #define sli_add_key_input(cmd_ctx, key, status) \ 348 SE_DataTransfer_t key_input_buffer; \ 349 (status) = sli_se_get_key_input_output((key), &key_input_buffer); \ 350 if ((status) != SL_STATUS_OK) { \ 351 return (status); \ 352 } \ 353 SE_addDataInput(&cmd_ctx->command, &key_input_buffer); 354 355 // Add Key output buffer to given command 356 #define sli_add_key_output(cmd_ctx, key, status) \ 357 SE_DataTransfer_t key_output_buffer; \ 358 (status) = sli_se_get_key_input_output((key), &key_output_buffer); \ 359 if ((status) != SL_STATUS_OK) { \ 360 return (status); \ 361 } \ 362 SE_addDataOutput(&cmd_ctx->command, &key_output_buffer); 363 #endif // SLI_MAILBOX_COMMAND_SUPPORTED 364 365 /******************************************************************************* 366 ***************************** PROTOTYPES ********************************** 367 ******************************************************************************/ 368 369 sl_status_t sli_se_to_sl_status(SE_Response_t res); 370 371 /***************************************************************************//** 372 * @brief 373 * Take the SE lock in order to synchronize multiple threads calling into 374 * the SE Manager API concurrently. 375 * 376 * @return 377 * SL_STATUS_OK when successful, or else error code. 378 ******************************************************************************/ 379 sl_status_t sli_se_lock_acquire(void); 380 381 /***************************************************************************//** 382 * @brief 383 * Give the SE lock in order to synchronize multiple threads calling into 384 * the SE Manager API concurrently. 385 * 386 * @return 387 * SL_STATUS_OK when successful, or else error code. 388 ******************************************************************************/ 389 sl_status_t sli_se_lock_release(void); 390 391 /***************************************************************************//** 392 * @brief 393 * Execute and wait for mailbox command to complete. 394 * 395 * @param[in] cmd_ctx 396 * Pointer to an SE command context object. 397 * 398 * @return 399 * Status code, @ref sl_status.h. 400 ******************************************************************************/ 401 sl_status_t sli_se_execute_and_wait(sl_se_command_context_t *cmd_ctx); 402 403 #if defined(SLI_MAILBOX_COMMAND_SUPPORTED) 404 // Key handling helper functions 405 sl_status_t sli_key_get_storage_size(const sl_se_key_descriptor_t* key, 406 uint32_t *storage_size); 407 sl_status_t sli_key_get_size(const sl_se_key_descriptor_t* key, uint32_t* size); 408 sl_status_t sli_key_check_equivalent(const sl_se_key_descriptor_t* key_1, 409 const sl_se_key_descriptor_t* key_2, 410 bool check_key_flag, 411 bool public_export); 412 413 sl_status_t sli_se_key_to_keyspec(const sl_se_key_descriptor_t* key, 414 uint32_t* keyspec); 415 sl_status_t sli_se_keyspec_to_key(const uint32_t keyspec, 416 sl_se_key_descriptor_t* key); 417 sl_status_t sli_se_get_auth_buffer(const sl_se_key_descriptor_t* key, 418 SE_DataTransfer_t* auth_buffer); 419 sl_status_t sli_se_get_key_input_output(const sl_se_key_descriptor_t* key, 420 SE_DataTransfer_t* buffer); 421 #endif // SLI_MAILBOX_COMMAND_SUPPORTED 422 423 #ifdef __cplusplus 424 } 425 #endif 426 427 #endif /* defined(SLI_MAILBOX_COMMAND_SUPPORTED) || defined(SLI_VSE_MAILBOX_COMMAND_SUPPORTED) */ 428 429 #endif /* SE_MANAGER_INTERNAL_H */ 430
