1 /* 2 * Copyright 2022 NXP 3 * All rights reserved. 4 * 5 * SPDX-License-Identifier: BSD-3-Clause 6 */ 7 #ifndef _FSL_ROMAPI_NBOOT_H_ 8 #define _FSL_ROMAPI_NBOOT_H_ 9 10 #include <stdlib.h> 11 #include <stdint.h> 12 #include "fsl_common.h" 13 14 15 /********************************************** 16 * CONSTANTS 17 **********************************************/ 18 #define NBOOT_RESET_VALUE 0x0U 19 20 #define NBOOT_IMG_LENGTH_OFFSET 0x20U 21 #define NBOOT_IMG_TYPE_OFFSET 0x24U 22 #define NBOOT_IMG_EXTHEADER_OFFSET 0x28U 23 24 #define NBOOT_IMG_TYPE_PLAIN 0x0U 25 #define NBOOT_IMG_TYPE_PLAIN_SIGNED 0x1U 26 #define NBOOT_IMG_TYPE_PLAIN_CRC 0x2U 27 #define NBOOT_IMG_TYPE_ENCRYPTED_SIGNED 0x3U 28 #define NBOOT_IMG_TYPE_XIPPLAINSIGNED 0x4U 29 #define NBOOT_IMG_TYPE_XIPPLAINCRC 0x5U 30 #define NBOOT_IMG_TYPE_SB3MANIFEST 0x6U 31 #define NBOOT_IMG_TYPE_SB3MANIFEST_NXPKEYS 0x7U 32 #define NBOOT_IMG_TYPE_XIPPLAINSIGNED_NXPKEYS 0x8U 33 #define NBOOT_IMG_TYPE_PLAIN_RADIO 0x40U 34 #define NBOOT_IMG_TYPE_SB3MANIFEST_RADIO_NXPKEYS 0x47U 35 36 #define NBOOT_IMG_TYPE_MASK 0xFFU 37 38 #define NBOOT_IMG_SELECTOR_MBI 0xAA55AA55U 39 #define NBOOT_IMG_SELECTOR_SB3 0x55AA55AAU 40 41 #define NBOOT_IMG_ROOTCERT_DIRECT_SIGN_TRUE 0x80000000U 42 #define NBOOT_IMG_ROOTCERT_DIRECT_SIGN_FALSE 0x00000000U 43 #define NBOOT_IMG_ROOTCERT_DIRECT_SIGN_MASK 0x80000000U 44 45 #define NBOOT_IMG_FORCECERTCHAIN_BIT 0x1U 46 47 #define NBOOT_IMG_CERTBLOCK_MAGIC 0x72646863U 48 #define NBOOT_IMG_IMGMANIFEST_MAGIC 0x6d676d69U 49 #define NBOOT_IMG_IMGMANIFEST_MIN_SIZE_IN_BYTES (20u) /* image manifest header (20) */ 50 51 #define NBOOT_ROOT_CERT_FLAG_CURVE_MASK 0xFU 52 #define NBOOT_ROOT_CERT_FLAG_CURVE_OFFSET 0x0U 53 #define NBOOT_ROOT_CERT_FLAG_CURVE_P256 0x1U 54 #define NBOOT_ROOT_CERT_FLAG_CURVE_P384 0x2U 55 #define NBOOT_ROOT_CERT_FLAG_NR_ROOTKEYHASHES_MASK 0xFU 56 #define NBOOT_ROOT_CERT_FLAG_NR_ROOTKEYHASHES_OFFSET 0x4U 57 #define NBOOT_ROOT_CERT_FLAG_ROOTKEY_INDEX_MASK 0xFU 58 #define NBOOT_ROOT_CERT_FLAG_ROOTKEY_INDEX_OFFSET 0x8U 59 60 #define NBOOT_ISK_CERT_FLAG_CURVE_MASK 0xFU 61 #define NBOOT_ISK_CERT_FLAG_CURVE_OFFSET 0x0U 62 #define NBOOT_ISK_CERT_FLAG_CURVE_P256 0x1U 63 #define NBOOT_ISK_CERT_FLAG_CURVE_P384 0x2U 64 #define NBOOT_ISK_USER_DATA_MAX_SIZE_IN_BYTES (96u) 65 66 #define NBOOT_CERTBLOCK_MAX_LENGTH_IN_BYTES ((508u) + NBOOT_ISK_USER_DATA_MAX_SIZE_IN_BYTES) /* 508 + user data size */ 67 #define NBOOT_CERTBLOCK_MIN_LENGTH_IN_BYTES (80u) /* Certificate block header (12) + flags (4) + secp256 public key (64) */ 68 69 #define NBOOT_ROOT_CERT_COUNT (4u) 70 #define NBOOT_CONTEXT_BYTELEN (192u + NXPCLHASH_WA_SIZE_MAX) 71 #define NBOOT_CONTEXT_WORDLEN (NBOOT_CONTEXT_BYTELEN/sizeof(uint32_t)) 72 #define NBOOT_KEYINFO_WORDLEN (23u) 73 #define NBOOT_EC_COORDINATE_256_SIZE_IN_BYTES (32u) 74 #define NBOOT_EC_COORDINATE_384_SIZE_IN_BYTES (48u) 75 #define NBOOT_EC_COORDINATE_521_SIZE_IN_BYTES (66u) 76 77 #define NBOOT_EC_COORDINATE_MAX_SIZE NBOOT_EC_COORDINATE_384_SIZE_IN_BYTES 78 #define NBOOT_EC_MIN_SIGNATURE_SIZE_IN_BYTES (2u*NBOOT_EC_COORDINATE_256_SIZE_IN_BYTES) 79 80 #define NBOOT_ROOT_OF_TRUST_HASH_SIZE_IN_BYTES (48u) 81 82 /* SB3.1 */ 83 #define NBOOT_SB3_MANIFEST_MAX_LENGTH_IN_BYTES ((712u) + NBOOT_ISK_USER_DATA_MAX_SIZE_IN_BYTES) /* 712 + user data size */ 84 #define NBOOT_SB3_MANIFEST_MIN_LENGTH_IN_BYTES (236u) /* sb3.1 header (60) + sha256 hash (32) + min cert block (80) + secp256 signature (64) */ 85 #define NBOOT_SB3_CHUNK_SIZE_IN_BYTES (256u) 86 #define NBOOT_SB3_BLOCK_HASH256_SIZE_IN_BYTES (32u) 87 #define NBOOT_SB3_BLOCK_HASH384_SIZE_IN_BYTES (48u) 88 89 /* authStatus */ 90 #define NBOOT_MBI_AUTH_P384_MASK (1u << 0) 91 #define NBOOT_MBI_AUTH_P256_MASK (1u << 1) 92 #define NBOOT_CSS_INITIALIZED (1u << 2) 93 #define NBOOT_AUTH_STATUS_SB3_TYPE_NXP_MFW (1u << 3) 94 #define NBOOT_AUTH_STATUS_SB3_TYPE_OEM_MFW (1u << 4) 95 #define NBOOT_AUTH_STATUS_SB3_TYPE_MASK (NBOOT_AUTH_STATUS_SB3_TYPE_NXP_MFW | NBOOT_AUTH_STATUS_SB3_TYPE_OEM_MFW) 96 #define NBOOT_MBI_AUTH_ROOT_KEY_INDEX_SHIFT (16) 97 #define NBOOT_MBI_AUTH_ROOT_KEY_INDEX_MASK (0x3u << NBOOT_MBI_AUTH_ROOT_KEY_INDEX_SHIFT) 98 99 #define NBOOT_STATE_SB3_TYPE_SHIFT (24) 100 #define NBOOT_STATE_SB3_TYPE_MASK (0x3u << NBOOT_STATE_SB3_TYPE_SHIFT) 101 #define NBOOT_STATE_FIPS_CKDF_SHIFT (23) 102 #define NBOOT_STATE_FIPS_HMAC_SHIFT (22) 103 #define NBOOT_STATE_FIPS_DRBG_SHIFT (21) 104 #define NBOOT_STATE_FIPS_ECDSA_SHIFT (20) 105 #define NBOOT_STATE_FIPS_AES_SHIFT (19) 106 #define NBOOT_STATE_FIPS_SHA_SHIFT (18) 107 #define NBOOT_STATE_FIPS_ALL_MASK ((1u << NBOOT_STATE_FIPS_CKDF_SHIFT) | (1u << NBOOT_STATE_FIPS_HMAC_SHIFT) | \ 108 (1u << NBOOT_STATE_FIPS_DRBG_SHIFT) | (1u << NBOOT_STATE_FIPS_ECDSA_SHIFT) | \ 109 (1u << NBOOT_STATE_FIPS_AES_SHIFT) | (1u << NBOOT_STATE_FIPS_SHA_SHIFT)) 110 /* SB 3.1 manifest flags */ 111 #define NBOOT_SB3_MANIFEST_FLAGS_PROV_MFW (0x00000001u) 112 #define NBOOT_SB3_MANIFEST_FLAGS_PROV_MFW_MASK (0x00000001u) 113 114 #define NBOOT_SB3_MANIFEST_FLAGS_RADIO_TYPE_WIFI (0x00000001u) 115 #define NBOOT_SB3_MANIFEST_FLAGS_RADIO_TYPE_BLE (0x00000002u) 116 #define NBOOT_SB3_MANIFEST_FLAGS_RADIO_TYPE_15_4 (0x00000003u) 117 #define NBOOT_SB3_MANIFEST_FLAGS_RADIO_TYPE_MASK (0x0000000Fu) 118 119 /* TP flags */ 120 #define NBOOT_OEM_SHARE_VALID_FLAG 0x95959595u 121 122 123 #define NBOOT_RCS_ARRAY(NAME, SIZE) NAME[SIZE] __attribute__((section(".rcs." #NAME))) __USED 124 125 126 /*! 127 * @brief NBOOT type for a timestamp 128 * 129 * This type defines the NBOOT timestamp 130 * 131 */ 132 typedef uint32_t nboot_timestamp_t[2]; 133 134 /*! 135 * @brief NBOOT SB3.1 header type 136 * 137 * This type defines the header used in the SB3.1 manifest 138 * 139 */ 140 typedef struct _nboot_sb3_header 141 { 142 uint32_t magic; /*! offset 0x00: Fixed 4-byte string of 'sbv3' without the trailing NULL */ 143 uint32_t formatVersion; /*! offset 0x04: (major = 3, minor = 1); The format version determines the manifest (block0) size. */ 144 uint32_t flags; /*! offset 0x08: not defined yet, keep zero for future compatibility */ 145 uint32_t blockCount; /*! offset 0x0C: Number of blocks not including the manifest (block0). */ 146 uint32_t blockSize; /*! offset 0x10: Size in bytes of data block (repeated blockCount times for SB3 data stream). */ 147 nboot_timestamp_t timeStamp; /*! offset 0x14: 64-bit value used as key derivation data. */ 148 uint32_t firmwareVersion; /*! offset 0x1c: Version number of the included firmware */ 149 uint32_t imageTotalLength; /*! offset 0x20: Total manifest length in bytes, including signatures etc. */ 150 uint32_t imageType; /*! offset 0x24: image type and flags */ 151 uint32_t certificateBlockOffset; /*! offset 0x28: Offset from start of header block to the certificate block. */ 152 uint8_t description[16]; /*! offset 0x32: This field provides description of the file. It is an arbitrary 153 string injected by the signing tool, which helps to identify the file. */ 154 } nboot_sb3_header_t; 155 156 #define NBOOT_SB3_MANIFEST_MAX_SIZE_IN_BYTES \ 157 (sizeof(nboot_sb3_header_t) + NBOOT_SB3_BLOCK_HASH384_SIZE_IN_BYTES + sizeof(nboot_certificate_block_t) + \ 158 NBOOT_EC_COORDINATE_MAX_SIZE * 2) 159 #define NBOOT_SB3_BLOCK_MAX_SIZE_IN_BYTES \ 160 (4 /* blockNumber */ + NBOOT_SB3_BLOCK_HASH384_SIZE_IN_BYTES + NBOOT_SB3_CHUNK_SIZE_IN_BYTES) 161 162 /*! @brief The size of the blob with Key Blob. */ 163 #define NBOOT_KEY_BLOB_SIZE_IN_BYTE_256 (32U) 164 #define NBOOT_KEY_BLOB_SIZE_IN_BYTE_384 (48U) 165 #define NBOOT_KEY_BLOB_SIZE_IN_BYTE_MAX (NBOOT_KEY_BLOB_SIZE_IN_BYTE_384) 166 167 #define SB3_DATA_BUFFER_SIZE_IN_BYTE (MAX(128, NBOOT_KEY_BLOB_SIZE_IN_BYTE_MAX)) 168 169 /********************************************** 170 * TYPEDEFS 171 **********************************************/ 172 /*! 173 * @brief Boolean type for the NBOOT functions 174 * 175 * This type defines boolean values used by NBOOT functions that are not easily disturbed by Fault Attacks 176 * 177 */ 178 typedef enum _nboot_bool 179 { 180 kNBOOT_TRUE = 0x3C5AC33Cu, /*!< Value for TRUE. */ 181 kNBOOT_TRUE256 = 0x3C5AC35Au, /*!< Value for TRUE when P256 was used to sign the image. */ 182 kNBOOT_TRUE384 = 0x3C5AC3A5u, /*!< Value for TRUE when P384 was used to sign the image. */ 183 kNBOOT_FALSE = 0x5AA55AA5u, /*!< Value for FALSE. */ 184 kNBOOT_OperationAllowed = 0x3c5a33ccU, 185 kNBOOT_OperationDisallowed = 0x5aa5cc33U, 186 } nboot_bool_t; 187 188 /*! @brief Data structure holding secure counter value used by nboot library */ 189 typedef struct _nboot_secure_counter 190 { 191 uint32_t sc; 192 uint32_t scAp; 193 } nboot_secure_counter_t; 194 195 /** Type for nboot protected status codes */ 196 typedef uint64_t nboot_status_protected_t; 197 198 /** Type for nboot status codes */ 199 typedef uint32_t nboot_status_t; 200 201 typedef int romapi_status_t; 202 203 #define kStatusGroup_NBOOT_PUF (0x69u) 204 #define kStatusGroup_NBOOT_PRINCE (0x6au) 205 206 //! @brief Interface to memory operations for one region of memory. 207 typedef struct 208 { 209 status_t (*init)(void); 210 status_t (*read)(uint32_t address, uint32_t length, uint8_t *buffer); 211 status_t (*write)(uint32_t address, uint32_t length, const uint8_t *buffer); 212 status_t (*fill)(uint32_t address, uint32_t length, uint32_t pattern); 213 status_t (*flush)(void); 214 status_t (*erase)(uint32_t address, uint32_t length); 215 status_t (*config)(uint32_t *buffer); 216 status_t (*erase_all)(void); 217 } memory_region_interface_t; 218 219 //! @brief Structure of a memory map entry. 220 typedef struct 221 { 222 uint32_t startAddress; 223 uint32_t endAddress; 224 uint32_t memoryProperty; 225 uint32_t memoryId; 226 const memory_region_interface_t *memoryInterface; 227 } memory_map_entry_t; 228 229 230 /** 231 * \defgroup nbootStatusValues This type defines status return values used by NBOOT functions that are not easily disturbed by Fault Attacks 232 * @{ 233 */ 234 #define kStatus_NBOOT_Success ((nboot_status_t) 0x5A5A5A5Au) /*!< Operation completed successfully. */ 235 #define kStatus_NBOOT_Fail ((nboot_status_t) 0x5A5AA5A5u) /*!< Operation failed. */ 236 #define kStatus_NBOOT_InvalidArgument ((nboot_status_t) 0x5A5AA5F0u) /*!< Invalid argument passed to the function. */ 237 #define kStatus_NBOOT_RequestTimeout ((nboot_status_t) 0x5A5AA5E1u) /*!< Operation timed out. */ 238 #define kStatus_NBOOT_KeyNotLoaded ((nboot_status_t) 0x5A5AA5E2u) /*!< The requested key is not loaded. */ 239 #define kStatus_NBOOT_AuthFail ((nboot_status_t) 0x5A5AA5E4u) /*!< Authentication failed. */ 240 #define kStatus_NBOOT_OperationNotAvaialable ((nboot_status_t) 0x5A5AA5E5u) /*!< Operation not available on this HW. */ 241 #define kStatus_NBOOT_KeyNotAvailable ((nboot_status_t) 0x5A5AA5E6u) /*!< Key is not avaialble. */ 242 #define kStatus_NBOOT_IvCounterOverflow ((nboot_status_t) 0x5A5AA5E7u) /*!< Overflow of IV counter (PRINCE/IPED). */ 243 #define kStatus_NBOOT_SelftestFail ((nboot_status_t) 0x5A5AA5E8u) /*!< FIPS self-test failure. */ 244 #define kStatus_NBOOT_InvalidDataFormat ((nboot_status_t) 0x5A5AA5E9u) /*!< Invalid data format for example antipole */ 245 #define kStatus_NBOOT_IskCertUserDataTooBig ((nboot_status_t) 0x5A5AA5EAu) /*!< Size of User data in ISK certificate is greater than 96 bytes */ 246 #define kStatus_NBOOT_IskCertSignatureOffsetTooSmall ((nboot_status_t) 0x5A5AA5EBu) /*!< Signature offset in ISK certificate is smaller than expected */ 247 #define kStatus_NBOOT_MemcpyFail ((nboot_status_t)0x5A5A845A) /*!< Unexpected error detected during nboot_memcpy() */ 248 249 #define NXPCLCSS_HASH_RTF_OUTPUT_SIZE ((size_t)32U) ///< Size of run-time fingerprint appended to the hash in @p pDigest in bytes, if #NXPCLCSS_HASH_RTF_OUTPUT_ENABLE was specified 250 #define NXPCLHASH_WA_SIZE_MAX (128u+64u) 251 252 /**@}*/ 253 254 /*! 255 * @brief NBOOT context type 256 * 257 * This type defines the NBOOT context 258 * 259 */ 260 typedef struct _nboot_context 261 { 262 uint32_t totalBlocks; /*!< holds number of SB3 blocks. Initialized by nboot_sb3_load_header(). */ 263 uint32_t processData; /*!< flag, initialized by nboot_sb3_load_header(). 264 SB3 related flag set by NBOOT in case the nboot_sb3_load_block() 265 provides plain data to output buffer (for processing by ROM SB3 loader */ 266 uint32_t timeout; /*!< timeout value for css operation. In case it is 0, infinite wait is performed */ 267 uint32_t keyinfo[NBOOT_KEYINFO_WORDLEN]; /*!< data for NBOOT key management. */ 268 uint32_t context[NBOOT_CONTEXT_WORDLEN]; /*!< work area for NBOOT lib. */ 269 uint32_t uuid[4]; /*!< holds UUID value from NMPA */ 270 uint32_t prngReadyFlag; /*!< flag, used by nboot_rng_generate_lq_random() to determine whether CSS is ready to generate rnd number */ 271 uint32_t multipartMacBuffer[1024/sizeof(uint32_t)]; 272 uint32_t oemShareValidFlag; /*!< flag, used during TP to determine whether valid oemShare was set by nboot_tp_isp_gen_oem_master_share() */ 273 uint32_t oemShare[4]; /*!< buffer to store OEM_SHARE computed by nxpCLTrustProv_nboot_isp_gen_oem_master_share() */ 274 nboot_secure_counter_t secureCounter; /*!< Secure counter used by nboot */ 275 uint32_t rtf[NXPCLCSS_HASH_RTF_OUTPUT_SIZE/sizeof(uint32_t)]; 276 uint32_t imageHash[48/sizeof(uint32_t)]; 277 uint32_t authStatus; 278 nboot_bool_t disableProvisioningFirmwareNXP; /*!< Flag to disable execution of NXP signed provisioning Firmwares */ 279 } nboot_context_t; 280 281 /*! 282 * @brief NBOOT type for an ECC coordinate 283 * 284 * This type defines the NBOOT ECC coordinate type 285 * 286 */ 287 typedef uint8_t nboot_ecc_coordinate_t[NBOOT_EC_COORDINATE_MAX_SIZE]; /*!ECC point coordinate, up to 384-bits. big endian. */ 288 289 /*! 290 * @brief NBOOT type for an ECC signature 291 * 292 * This type defines the NBOOT ECC signature type 293 * 294 */ 295 typedef struct 296 { 297 nboot_ecc_coordinate_t r; /*! r portion of the ECDSA signature, up to 384-bits. big endian. */ 298 nboot_ecc_coordinate_t s; /*! s portion of the ECDSA signature, up to 384-bits. big endian. */ 299 } nboot_ecdsa_signature_t; 300 301 /*! 302 * @brief NBOOT type for an ECC point 303 * 304 * This type defines the NBOOT ECC point type 305 * 306 */ 307 typedef struct 308 { 309 nboot_ecc_coordinate_t x; /*! x portion of the ECDSA public key, up to 384-bits. big endian. */ 310 nboot_ecc_coordinate_t y; /*! y portion of the ECDSA public key, up to 384-bits. big endian. */ 311 } nboot_ecdsa_public_key_t; 312 313 typedef uint8_t nboot_ctrk_hash_t[NBOOT_ROOT_OF_TRUST_HASH_SIZE_IN_BYTES]; 314 315 /*! 316 * @brief NBOOT type for the hash table 317 * 318 * This type defines the NBOOT hash table 319 * 320 */ 321 typedef struct _nboot_ctrk_hash_table 322 { 323 nboot_ctrk_hash_t ctrkHashTable[NBOOT_ROOT_CERT_COUNT]; 324 } nboot_ctrk_hash_table_t; 325 326 /*! 327 * @brief NBOOT type for the isk block 328 * 329 * This type defines the constant length part of an NBOOT isk block 330 * 331 */ 332 typedef struct 333 { 334 uint32_t signatureOffset; /*! Offset of signature in ISK block. */ 335 uint32_t constraints; /*! Version number of signing certificate. */ 336 uint32_t iskFlags; /*! Reserved for definiton of ISK certificate flags. */ 337 nboot_ecdsa_public_key_t iskPubKey; /*! Public key of signing certificate. Variable length; only used to determine start address*/ 338 nboot_ecdsa_public_key_t userData; /*! Space for at lest one addition public key*/ 339 nboot_ecdsa_signature_t iskSign; /*! ISK signature*/ 340 } nboot_isk_block_t; 341 342 /*! 343 * @brief NBOOT type for the root certificate block 344 * 345 * This type defines the NBOOT root certificate block, it is part of the nboot_certificate_block_t 346 * 347 */ 348 typedef struct _nboot_root_certificate_block 349 { 350 uint32_t flags; //!< root certificate flags 351 nboot_ctrk_hash_table_t ctrkHashTable; //!< hash table 352 nboot_ecdsa_public_key_t rootPublicKey; //!< root public key 353 } nboot_root_certificate_block_t; 354 355 /*! 356 * @brief NBOOT type for the header of the certificate block 357 * 358 * This type defines the NBOOT header of the certificate block, it is part of the nboot_certificate_block_t 359 * 360 */ 361 typedef struct _nboot_certificate_header_block 362 { 363 uint32_t magic; //!< magic number. 364 uint32_t formatMajorMinorVersion; //!< format major minor version 365 uint32_t certBlockSize; //!< Size of the full certificate block 366 } nboot_certificate_header_block_t; 367 368 /*! 369 * @brief NBOOT type for the certificate block 370 * 371 * This type defines the constant length part of an NBOOT image manifest 372 * 373 */ 374 typedef struct _nboot_image_manifest_block 375 { 376 uint32_t magic; //!< magic number 377 uint32_t formatMajorMinorVersion; //!< format major minor version 378 uint32_t firmwareVersion; //!< firmware versino number 379 uint32_t imageManifestSize; //!< Size of image manifest 380 uint32_t flags; //!< image manifest flags 381 } nboot_image_manifest_block_t; 382 383 /*! 384 * @brief NBOOT type for the certificate block 385 * 386 * This type defines the constant length part of an NBOOT certificate block 387 * 388 */ 389 typedef struct _nboot_certificate_block 390 { 391 nboot_certificate_header_block_t header; 392 nboot_root_certificate_block_t rootCertBlock; /*! Details of selected root certificate (root certificate which will be used for ISK signing/SB3 header signing) */ 393 nboot_isk_block_t iskBlock; 394 } nboot_certificate_block_t; 395 /*! 396 * @brief NBOOT type for the root key revocation 397 * 398 * This type defines the NBOOT root key revocation 399 * 400 */ 401 #define kNBOOT_RootKey_Enabled (0xAAu) 402 #define kNBOOT_RootKey_Revoked (0xBBu) 403 /* any other value means the root key is revoked */ 404 typedef uint32_t nboot_root_key_revocation_t; 405 406 /*! 407 * @brief NBOOT type for the root key usage 408 * 409 * This type defines the NBOOT root key usage 410 * 411 */ 412 #define kNBOOT_RootKeyUsage_DebugCA_ImageCA_FwCA_ImageKey_FwKey (0x0u) 413 #define kNBOOT_RootKeyUsage_DebugCA (0x1u) 414 #define kNBOOT_RootKeyUsage_ImageCA_FwCA (0x2u) 415 #define kNBOOT_RootKeyUsage_DebugCA_ImageCA_FwCA (0x3u) 416 #define kNBOOT_RootKeyUsage_ImageKey_FwKey (0x4u) 417 #define kNBOOT_RootKeyUsage_ImageKey (0x5u) 418 #define kNBOOT_RootKeyUsage_FwKey (0x6u) 419 #define kNBOOT_RootKeyUsage_Unused (0x7u) 420 /* any other value means the root key is not valid (treat as if revoked) */ 421 typedef uint32_t nboot_root_key_usage_t; 422 423 /*! @brief Enumeration for SoC Lifecycle. */ 424 #define nboot_lc_nxpBlank (0xFFFF0000u) 425 #define nboot_lc_nxpDevNonSec (0xFF0200FDu) 426 #define nboot_lc_nxpDevSec (0xFF0100FEu) 427 #define nboot_lc_nxpProvisioned (0xFFFE0001u) 428 #define nboot_lc_oemOpen (0xFFFC0003u) 429 #define nboot_lc_oemSecureWorld (0xFFF80007u) 430 #define nboot_lc_oemClosed (0xFFF0000Fu) 431 #define nboot_lc_oemLocked (0xFF3000CFu) 432 #define nboot_lc_oemFieldReturn (0xFFE0001Fu) 433 #define nboot_lc_nxpFieldReturn (0xFFC0003Fu) 434 #define nboot_lc_shredded (0xFF0000FFu) 435 typedef uint32_t nboot_soc_lifecycle_t; 436 437 /*! 438 * @brief NBOOT type specifying the elliptic curve to be used 439 * 440 * This type defines the elliptic curve type and length 441 * 442 */ 443 #define kNBOOT_RootKey_Ecdsa_P256 (0x0000FE01u) 444 #define kNBOOT_RootKey_Ecdsa_P384 (0x0000FD02u) 445 typedef uint32_t nboot_root_key_type_and_length_t; 446 447 /*! 448 * @brief NBOOT type for the root of trust parameters 449 * 450 * This type defines the NBOOT root of trust parameters 451 * 452 */ 453 #define kNBOOT_SocRkh_Size_Words_P384 (12u) 454 #define kNBOOT_SocRkh_Size_Words_P256 (8u) 455 typedef struct _nboot_rot_auth_parms 456 { 457 /* trusted information originated from CFPA */ 458 nboot_root_key_revocation_t soc_rootKeyRevocation[NBOOT_ROOT_CERT_COUNT]; /*!< Provided by caller based on NVM information in CFPA: ROTKH_REVOKE */ 459 uint32_t soc_imageKeyRevocation; /*!< Provided by caller based on NVM information in CFPA: IMAGE_KEY_REVOKE */ 460 461 /* trusted information originated from CMPA */ 462 uint32_t soc_rkh[kNBOOT_SocRkh_Size_Words_P384]; /*!< Provided by caller based on NVM information in CMPA: ROTKH (hash of hashes) */ 463 /*!< In case of kNBOOT_RootKey_Ecdsa_P384, sock_rkh[0..11] are used */ 464 /*!< In case of kNBOOT_RootKey_Ecdsa_P256, sock_rkh[0..7] are used */ 465 466 uint32_t soc_numberOfRootKeys; /* unsigned int, between minimum = 1 and maximum = 4; */ 467 nboot_root_key_usage_t soc_rootKeyUsage[NBOOT_ROOT_CERT_COUNT]; /* CMPA */ 468 nboot_root_key_type_and_length_t soc_rootKeyTypeAndLength; /* static selection between ECDSA P-256 or ECDSA P-384 based root keys */ 469 470 /* trusted information originated from OTP fuses */ 471 nboot_soc_lifecycle_t soc_lifecycle; 472 } nboot_rot_auth_parms_t; 473 474 /*! @brief Data structure holding input arguments to POR secure boot (authentication) algorithm. Shall be read from SoC trusted NVM or SoC fuses. */ 475 typedef struct _nboot_img_auth_ecdsa_parms 476 { 477 /* trusted information originated from CFPA and NMPA */ 478 nboot_rot_auth_parms_t soc_RoTNVM; 479 480 uint32_t soc_trustedFirmwareVersion; /*!< Provided by caller based on NVM information in CFPA: Secure_FW_Version */ 481 } nboot_img_auth_ecdsa_parms_t; 482 483 /*! 484 * @brief manifest loading parameters 485 * 486 * This type defines the NBOOT SB3.1 manifest loading parameters 487 * 488 */typedef struct _nboot_sb3_load_manifest_parms 489 { 490 nboot_rot_auth_parms_t soc_RoTNVM; /*! trusted information originated from CFPA and NMPA */ 491 uint32_t soc_trustedFirmwareVersion; /*!< Provided by caller based on NVM information in CFPA: Secure_FW_Version */ 492 uint8_t pckBlob[48]; /*! CSSv2 protected blob with Part Common Key (PCK) */ 493 } nboot_sb3_load_manifest_parms_t; 494 495 /*! @brief Data structure holding input arguments for CMAC authentication */ 496 typedef struct _nboot_cmac_authenticate_parms 497 { 498 uint32_t expectedMAC[4]; /*!< expected MAC result */ 499 } nboot_cmac_authenticate_parms_t; 500 501 typedef struct 502 { 503 romapi_status_t (*rng_generate_random)(uint8_t *output, size_t outputByteLen); 504 nboot_status_t (*context_init)(nboot_context_t *context); 505 nboot_status_t (*context_deinit)(nboot_context_t *context); 506 nboot_status_protected_t (*sb3_load_manifest)(nboot_context_t *context, 507 uint32_t *manifest, 508 nboot_sb3_load_manifest_parms_t *parms); 509 nboot_status_protected_t (*sb3_load_block)(nboot_context_t *context, 510 uint32_t *block); 511 nboot_status_protected_t (*img_authenticate_ecdsa)(nboot_context_t *context, 512 uint8_t imageStartAddress[], 513 nboot_bool_t *isSignatureVerified, 514 nboot_img_auth_ecdsa_parms_t *parms); 515 } nboot_interface_t; 516 517 518 /******************************************************************************* 519 * API 520 ******************************************************************************/ 521 522 #if defined(__cplusplus) 523 extern "C" { 524 #endif 525 526 /* NBOOT ROM API function */ 527 /* Specifically designed to be used in both secure and non-secure devices */ 528 /*! 529 * @brief Returns random number 530 * 531 * This function returns random number with specified length 532 * 533 * @param output [in] Pointer to random number 534 * @param outputByteLen [in] length of generated random number in bytes 535 * Length has to be in range <1, 2^16> 536 * 537 * @retval kStatus_NBOOT_InvalidArgument Invalid input parameters (Input poiters points to NULL or invalid length) 538 * @retval kStatus_NBOOT_Success Operation successfully finished 539 * @retval kStatus_NBOOT_Fail Error occured during operation 540 * 541 */ 542 romapi_status_t romapi_rng_generate_random(uint8_t *output, size_t outputByteLen); 543 544 /*! 545 * @brief Initialize nboot context data struct 546 * @param context [in] Nboot context 547 * @retval kStatus_NBOOT_Success Operation successfully finished 548 * @retval kStatus_NBOOT_Fail Error occured during operation 549 */ 550 nboot_status_t nboot_context_init(nboot_context_t *context); 551 552 /*! 553 * @brief Deinitialize nboot context data struct 554 * @param context [in] Nboot context 555 * @retval kStatus_NBOOT_Success Operation successfully finished 556 * @retval kStatus_NBOOT_Fail Error occured during operation 557 */ 558 nboot_status_t nboot_context_deinit(nboot_context_t *context); 559 560 /*! 561 * @brief Verify NBOOT SB3.1 manifest (header message) 562 * 563 * This function verifies the NBOOT SB3.1 manifest, initializes the context and loads keys into the 564 * CSS key store so that they can be used by nboot_sb3_load_block function 565 * The NBOOT context has to be initialized by the function nboot_key_store_init before calling this function. 566 * 567 * @param context [in] NBOOT context data struct. 568 * @param manifest [in] pointer to the input manifest buffer 569 * @param params [in] additional input parameters; refer to nboot_sb3_load_manifest_parms_t for details 570 * @return A code-flow protected error code (see @ref nxpCsslFlowProtection) 571 * @retval kStatus_NBOOT_Success Returned when the operation completed successfully 572 * @retval kStatus_NBOOT_Fail Returned in case of error. 573 */ 574 nboot_status_protected_t nboot_sb3_load_manifest( nboot_context_t *context, uint32_t *manifest, 575 nboot_sb3_load_manifest_parms_t *parms); 576 577 /*! 578 * @brief Verify NBOOT SB3.1 block 579 * 580 * This function verifies and decrypts an NBOOT SB3.1 block. Decryption is performed in-place. 581 * The NBOOT context has to be initialized by the function nboot_key_store_init before calling this function. 582 * To be more resistant against SPA, it is recommended that block is word aligned. 583 * 584 * @param context [in] NBOOT context data struct. 585 * @param block [in] pointer to the input block 586 * @return A code-flow protected error code (see @ref nxpCsslFlowProtection) 587 * @retval kStatus_NBOOT_Success Returned when the operation completed successfully 588 * @retval kStatus_NBOOT_Fail Returned in case of error. 589 */ 590 nboot_status_protected_t nboot_sb3_load_block(nboot_context_t *context, uint32_t *block ); 591 592 593 /*! 594 * @brief Secure boot image authentication 595 * 596 * This function authenticates image with asymmetric cryptography. 597 * !NOTE! BootROM shall link this function to hidden ROM region !NOTE! 598 * 599 * @param context NBOOT context data struct (work area). 600 * @param imageStartAddress Pointer to start of the image in memory. 601 * @param isSignatureVerified Pointer to memory holding function call result. 602 * After the function returns, the value will be set to kNBOOT_TRUE when the image is authentic. 603 * Any other value means the authentication does not pass. 604 * @param parms Pointer to a data structure in trusted memory, holding input parameters for the algorithm. 605 * The data structure shall be correctly filled before the function call. 606 * @retval kStatus_NBOOT_Success Returned when the image is authentic. 607 * @retval kStatus_NBOOT_Fail Returned in all other cases. Doesn't always mean invalid image, 608 * it could also mean transient error caused by short time environmental conditions. 609 */ 610 nboot_status_protected_t nboot_img_authenticate_ecdsa(nboot_context_t *context, 611 uint8_t imageStartAddress[], 612 nboot_bool_t *isSignatureVerified, 613 nboot_img_auth_ecdsa_parms_t *parms); 614 615 #endif /* _FSL_ROMAPI_NBOOT_H_ */ 616
