CycloneBOOT 2.6.6
Secure Bootloader for ARM Cortex-M MCU
Loading...
Searching...
No Matches
boot.h
Go to the documentation of this file.
1
31#ifndef _SECOND_STAGE_BOOT_H
32#define _SECOND_STAGE_BOOT_H
33
34// Dependencies
35#include "boot_config.h"
36#include "core/cboot_error.h"
37#include "core/crypto.h"
38#include "core/flash.h"
39#include "core/verify.h"
40
41// default offset
42#ifndef BOOT_OFFSET
43#define BOOT_OFFSET 0x10000
44#endif
45
46// Enable fallback support
47#ifndef BOOT_FALLBACK_SUPPORT
48#define BOOT_FALLBACK_SUPPORT DISABLED
49#elif ((BOOT_FALLBACK_SUPPORT != ENABLED) && (BOOT_FALLBACK_SUPPORT != DISABLED))
50#error BOOT_FALLBACK_SUPPORT parameter is not valid
51#elif ((BOOT_FALLBACK_SUPPORT == DISABLED) && \
52 (BOOT_FALLBACK_AUTO_MODE == ENABLED || BOOT_FALLBACK_MANUAL_MODE == ENABLED))
53#error BOOT_FALLBACK_SUPPORT is DISABLED while BOOT_FALLBACK_XXX_MODE is ENABLED
54#endif
55
56// Fallback on internal memory reads the application, update and backup slots of one memory
57#if (BOOT_FALLBACK_SUPPORT == ENABLED && EXTERNAL_MEMORY_SUPPORT == DISABLED && \
58 NB_MAX_MEMORY_SLOTS < 3)
59#error when BOOT_FALLBACK_SUPPORT is ENABLED on internal memory, NB_MAX_MEMORY_SLOTS must be >= 3
60#endif
61
62#if (BOOT_FALLBACK_AUTO_MODE == ENABLED)
63#if (BOOT_FLAG_SUPPORT == DISABLED && BOOT_COUNTER_SUPPORT == DISABLED)
64#error when BOOT_FALLBACK_AUTO_MODE is ENABLED, also ENABLE BOOT_FLAG_SUPPORT and/or BOOT_COUNTER_SUPPORT
65#endif
66#if (BOOT_COUNTER_SUPPORT == ENABLED && BOOT_COUNTER_MAX_ATTEMPTS <= 0)
67#error invalid counter value (should be > 0)
68#endif
69#endif
70
71#if (BOOT_FALLBACK_AUTO_MODE != ENABLED)
72#if (BOOT_COUNTER_SUPPORT == ENABLED || BOOT_FLAG_SUPPORT == ENABLED)
73#error BOOT_FALLBACK_AUTO_MODE is DISABLED while BOOT_XXX_SUPPORT is ENABLED
74#endif
75#endif
76
77#if (BOOT_FALLBACK_SUPPORT == ENABLED)
78#if (BOOT_FALLBACK_AUTO_MODE == DISABLED && BOOT_FALLBACK_MANUAL_MODE == DISABLED)
79#error BOOT_FALLBACK_SUPPORT is ENABLED BOOT_FALLBACK_XXX_MODE is DISABLED
80#endif
81#endif
82
83// Enable anti-rollback support
84#ifndef BOOT_ANTI_ROLLBACK_SUPPORT
85#define BOOT_ANTI_ROLLBACK_SUPPORT DISABLED
86#elif ((BOOT_ANTI_ROLLBACK_SUPPORT != ENABLED) && (BOOT_ANTI_ROLLBACK_SUPPORT != DISABLED))
87#error BOOT_ANTI_ROLLBACK_SUPPORT parameter is not valid
88#endif
89
90// Enable external memory encryption support
91#ifndef BOOT_EXT_MEM_ENCRYPTION_SUPPORT
92#define BOOT_EXT_MEM_ENCRYPTION_SUPPORT DISABLED
93#elif ((BOOT_EXT_MEM_ENCRYPTION_SUPPORT != ENABLED) && \
94 (BOOT_EXT_MEM_ENCRYPTION_SUPPORT != DISABLED))
95#error BOOT_EXT_MEM_ENCRYPTION_SUPPORT parameter is not valid
96#endif
97
98// ------------------------------
99// Boot Runtime Integrity Check Config
100// ------------------------------
101
102// Default values
103#ifndef BOOT_RUNTIME_INTEGRITY_CHECK_SUPPORT
104#define BOOT_RUNTIME_INTEGRITY_CHECK_SUPPORT DISABLED
105#endif
106
107// Install (footer) integrity algorithm written by bootUpdateApp.
108// This is distinct from runtime integrity check
109#ifndef BOOT_INTEGRITY_CHECK_ALGO
110#define BOOT_INTEGRITY_CHECK_ALGO CRC32_HASH_ALGO
111#endif
112
113// ------------------------------
114// Supported hash algorithms
115// ------------------------------
116#define HASH_ALGO_CRC32 CRC32_HASH_ALGO
117#define HASH_ALGO_SHA1 SHA1_HASH_ALGO
118#define HASH_ALGO_SHA224 SHA224_HASH_ALGO
119#define HASH_ALGO_SHA256 SHA256_HASH_ALGO
120#define HASH_ALGO_SHA384 SHA384_HASH_ALGO
121#define HASH_ALGO_SHA512 SHA512_HASH_ALGO
122
123// ------------------------------
124// Validation
125// ------------------------------
126#if (BOOT_RUNTIME_INTEGRITY_CHECK_SUPPORT != ENABLED) && (BOOT_RUNTIME_INTEGRITY_CHECK_SUPPORT != DISABLED)
127#error "BOOT_RUNTIME_INTEGRITY_CHECK_SUPPORT must be ENABLED or DISABLED"
128#endif
129
130// ------------------------------
131// Boot Runtime Signature Check Config
132// ------------------------------
133
134// Default values
135#ifndef BOOT_RUNTIME_SIGNATURE_CHECK_SUPPORT
136#define BOOT_RUNTIME_SIGNATURE_CHECK_SUPPORT DISABLED
137#endif
138
139// ------------------------------
140// Validation
141// ------------------------------
142#if (BOOT_RUNTIME_SIGNATURE_CHECK_SUPPORT == ENABLED)
143#if defined(BOOT_RUNTIME_SIGNATURE_ECDSA)
144/* ok */
145#elif defined(BOOT_RUNTIME_SIGNATURE_RSA)
146/* ok */
147#else
148 #error "Unknown signature algorithm macro enabled."
149#endif
150
151#if ((BOOT_RUNTIME_SIGNATURE_ECDSA == ENABLED) && (BOOT_RUNTIME_SIGNATURE_RSA == ENABLED))
152#error "BOOT_RUNTIME_SIGNATURE_ECDSA and BOOT_RUNTIME_SIGNATURE_RSA cannot be enabled at the same time"
153#endif
154
155#endif
156
157#if (BOOT_RUNTIME_SIGNATURE_CHECK_SUPPORT != ENABLED) && (BOOT_RUNTIME_SIGNATURE_CHECK_SUPPORT != DISABLED)
158#error "BOOT_RUNTIME_SIGNATURE_CHECK_SUPPORT must be ENABLED or DISABLED"
159#endif
160// An image carries a single embedded runtime verification field
161#if (BOOT_RUNTIME_INTEGRITY_CHECK_SUPPORT == ENABLED) && \
162 (BOOT_RUNTIME_SIGNATURE_CHECK_SUPPORT == ENABLED)
163#error "Enable at most one of BOOT_RUNTIME_INTEGRITY_CHECK_SUPPORT / BOOT_RUNTIME_SIGNATURE_CHECK_SUPPORT: an image carries a single embedded runtime field."
164#endif
165
166
167// C++ guard
168#ifdef __cplusplus
169extern "C"
170{
171#endif
172
177typedef enum
178{
179 BOOT_STATE_IDLE,
180 BOOT_STATE_RUN_APP,
181 BOOT_STATE_UPDATE_APP,
182 BOOT_STATE_FALLBACK_APP,
183 BOOT_STATE_ERROR
184} BootState;
185
190typedef struct
191{
192#if (BOOT_EXT_MEM_ENCRYPTION_SUPPORT == ENABLED) /* \
193 && (BOOT_FALLBACK_SUPPORT == ENABLED))*/
194 const char_t *psk;
195 size_t pskSize;
196#endif
197#if (BOOT_RUNTIME_SIGNATURE_CHECK_SUPPORT == ENABLED)
198 VerifySettings verifySettings;
199#endif
200 Memory memories[NB_MEMORIES];
201} BootSettings;
202
206typedef struct
207{
208 BootState state;
209 BootSettings settings;
210 Memory memories[NB_MEMORIES];
211#if (BOOT_EXT_MEM_ENCRYPTION_SUPPORT == ENABLED)
212 uint8_t psk[32];
213 size_t pskSize;
214#endif
215 Slot selectedSlot;
216 bool_t busy;
217#if (BOOT_FALLBACK_SUPPORT == ENABLED)
218 bool_t fallbackAttempted;
219#endif
220} BootContext;
221
222// Bootloader related functions
223cboot_error_t bootFsm(BootContext *context);
224void bootGetDefaultSettings(BootSettings *settings);
225cboot_error_t bootInit(BootContext *context, BootSettings *settings);
226cboot_error_t bootCreateBackupSlot(BootContext *context);
227cboot_error_t bootUpdateApp(BootContext *context, Slot *slot);
228
229#if ((defined(__ARMCC_VERSION) && (__ARMCC_VERSION >= 6010050)) || defined(__GNUC__) || \
230 defined(__CC_ARM) || defined(__IAR_SYSTEMS_ICC__) || defined(__TASKING__) || \
231 defined(__CWCC__) || defined(__TI_ARM__))
232void bootInitHook(void);
233void bootIdleStateHook(void);
234void bootNoValidUpdatesHook(void);
235void bootJumpingToApplicationHook(void);
236void bootFallbackPerformedHook(void);
237void bootApplicationUpdatedHook(void);
238void bootHandleFallbackError(void);
239void bootHandleGenericError(void);
240#elif ((defined(_MSC_VER) || defined(_WIN32) || defined(WIN32) || defined(WIN64) || \
241 defined(__unix__)))
242extern void bootInitHook(void);
243extern void bootIdleStateHook(void);
244extern void bootNoValidUpdatesHook(void);
245extern void bootJumpingToApplicationHook(void);
246extern void bootFallbackPerformedHook(void);
247extern void bootApplicationUpdatedHook(void);
248extern void bootHandleFallbackError(void);
249extern void bootHandleGenericError(void);
250#endif
251
252// Extern device MCU related function
253extern uint32_t mcuGetVtorOffset(void);
254extern void mcuSystemReset(void);
255extern void mcuJumpToApplication(uint32_t address);
256
257// C++ guard
258#ifdef __cplusplus
259}
260#endif
261#endif //_SECOND_STAGE_BOOT_H
cboot_error.h
Error codes description.
cboot_error_t
cboot_error_t
Error codes.
Definition cboot_error.h:57
bootFsm
cboot_error_t bootFsm(BootContext *context)
Bootloader Task routine.
Definition boot.c:233
bootInit
cboot_error_t bootInit(BootContext *context, BootSettings *settings)
Initialize the first-stage bootloader context from user settings.
Definition boot.c:131
bootGetDefaultSettings
void bootGetDefaultSettings(BootSettings *settings)
Initialize first-stage bootloader settings with default values.
Definition boot.c:55
flash.h
CycloneBOOT Flash layer.
bootUpdateApp
cboot_error_t bootUpdateApp(BootContext *context, Slot *slot)
Update current application. Basically it decrypt/copy an image from the external flash memory into th...
Definition boot_common.c:647
mcuGetVtorOffset
uint32_t mcuGetVtorOffset(void)
Return mcu vector table offset.
Definition sam_ed_5x_mcu_driver.c:51
mcuJumpToApplication
void mcuJumpToApplication(uint32_t address)
Jump to the application at the given address.
Definition sam_ed_5x_mcu_driver.c:80
mcuSystemReset
void mcuSystemReset(void)
Reset MCU system.
Definition sam_ed_5x_mcu_driver.c:59
BootState
BootState
Bootloader States definition.
Definition boot.h:178
bootJumpingToApplicationHook
__weak_func void bootJumpingToApplicationHook(void)
Pre-jump callback. It is declared weak and may be replaced in the user code space....
Definition boot.c:691
bootApplicationUpdatedHook
__weak_func void bootApplicationUpdatedHook(void)
Application updated callback. It is declared weak and may be replaced in the user code space....
Definition boot.c:676
BootState
BootState
Standalone bootloader states definition.
Definition boot.h:189
BootContext
First-stage bootloader context.
Definition boot.h:136
BootContext::fallbackAttempted
bool_t fallbackAttempted
A fallback already failed during this boot.
Definition boot.h:218
BootContext::pskSize
size_t pskSize
Cipher PSK key size.
Definition boot.h:213
BootContext::state
BootState state
Bootloader state.
Definition boot.h:208
BootContext::settings
BootSettings settings
Bootloader user settings.
Definition boot.h:209
BootSettings
First-stage bootloader user settings.
Definition boot.h:118
BootSettings::pskSize
size_t pskSize
Secondary flash slot cipher key size.
Definition boot.h:195
BootSettings::verifySettings
VerifySettings verifySettings
Runtime verification of the resident image.
Definition boot.h:198
BootSettings::psk
const char_t * psk
Secondary flash slot cipher key.
Definition boot.h:194
Memory
Memory Definition.
Definition memory.h:225
Slot
Slot Type definition.
Definition memory.h:181
VerifySettings
Verification settings.
Definition verify.h:157
verify.h
CycloneBOOT Image data verification module.