boot.h

Go to the documentation of this file.

 
#ifndef _FIRST_STAGE_BOOT_H
#define _FIRST_STAGE_BOOT_H
 
#include "core/mcu.h"
#include "core/crc32.h"
#include "core/flash.h"
#include "core/cboot_error.h"
#include "image/image.h"
#include "modules/memory/memory.h"
#include "debug.h"
 
#ifndef BOOT_FIRST_STAGE_RUNTIME_INTEGRITY_SUPPORT
#define BOOT_FIRST_STAGE_RUNTIME_INTEGRITY_SUPPORT DISABLED
#endif
 
#if (BOOT_FIRST_STAGE_RUNTIME_INTEGRITY_SUPPORT != ENABLED) &&                                      \
   (BOOT_FIRST_STAGE_RUNTIME_INTEGRITY_SUPPORT != DISABLED)
#error "BOOT_FIRST_STAGE_RUNTIME_INTEGRITY_SUPPORT must be ENABLED or DISABLED"
#endif
 
#ifndef BOOT_FIRST_STAGE_RUNTIME_SIGNATURE_SUPPORT
#define BOOT_FIRST_STAGE_RUNTIME_SIGNATURE_SUPPORT DISABLED
#endif
 
#if (BOOT_FIRST_STAGE_RUNTIME_SIGNATURE_SUPPORT != ENABLED) &&                                      \
   (BOOT_FIRST_STAGE_RUNTIME_SIGNATURE_SUPPORT != DISABLED)
#error "BOOT_FIRST_STAGE_RUNTIME_SIGNATURE_SUPPORT must be ENABLED or DISABLED"
#endif
 
#ifndef BOOT_FIRST_STAGE_RUNTIME_SIGNATURE_ECDSA
#define BOOT_FIRST_STAGE_RUNTIME_SIGNATURE_ECDSA DISABLED
#endif
#ifndef BOOT_FIRST_STAGE_RUNTIME_SIGNATURE_RSA
#define BOOT_FIRST_STAGE_RUNTIME_SIGNATURE_RSA DISABLED
#endif
 
// A candidate embeds EITHER a hash digest OR a signature in the runtime field, never
// both, so the two checks are mutually exclusive.
#if (BOOT_FIRST_STAGE_RUNTIME_INTEGRITY_SUPPORT == ENABLED) &&                                      \
   (BOOT_FIRST_STAGE_RUNTIME_SIGNATURE_SUPPORT == ENABLED)
#error "Enable only one of BOOT_FIRST_STAGE_RUNTIME_INTEGRITY_SUPPORT or _RUNTIME_SIGNATURE_SUPPORT"
#endif
 
// Runtime integrity needs a hash algorithm, for example SHA256_HASH_ALGO
#if (BOOT_FIRST_STAGE_RUNTIME_INTEGRITY_SUPPORT == ENABLED) &&                                      \
   !defined(BOOT_FIRST_STAGE_RUNTIME_INTEGRITY_ALGO)
#error "Define BOOT_FIRST_STAGE_RUNTIME_INTEGRITY_ALGO when BOOT_FIRST_STAGE_RUNTIME_INTEGRITY_SUPPORT is ENABLED"
#endif
 
// When signature support is on, exactly one scheme must be selected.
#if (BOOT_FIRST_STAGE_RUNTIME_SIGNATURE_SUPPORT == ENABLED) &&                                      \
   ((BOOT_FIRST_STAGE_RUNTIME_SIGNATURE_ECDSA == ENABLED) ==                                        \
   (BOOT_FIRST_STAGE_RUNTIME_SIGNATURE_RSA == ENABLED))
#error "Enable exactly one of BOOT_FIRST_STAGE_RUNTIME_SIGNATURE_ECDSA or _RSA"
#endif
 
// The first stage refuses a second-stage candidate whose firmware version is not
// newer than the resident one, mirroring the second stage's own anti-rollback.
#ifndef BOOT_ANTI_ROLLBACK_SUPPORT
#define BOOT_ANTI_ROLLBACK_SUPPORT DISABLED
#elif ((BOOT_ANTI_ROLLBACK_SUPPORT != ENABLED) && (BOOT_ANTI_ROLLBACK_SUPPORT != DISABLED))
#error BOOT_ANTI_ROLLBACK_SUPPORT parameter is not valid
#endif
 
// A candidate staged in external memory is held encrypted, so the first stage
// must decrypt it while installing.
#ifndef BOOT_EXT_MEM_ENCRYPTION_SUPPORT
#define BOOT_EXT_MEM_ENCRYPTION_SUPPORT DISABLED
#elif ((BOOT_EXT_MEM_ENCRYPTION_SUPPORT != ENABLED) &&                                             \
   (BOOT_EXT_MEM_ENCRYPTION_SUPPORT != DISABLED))
#error BOOT_EXT_MEM_ENCRYPTION_SUPPORT parameter is not valid
#endif
 
// Check verified boot settings
 
// Refuse a build that would hand over to an unverified second stage
#if (BOOT_FIRST_STAGE_RUNTIME_INTEGRITY_SUPPORT == DISABLED) &&                                    \
   (BOOT_FIRST_STAGE_RUNTIME_SIGNATURE_SUPPORT == DISABLED) &&                                     \
   !defined(BOOT_FIRST_STAGE_ALLOW_UNVERIFIED_SECOND_STAGE)
#error "The first stage would accept any second stage passing a CRC32 check. Enable \
   BOOT_FIRST_STAGE_RUNTIME_SIGNATURE_SUPPORT (or _INTEGRITY_), or define \
   BOOT_FIRST_STAGE_ALLOW_UNVERIFIED_SECOND_STAGE to accept this."
#endif
 
typedef struct {
   Memory memories[NB_MEMORIES]; //Memories and their slots (driver carried per memory)
   uint32_t self_address;        //Address of the first-stage bootloader's own slot
   uint32_t self_size;           //Size of the first-stage bootloader's own slot
   uint32_t offset;              //Jump offset applied when handing off to the second stage
#if (BOOT_FIRST_STAGE_RUNTIME_SIGNATURE_SUPPORT == ENABLED)
   const char_t *signKey;        //PEM public key used to verify the 2nd-stage candidate signature
   size_t signKeyLen;            //Length of the PEM public key
#endif
#if (BOOT_EXT_MEM_ENCRYPTION_SUPPORT == ENABLED)
   const uint8_t *cipherKey;     //Key decrypting a candidate staged in external memory
   size_t cipherKeyLen;          //Length of the cipher key
#endif
} BootSettings;
 
typedef struct {
   Memory memories[NB_MEMORIES]; //Working copy of the memories/slots
   uint32_t self_address;        //Address of the first-stage bootloader's own slot
   uint32_t self_size;           //Size of the first-stage bootloader's own slot
   uint32_t offset;              //Jump offset applied when handing off to the second stage
   Slot *updateSlot;             //Selected newer second-stage candidate slot (NULL if none)
#if (BOOT_FIRST_STAGE_RUNTIME_SIGNATURE_SUPPORT == ENABLED)
   const char_t *signKey;        //PEM public key used to verify the 2nd-stage candidate signature
   size_t signKeyLen;            //Length of the PEM public key
#endif
#if (BOOT_EXT_MEM_ENCRYPTION_SUPPORT == ENABLED)
   const uint8_t *cipherKey;     //Key decrypting a candidate staged in external memory
   size_t cipherKeyLen;          //Length of the cipher key
#endif
} BootContext;
 
void bootGetDefaultSettings(BootSettings *settings);
cboot_error_t bootInit(BootContext *context, BootSettings *settings);
cboot_error_t bootFsm(BootContext *context);
cboot_error_t getSecondStageBlIndex(BootContext *context, uint32_t *index);
cboot_error_t checkForSecondStageBlUpdate(BootContext *context, uint32_t currentIndex,
   bool_t residentOk, bool_t *updateFound);
cboot_error_t updateSecondStageBl(BootContext *context);
 
// Resolve the active second-stage (BOOT) slot in the primary memory.
Slot *bootGetActiveSlot(BootContext *context);
 
void jumpToSecondStageBl(BootContext *context);
 
#if ((defined(__ARMCC_VERSION) && (__ARMCC_VERSION >= 6010050)) || defined(__GNUC__) ||            \
   defined(__CC_ARM) || defined(__IAR_SYSTEMS_ICC__) || defined(__TASKING__) ||                  \
   defined(__CWCC__) || defined(__TI_ARM__))
void bootHandleError(void);
void bootSecondStageUpdatedHook(void);
void bootJumpingToSecondStageHook(void);
void bootRecoveryHook(void);
#elif ((defined(_MSC_VER) || defined(_WIN32) || defined(WIN32) || defined(WIN64) ||                \
   defined(__unix__)))
extern void bootHandleError(void);
extern void bootSecondStageUpdatedHook(void);
extern void bootJumpingToSecondStageHook(void);
extern void bootRecoveryHook(void);
#endif
 
#endif