image.h

Go to the documentation of this file.

 
#ifndef _IMAGE_H
#define _IMAGE_H
 
// Dependencies
#include "boot_config.h"
#include "compiler_port.h"
#include "core/cboot_error.h"
#include "image_format.h"
#include "core/crypto.h"
#include "memory/memory.h"
#include "core/verify.h"
 
/*
 * CycloneBOOT Open is licensed under GPL version 2. In particular:
 *
 * - If you link your program to CycloneBOOT Open, the result is a derivative
 *   work that can only be distributed under the same GPL license terms.
 *
 * - If additions or changes to CycloneBOOT Open are made, the result is a
 *   derivative work that can only be distributed under the same license terms.
 *
 * - The GPL license requires that you make the source code available to
 *   whoever you make the binary available to.
 *
 * - If you sell or distribute a hardware product that runs CycloneBOOT Open,
 *   the GPL license requires you to provide public and full access to all
 *   source code on a nondiscriminatory basis.
 *
 * If you fully understand and accept the terms of the GPL license, then edit
 * the os_port_config.h header and add the following directive:
 *
 * #define GPL_LICENSE_TERMS_ACCEPTED
 */
 
#ifndef GPL_LICENSE_TERMS_ACCEPTED
   #error Before compiling CycloneBOOT Open, you must accept the terms of the GPL license
#endif
 
// Image input encryption support
#ifndef IMAGE_INPUT_ENCRYPTED
#define IMAGE_INPUT_ENCRYPTED DISABLED
#elif (IMAGE_INPUT_ENCRYPTED != ENABLED && IMAGE_INPUT_ENCRYPTED != DISABLED)
#error IMAGE_INPUT_ENCRYPTED parameter is not valid!
#endif
 
// Image output encryption support (for encrypted external memory if needed)
#ifndef IMAGE_OUTPUT_ENCRYPTED
#define IMAGE_OUTPUT_ENCRYPTED DISABLED
#elif (IMAGE_OUTPUT_ENCRYPTED != ENABLED && IMAGE_OUTPUT_ENCRYPTED != DISABLED)
#error IMAGE_OUTPUT_ENCRYPTED parameter is not valid!
#endif
 
// Acceptable input or output image encryption support
#if (((IMAGE_OUTPUT_ENCRYPTED == ENABLED) || (IMAGE_INPUT_ENCRYPTED == ENABLED)) &&               \
   (CIPHER_SUPPORT == DISABLED))
#error CIPHER_SUPPORT MUST be ENABLED if IMAGE_INPUT_ENCRYPTED or IMAGE_OUTPUT_ENCRYPTED is enabled!
#endif
 
// Add image encryption related dependencies
#if (CIPHER_SUPPORT == ENABLED) &&                                                                 \
   ((IMAGE_INPUT_ENCRYPTED == ENABLED) || (IMAGE_OUTPUT_ENCRYPTED == ENABLED))
#include "security/cipher.h"
#endif
 
// Maximum image check data size
#define IMAGE_MAX_CHECK_DATA_SIZE 512
 
typedef enum
{
   IMAGE_STATE_IDLE,
   IMAGE_STATE_RECV_APP_HEADER,
   IMAGE_STATE_RECV_APP_DATA,
   IMAGE_STATE_RECV_APP_CHECK,
   IMAGE_STATE_VALIDATE_APP,
   IMAGE_STATE_APP_REBOOT,
   IMAGE_STATE_WRITE_APP_INIT,
   IMAGE_STATE_WRITE_APP_HEADER,
   IMAGE_STATE_WRITE_APP_DATA,
   IMAGE_STATE_WRITE_APP_CHECK,
   IMAGE_STATE_WRITE_APP_END
} ImageState;
 
typedef enum
{
   IMAGE_VERSION_EQUAL,
   IMAGE_VERSION_SUPERIOR,
   IMAGE_VERSION_INFERIOR
} ImageVersionComparisonFlag;
 
// Image Header Major version
#define IMAGE_HEADER_VERSION_MAJOR 1
// Image Header Minor version
#define IMAGE_HEADER_VERSION_MINOR 3
// Image Header Revision number
#define IMAGE_HEADER_VERSION_PATCH 0
 
 
// Image Header version (always computed from the above)
#define IMAGE_HEADER_VERSION                                                   \
        (uint32_t)(((IMAGE_HEADER_VERSION_MAJOR & 0xFF) << 16) |                 \
        ((IMAGE_HEADER_VERSION_MINOR & 0xFF) << 8) | (IMAGE_HEADER_VERSION_PATCH & 0xFF))
 
// Helper macros to extract version components
#define IMAGE_HEADER_VERSION_GET_MAJOR(version) (((version) >> 16) & 0xFF)
#define IMAGE_HEADER_VERSION_GET_MINOR(version) (((version) >> 8) & 0xFF)
#define IMAGE_HEADER_VERSION_GET_PATCH(version) ((version) & 0xFF)
 
// ImageVersion + ImageHeader layout
 
typedef struct
{
   uint8_t buffer[128];  
   uint8_t *bufferPos;   
   size_t bufferLen;     
 
   Slot *activeSlot;  
 
   uint32_t newImageIdx;      
   uint32_t newBootImageIdx;  
 
   uint32_t firmwareAddr;  
   size_t firmwareLength;  
   uint32_t pos;           
   size_t written;         
 
   ImageState state;
 
#if ((CIPHER_SUPPORT == ENABLED) &&                                                                \
   ((IMAGE_INPUT_ENCRYPTED == ENABLED) || (IMAGE_OUTPUT_ENCRYPTED == ENABLED)))
   CipherEngine cipherEngine;  
   bool_t ivRetrieved;
   uint32_t magicNumberCrc;
   bool_t magicNumberCrcRetrieved;
#endif
 
   VerifyContext verifyContext;  
 
   uint8_t checkData[IMAGE_MAX_CHECK_DATA_SIZE];  
   uint8_t *checkDataPos;                         
   size_t checkDataLen;   
   size_t checkDataSize;  
 
} Image;
 
typedef bool_t (*ImageAntiRollbackCallback)(ImageVersion currentAppVersion,
   ImageVersion updateAppVersion);
 
typedef struct
{
   Image inputImage;   
   Image outputImage;  
 
   ImageVersion currentAppVersion;                     
   ImageVersion currentBootVersion;                    
   ImageAntiRollbackCallback imgAntiRollbackCallback;  
 
   Memory *memories;  
} ImageProcessContext;
 
// C++ guard
#ifdef __cplusplus
extern "C"
{
#endif
 
// CycloneBOOT Image related functions
bool_t imageSafeAdd32(uint32_t a, uint32_t b, uint32_t *sum);
bool_t imageFitsSlot(const ImageHeader *header, size_t slotSize);
bool_t imageIsBootImage(const ImageHeader *header);
cboot_error_t imageCheckHeader(ImageHeader *header);
cboot_error_t imageGetHeader(uint8_t *buffer, size_t bufferLen, ImageHeader **header);
cboot_error_t imageComputeHeaderCrc(ImageHeader *header);
cboot_error_t imageCheckIntegrity(Image *image);
 
// C++ guard
#ifdef __cplusplus
}
#endif
#endif