arm_uc_metadata_header_v2.h

00001 // ----------------------------------------------------------------------------
00002 // Copyright 2016-2017 ARM Ltd.
00003 //
00004 // SPDX-License-Identifier: Apache-2.0
00005 //
00006 // Licensed under the Apache License, Version 2.0 (the "License");
00007 // you may not use this file except in compliance with the License.
00008 // You may obtain a copy of the License at
00009 //
00010 //     http://www.apache.org/licenses/LICENSE-2.0
00011 //
00012 // Unless required by applicable law or agreed to in writing, software
00013 // distributed under the License is distributed on an "AS IS" BASIS,
00014 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00015 // See the License for the specific language governing permissions and
00016 // limitations under the License.
00017 // ----------------------------------------------------------------------------
00018 
00019 #ifndef ARM_UC_METADATA_HEADER_V2_H
00020 #define ARM_UC_METADATA_HEADER_V2_H
00021 
00022 #include "update-client-common/arm_uc_types.h"
00023 #include "update-client-common/arm_uc_error.h"
00024 #include "arm_uc_buffer_utilities.h"
00025 
00026 #ifdef __cplusplus
00027 extern "C" {
00028 #endif
00029 
00030 #define ARM_UC_INTERNAL_HEADER_MAGIC_V2   (0x5a51b3d4UL)
00031 #define ARM_UC_INTERNAL_HEADER_VERSION_V2 (2)
00032 
00033 #define ARM_UC_EXTERNAL_HEADER_MAGIC_V2   (0x5a51b3d4UL)
00034 #define ARM_UC_EXTERNAL_HEADER_VERSION_V2 (2)
00035 
00036 #define ARM_UC_INTERNAL_FIRMWARE_VERSION_OFFSET_V2 (8)
00037 #define ARM_UC_INTERNAL_FIRMWARE_SIZE_OFFSET_V2    (16)
00038 #define ARM_UC_INTERNAL_FIRMWARE_HASH_OFFSET_V2    (24)
00039 #define ARM_UC_INTERNAL_CAMPAIGN_OFFSET_V2         (88)
00040 #define ARM_UC_INTERNAL_SIGNATURE_SIZE_OFFSET_V2   (104)
00041 #define ARM_UC_INTERNAL_HEADER_CRC_OFFSET_V2       (108)
00042 
00043 #define ARM_UC_INTERNAL_HEADER_SIZE_V2 (112)
00044 
00045 #define ARM_UC_EXTERNAL_FIRMWARE_VERSION_OFFSET_V2 (8)
00046 #define ARM_UC_EXTERNAL_FIRMWARE_SIZE_OFFSET_V2    (16)
00047 #define ARM_UC_EXTERNAL_FIRMWARE_HASH_OFFSET_V2    (24)
00048 #define ARM_UC_EXTERNAL_PAYLOAD_SIZE_OFFSET_V2     (88)
00049 #define ARM_UC_EXTERNAL_PAYLOAD_HASH_OFFSET_V2     (96)
00050 #define ARM_UC_EXTERNAL_CAMPAIGN_OFFSET_V2         (160)
00051 #define ARM_UC_EXTERNAL_HMAC_OFFSET_V2             (232)
00052 
00053 #define ARM_UC_EXTERNAL_HEADER_SIZE_V2 (296)
00054 
00055 typedef struct _arm_uc_internal_header_t {
00056     /* Metadata-header specific magic code */
00057     uint32_t headerMagic;
00058 
00059     /* Revision number for metadata header. */
00060     uint32_t headerVersion;
00061 
00062     /* Version number accompanying the firmware. Larger numbers imply more
00063        recent and preferred versions. This is used for determining the
00064        selection order when multiple versions are available. For downloaded
00065        firmware the manifest timestamp is used as the firmware version.
00066     */
00067     uint64_t firmwareVersion;
00068 
00069     /* Total space (in bytes) occupied by the firmware BLOB. */
00070     uint64_t firmwareSize;
00071 
00072     /* Firmware hash calculated over the firmware size. Should match the hash
00073        generated by standard command line tools, e.g., shasum on Linux/Mac.
00074     */
00075     uint8_t firmwareHash[ARM_UC_SHA512_SIZE];
00076 
00077     /* The ID for the update campaign that resulted in the firmware update.
00078     */
00079     uint8_t campaign[ARM_UC_GUID_SIZE];
00080 
00081     /* Size of the firmware signature. Must be 0 if no signature is supplied. */
00082     uint32_t firmwareSignatureSize;
00083 
00084     /* Header 32 bit CRC. Calculated over the entire header, including the CRC
00085        field, but with the CRC set to zero.
00086     */
00087     uint32_t headerCRC;
00088 
00089     /* Optional firmware signature. Hashing algorithm should be the same as the
00090        one used for the firmware hash. The firmwareSignatureSize must be set.
00091     */
00092     uint8_t firmwareSignature[0];
00093 } arm_uc_internal_header_t;
00094 
00095 typedef struct _arm_uc_external_header_t {
00096     /* Metadata-header specific magic code */
00097     uint32_t headerMagic;
00098 
00099     /* Revision number for metadata header. */
00100     uint32_t headerVersion;
00101 
00102     /* Version number accompanying the firmware. Larger numbers imply more
00103        recent and preferred versions. This is used for determining the
00104        selection order when multiple versions are available. For downloaded
00105        firmware the manifest timestamp is used as the firmware version.
00106     */
00107     uint64_t firmwareVersion;
00108 
00109     /* Total space (in bytes) occupied by the firmware BLOB. */
00110     uint64_t firmwareSize;
00111 
00112     /* Firmware hash calculated over the firmware size. Should match the hash
00113        generated by standard command line tools, e.g., shasum on Linux/Mac.
00114     */
00115     uint8_t firmwareHash[ARM_UC_SHA512_SIZE];
00116 
00117     /* Total space (in bytes) occupied by the payload BLOB.
00118        The payload is the firmware after some form of transformation like
00119        encryption and/or compression.
00120     */
00121     uint64_t payloadSize;
00122 
00123     /* Payload hash calculated over the payload size. Should match the hash
00124        generated by standard command line tools, e.g., shasum on Linux/Mac.
00125        The payload is the firmware after some form of transformation like
00126        encryption and/or compression.
00127     */
00128     uint8_t payloadHash[ARM_UC_SHA512_SIZE];
00129 
00130     /* The ID for the update campaign that resulted in the firmware update.
00131     */
00132     uint8_t campaign[ARM_UC_GUID_SIZE];
00133 
00134     /* Type of transformation used to turn the payload into the firmware image.
00135        Possible values are:
00136      * * NONE
00137      * * AES128_CTR
00138      * * AES128_CBC
00139      * * AES256_CTR
00140      * * AES256_CBC
00141      */
00142     uint32_t firmwareTransformationMode;
00143 
00144     /* Encrypted firmware encryption key.
00145      * To decrypt the firmware, the bootloader combines the bootloader secret
00146      * and the firmwareKeyDerivationFunctionSeed to create an AES key. It uses
00147      * This AES key to decrypt the firmwareCipherKey. The decrypted
00148      * firmwareCipherKey is the FirmwareKey, which is used with the
00149      * firmwareInitVector to decrypt the firmware.
00150      */
00151     uint8_t firmwareCipherKey[ARM_UC_AES256_KEY_SIZE];
00152 
00153     /* AES Initialization vector. This is a random number used to protect the
00154        encryption algorithm from attack. It must be unique for every firmware.
00155      */
00156     uint8_t firmwareInitVector[ARM_UC_AES_BLOCK_SIZE];
00157 
00158     /* Size of the firmware signature. Must be 0 if no signature is supplied. */
00159     uint32_t firmwareSignatureSize;
00160 
00161     /* Hash based message authentication code for the metadata header. Uses per
00162        device secret as key. Should use same hash algorithm as firmware hash.
00163        The headerHMAC field and firmwareSignature field are not part of the hash.
00164     */
00165     uint8_t headerHMAC[ARM_UC_SHA512_SIZE];
00166 
00167     /* Optional firmware signature. Hashing algorithm should be the same as the
00168        one used for the firmware hash. The firmwareSignatureSize must be set.
00169     */
00170     uint8_t firmwareSignature[0];
00171 } arm_uc_external_header_t;
00172 
00173 /**
00174  * @brief Get a 256 device key.
00175  *
00176  * @param output buffer struct to cotain output device key.
00177                  The size member of the struct will be set on success.
00178  *
00179  * @return ERR_NONE on success, error code on failure.
00180  */
00181 arm_uc_error_t ARM_UC_getDeviceKey256Bit(arm_uc_buffer_t *output);
00182 
00183 /**
00184  * @brief Function to get the device root of trust
00185  * @details The device root of trust should be a 128 bit value. It should never leave the device.
00186  *          It should be unique to the device. It should have enough entropy to avoid contentional
00187  *          entropy attacks. The porter should implement the following device signature to provide
00188  *          device root of trust on different platforms.
00189  *
00190  * @param key_buf buffer to be filled with the device root of trust.
00191  * @param length  length of the buffer provided to make sure no overflow occurs.
00192  *
00193  * @return 0 on success, non-zero on failure.
00194  */
00195 int8_t mbed_cloud_client_get_rot_128bit(uint8_t *key_buf, uint32_t length);
00196 
00197 arm_uc_error_t arm_uc_parse_internal_header_v2(const uint8_t *input,
00198                                                arm_uc_firmware_details_t *output);
00199 
00200 arm_uc_error_t arm_uc_create_internal_header_v2(const arm_uc_firmware_details_t *input,
00201                                                 arm_uc_buffer_t *output);
00202 
00203 arm_uc_error_t arm_uc_parse_external_header_v2(const uint8_t *input,
00204                                                arm_uc_firmware_details_t *output);
00205 
00206 arm_uc_error_t arm_uc_create_external_header_v2(const arm_uc_firmware_details_t *input,
00207                                                 arm_uc_buffer_t *output);
00208 
00209 #ifdef __cplusplus
00210 }
00211 #endif
00212 
00213 #endif // ARM_UC_METADATA_HEADER_V2_H