1 /* 2 * Copyright 2022 NXP 3 * All rights reserved. 4 * 5 * SPDX-License-Identifier: BSD-3-Clause 6 */ 7 #ifndef _FSL_KB_API_H_ 8 #define _FSL_KB_API_H_ 9 10 #include <stdlib.h> 11 #include <stdint.h> 12 #include "fsl_common.h" 13 14 //! @brief Details of the operation to be performed by the ROM. 15 // 16 //! The #kRomAuthenticateImage operation requires the entire signed image to be 17 //! available to the application. 18 typedef enum 19 { 20 kRomAuthenticateImage = 1, //!< Authenticate a signed image. 21 kRomLoadImage = 2, //!< Load SB file. 22 kRomOperationCount = 3, 23 } kb_operation_t; 24 25 //! @brief Memory region definition. 26 typedef struct 27 { 28 uint32_t address; 29 uint32_t length; 30 } kb_region_t; 31 32 //! @brief User-provided options passed into kb_init(). 33 //! 34 //! The @a buffer field is a pointer to memory provided by the caller for use by 35 //! Kboot during execution of the operation. Minimum size is the size of each 36 //! certificate in the chain plus 432 bytes additional per certificate. 37 //! 38 //! The @a profile field is a mask that specifies which features are required in 39 //! the SB file or image being processed. This includes the minimum AES and RSA 40 //! key sizes. See the _kb_security_profile enum for profile mask constants. 41 //! The image being loaded or authenticated must match the profile or an error will 42 //! be returned. 43 //! 44 //! @a minBuildNumber is an optional field that can be used to prevent version 45 //! rollback. The API will check the build number of the image, and if it is less 46 //! than @a minBuildNumber will fail with an error. 47 //! 48 //! @a maxImageLength is used to verify the @a offsetToCertificateBlockHeaderInBytes 49 //! value at the beginning of a signed image. It should be set to the length of 50 //! the SB file. If verifying an image in flash, it can be set to the internal 51 //! flash size or a large number like 0x10000000. 52 //! 53 //! @a userRHK can optionally be used by the user to override the RHK in IFR. If 54 //! @a userRHK is not NULL, it points to a 32-byte array containing the SHA-256 of 55 //! the root certificate's RSA public key. 56 //! 57 //! The @a regions field points to an array of memory regions that the SB file being 58 //! loaded is allowed to access. If regions is NULL, then all memory is 59 //! accessible by the SB file. This feature is required to prevent a malicious 60 //! image from erasing good code or RAM contents while it is being loaded, only 61 //! for us to find that the image is inauthentic when we hit the end of the 62 //! section. 63 //! 64 //! @a overrideSBBootSectionID lets the caller override the default section of the 65 //! SB file that is processed during a #kKbootLoadSB operation. By default, 66 //! the section specified in the firstBootableSectionID field of the SB header 67 //! is loaded. If @a overrideSbBootSectionID is non-zero, then the section with 68 //! the given ID will be loaded instead. 69 //! 70 //! The @a userSBKEK field lets a user provide their own AES-256 key for unwrapping 71 //! keys in an SB file during the #kKbootLoadSB operation. @a userSBKEK should point 72 //! to a 32-byte AES-256 key. If @a userSBKEK is NULL then the IFR SBKEK will be used. 73 //! After kb_init() returns, the caller should zero out the data pointed to by @a 74 //! userSBKEK, as the API will have installed the key in the CAU3. 75 76 typedef struct 77 { 78 uint32_t profile; 79 uint32_t minBuildNumber; 80 uint32_t overrideSBBootSectionID; 81 uint32_t *userSBKEK; 82 uint32_t regionCount; 83 const kb_region_t *regions; 84 } kb_load_sb_t; 85 86 typedef struct 87 { 88 uint32_t profile; 89 uint32_t minBuildNumber; 90 uint32_t maxImageLength; 91 uint32_t *userRHK; 92 } kb_authenticate_t; 93 94 typedef struct 95 { 96 uint32_t version; //!< Should be set to #kKbootApiVersion. 97 uint8_t *buffer; //!< Caller-provided buffer used by Kboot. 98 uint32_t bufferLength; 99 kb_operation_t op; 100 union 101 { 102 //! Settings for #kKbootAuthenticate operation. 103 kb_authenticate_t authenticate; 104 //! Settings for #kKbootLoadSB operation. 105 kb_load_sb_t loadSB; 106 }; 107 } kb_options_t; 108 109 #endif /* _FSL_KB_API_H_ */ 110
