Release v1.2.0

Author: firmwareguru

Include/stm32_secure_patching_bootloader_interface_v1.1.0.h renamed to Include/stm32_secure_patching_bootloader_interface_v1.2.0.h

@@ -5,7 +5,7 @@
 ******************************************************************************
 */
 /*
- * Copyright (c) 2021 Firmware Modules Inc.
+ * Copyright (c) 2021-2022 Firmware Modules Inc.
  *
  * Permission is hereby granted, free of charge, to any person obtaining a copy
  * of this software and associated documentation files(the "Software"), to deal
@@ -51,34 +51,53 @@ typedef enum
 } SE_StatusTypeDef;
 
 /*!
-* Provides services for applications to update firmware in accordance with
-* the Firmware Modules' Application Management and Deployment Model.
-*
-* The application (APP) and manufacturing test application (MTA) sections in
-* the target non-volatile storage may be updated by presenting an update firmware
-* image that was generated with FM_Release.  The Update module takes care of
-* choosing the correct APP section (APP1 or APP2) so as to support over-the-air
-* streaming firmware updating that is highly tolerant to link or device failure -
+* Provides services to access bootloader and application versions, perform
+* in-application firmware updates and access the user-provisioned OTP secure data area.
+*
+* The patching engine is the core of the stm32-secure-patching-bootloader firmware
+* update system.  It supports over-the-air streaming in-application firmware updating 
+* that is highly tolerant to link or device failure - 
 * the target device's running application remains safe at all times during this
-* process.
-*
-* Update APIs will NOT update firmware to older versions.  If an older version (i.e. a 'downgrade')
-* is required, the changes must be reverted/implemented then built with a new version number.
-* The Update and AMDM system uses only the version number to determine which application
-* to boot and which application to overwrite when updating.
-*
-* The Update module does not maintain its own RAM buffer but rather utilizes
-* the buffers provided by existing packet transport infrastructure.  The only
-* requirement on these buffers is that the *first* buffer provided must contain
-* at least {@link #getMinUpdateImageDataLen} bytes.  This value is platform
-* dependent, therefore transport buffer sizing must take this value into account as well.
-* The first buffer must contain enough bytes to verify that a firmware image is
-* indeed being supplied to the update engine.  The actual firmware image length is
-* extracted from the content of the first buffer supplied to {@link #data}.
+* process thanks to the dual slot architecture.
+* 
+* Patching engine APIs (SE_PATCH_) are designed to process Secure Firmware Binary (.sfb)
+* or Secure Firmware Binary Patch (.sfbp) files generated by the
+* stm32-secure-patching-bootloader build system.  The user is required to pass the
+* file binary data in arbitrarily sized chunks through the Data() API.
+* 
+* Full-image .sfb files contain the entire new firmware update image and therefore
+* updates can be performed to any available newer version.
+* Patch files .sfbp, on the other hand, only contain the differences between the
+* current version on the device and the new version.  Consequently, patch files
+* only work if the required "from" version already exists on the device with a
+* fully matching SHA256 digest. Attempting an update with an incorrect patch file
+* has no effect on the system or running application - the patch file is immediately rejected
+* due to "from" version or SHA256 mismatch (fields digitally signed in the file header).
+* The choice of using full or patch file update images depends
+* on delivery method bandwidth constraints and how much attention is paid
+* to the firmware release and delivery process in your organization.
+*
+* The patching engine will NOT update firmware to older versions (security feature).
+* If an older version (i.e. a 'downgrade') is required, the changes must be 
+* reverted/implemented then built with a new version number.
+*
+* The patching engine utilizes the buffers provided by the caller of the Data() API. 
+* There are no requirements on these buffers - they can contain as little as 1 byte 
+* of .sfb or .sfbp file data per invocation.
+* 
+* The system employs multiple protections to ensure it is virtually impossible to
+* inject wrong or malformed firmware update binary data and cause fault or failure in the
+* system.  Digital signatures with SHA256 integrity checking ensure correctness of binary data.
 *
 * @a(Security Policies)
-* It is strongly advised to use a secure transport for data (for both commands and firmware images)
-* provided over the air to the APIs in this module.
+* Firmware images are protected from tampering (digitally signed) and from IP theft
+* (encrypted). The methods selected to transport the firmware update images (.sfb, .sfbp)
+* are not required to be secured and can be user-distributed (e.g. from a public web page).
+* Chip-level readout protection (RDP level 2) option byte is recommended to be 
+* programmed for production devices to protect the digital signature public key (ECDSA) and
+* the decryption private key (AES).
+* Production versions of the stm32-secure-patching-bootloader enforce chip-level readout
+* protection (RDP level 2) at each startup to help protect against possible physical attack vectors.
 *
 * @a(Thread Safety)
 * The APIs in this module are NOT thread-safe
@@ -112,6 +131,11 @@ typedef enum
 * @value(StatusCode_INVALID_ORDER) Supplied data with incorrect order for the current state
 * @value(StatusCode_TOO_FEW_BYTES) Supplied first data packet with less than minimum required bytes
 * @value(StatusCode_PARSER_ERROR) Update container format parser has encountered an unrecoverable error in the byte stream
+* @value(StatusCode_DECRYPTION_ERROR) Update container format stream decryption has failed
+* @value(StatusCode_INSTALL_ERROR) Error finalizing the newly written firmware in download slot (automatically or through SE_PATCH_InstallAtNextReset)
+* @value(StatusCode_FLASH_ERROR) Flash (possibly external) initialization error
+* @value(StatusCode_FLASH_SEGMENT_ERROR) Error initializing the SEGMENT read layer for external flash MultiSegment feature
+* @value(StatusCode_FLASH_CIPHER_ERROR) Error initializing the CIPHER write layer for external flash MultiSegment feature
 */
 typedef enum
 {
@@ -146,9 +170,9 @@ typedef enum
 
 
 /*!
- * High-level AMDM image types.
+ * High-level patching engine image types.
  *
- * These are the types of firmware images that may be presented to the Update module.
+ * These are the types of firmware images that may be presented to the patching engine.
  */
 typedef enum
 {
@@ -175,7 +199,7 @@ typedef enum
 /*!
 * Update start setup data structure.
 *
-* @field(type) Target update location of firmware image presented to Update module.
+* @field(type) Target update location of firmware image presented to patching engine.
 *              This field may be set if known, or may be omitted (set to NONE) to use the firmware update image's
 *              embedded type determined on-the-fly.
 * @field(rebootDelay) Specify the reboot delay that is to occur after a completed firmware update.
@@ -286,6 +310,7 @@ SE_ErrorStatus SE_PATCH_Init(SE_PATCH_Status* p_PatchStatus, const SE_PATCH_Star
 
 /*!
 * Supply a portion of a stream of data to the firmware patching engine.
+* Accepts byte streams from .sfb or .sfbp files.
 *
 * This function blocks until the operation is completed which may consist of one or both of:
 * @p(blist)
@@ -294,17 +319,18 @@ SE_ErrorStatus SE_PATCH_Init(SE_PATCH_Status* p_PatchStatus, const SE_PATCH_Star
 * @p
 *
 * No action is taken against the non-volatile storage unless the provided
-* data was verified to contain the start of a valid firmware image.
+* data was verified to contain the start of a valid firmware image whose
+* signature verifies correctly by the public signing key embedded in the 
+* on-board stm32-secure-patching-bootloader.  In the case of a patch file (.sfbp)
+* the 'source' firmware's - that is, the firmware already on the device - sha256 tag must also match.
 *
-* There is a requirement for data ordering - the first
-* {@link #getMinUpdateImageDataLen} bytes must be sent first and available as a unit
-* to the `data` function.  These bytes contain enough information for the updater
-* to make a decision on whether to proceed.  All subsequent bytes of the
-* firmware update image must also be delivered in order.
+* There is no requirement on how many bytes can be delivered in each Data invocation:
+* as little as 1 byte can be supplied and there is no upper limit other than the 
+* size of the buffer the application can supply.
 *
 * Additionally, the count of bytes is accumulated until the expected number
 * of bytes is received, at which time the written firmware image will be fully verified.
-* There is no protection against duplicate data packets.
+* Any subsequent bytes will be ignored.
 *
 * @param(status) Supplied structure to be filled in with detailed API result status.
 * @param(data) Pointer to firmware image data buffer
@@ -356,8 +382,8 @@ SE_ErrorStatus SE_PATCH_InstallAtNextReset(SE_PATCH_Status* status);
 * the non-volatile memory can be detected by inspecting the returned status codes:
 *      @p(blist)
 *           - StatusCode_SECTION_ERASE_FAILURE: could not invalidate image.
-*                   if an image was successfully written, upon next reboot it will be
-*                   booted, but only if it verifies successfully by the bootloader
+*                   if an image was successfully written, upon next reboot the bootloader will
+*                   attempt to install it but only if it verifies successfully.
 *                   (otherwise the currently running firmware image is booted again).
 *      @p
 * @param(status) Supplied structure to be filled in with detailed API result status.
@@ -423,6 +449,19 @@ typedef struct
 #define FW_VERSION_PATCH(x) (((uint32_t)(x) >>  0) & 0x000000FF)
 
 SE_ErrorStatus SE_APP_GetActiveFwInfo(SE_StatusTypeDef* peSE_Status, SE_APP_ActiveFwInfo* p_FwInfo);
+
+/* Copy the pre-provisoned secure user data into the provided pointer buffer. 
+ * This is an OTP area inside the bootloader flash area containing a maximum of 128 bytes.
+ */
 SE_ErrorStatus SE_APP_GetSecureUserData(SE_StatusTypeDef* peSE_Status, void* p_Data, uint32_t len);
 
+/* Get the bootloader version as a string in the format "v<major>.<minor>.<patch>" e.g. "v1.2.0"
+ * The buffer is always null-terminated when the function returns.
+ * A user buffer of at least 16 bytes is suggested.  A buffer smaller than the bootloader version string length
+ * will simply contain a truncated null-terminated string.
+ * 
+ * @param p_Data buffer to copy bootloader version string into.
+ * @param len length of provided buffer.
+ */
+SE_ErrorStatus SE_APP_GetBootVer(SE_StatusTypeDef* peSE_Status, char* p_Data, uint32_t len);
 

Libs/B-L072Z-LRWAN1/stm32-secure-patching-bootloader-README_B-L072Z-LRWAN1_v1.1.0.txt renamed to Libs/B-L072Z-LRWAN1/stm32-secure-patching-bootloader-README_B-L072Z-LRWAN1_v1.2.0.txt

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2021 Firmware Modules Inc.
+ * Copyright (c) 2021-2022 Firmware Modules Inc.
  *
  * Permission is hereby granted, free of charge, to any person obtaining a copy
  * of this software and associated documentation files(the "Software"), to deal
@@ -34,4 +34,4 @@ STM32_SECURE_PATCHING_BOOTLOADER_SLOT0_END      = 0x0801EFFF;
 STM32_SECURE_PATCHING_BOOTLOADER_RAM_START      = 0x20001500;
 
 SE_IF_REGION_ROM_START                          = 0x8006E00;
-SE_IF_REGION_ROM_LENGTH                         = 0xB00;
+SE_IF_REGION_ROM_LENGTH                         = 0xC00;

Libs/B-L072Z-LRWAN1/stm32-secure-patching-bootloader-interface-gcc_B-L072Z-LRWAN1_v1.1.0.o renamed to Libs/B-L072Z-LRWAN1/stm32-secure-patching-bootloader-interface-gcc_B-L072Z-LRWAN1_v1.2.0.o

@@ -0,0 +1 @@
+c9aa6f1116174b0bd1d3105ffe6c0513d4b557c1d5014664a008660529e1dcab stm32-secure-patching-bootloader_B-L072Z-LRWAN1_v1.2.0.bin