Mayank Gupta / Mbed OS pelion-example-frdm

Example

Dependencies:   FXAS21002 FXOS8700Q

simple-mbed-cloud-client/mbed-cloud-client/update-client-hub/modules/manifest-manager/update-client-manifest-manager/update-client-manifest-manager.h@0:11cc2b7889af, 2019-11-19 (annotated)

Committer:
maygup01
Date:
Tue Nov 19 09:49:38 2019 +0000
Revision:
0:11cc2b7889af
Example

Who changed what in which revision?

UserRevisionLine numberNew contents of line
maygup01 0:11cc2b7889af 1 // ----------------------------------------------------------------------------
maygup01 0:11cc2b7889af 2 // Copyright 2016-2017 ARM Ltd.
maygup01 0:11cc2b7889af 3 //
maygup01 0:11cc2b7889af 4 // SPDX-License-Identifier: Apache-2.0
maygup01 0:11cc2b7889af 5 //
maygup01 0:11cc2b7889af 6 // Licensed under the Apache License, Version 2.0 (the "License");
maygup01 0:11cc2b7889af 7 // you may not use this file except in compliance with the License.
maygup01 0:11cc2b7889af 8 // You may obtain a copy of the License at
maygup01 0:11cc2b7889af 9 //
maygup01 0:11cc2b7889af 10 // http://www.apache.org/licenses/LICENSE-2.0
maygup01 0:11cc2b7889af 11 //
maygup01 0:11cc2b7889af 12 // Unless required by applicable law or agreed to in writing, software
maygup01 0:11cc2b7889af 13 // distributed under the License is distributed on an "AS IS" BASIS,
maygup01 0:11cc2b7889af 14 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
maygup01 0:11cc2b7889af 15 // See the License for the specific language governing permissions and
maygup01 0:11cc2b7889af 16 // limitations under the License.
maygup01 0:11cc2b7889af 17 // ----------------------------------------------------------------------------
maygup01 0:11cc2b7889af 18
maygup01 0:11cc2b7889af 19 /**
maygup01 0:11cc2b7889af 20 * @file draft-api.h
maygup01 0:11cc2b7889af 21 * @brief Manifest Manager API
maygup01 0:11cc2b7889af 22 * @details This file specifies the API used to interact with the manifest manager
maygup01 0:11cc2b7889af 23 * # Expected API call pattern
maygup01 0:11cc2b7889af 24 * The update hub should call the API in the following way:
maygup01 0:11cc2b7889af 25 * - The update hub initializes the manifest manager: `manifest_manager_init()`
maygup01 0:11cc2b7889af 26 * - TODO: The manifest manager checks internal consistency of the latest manifest.
maygup01 0:11cc2b7889af 27 * - The udpate hub passes a manifest to the manifest manager: `manifest_manager_insert()`
maygup01 0:11cc2b7889af 28 * - The manifest manager:
maygup01 0:11cc2b7889af 29 * - checks for validity of the manifest and exits with a failure if it is invalid.
maygup01 0:11cc2b7889af 30 * - validates the integrity of the manifest (hash)
maygup01 0:11cc2b7889af 31 * - validates the authenticity of the manifest (signature)
maygup01 0:11cc2b7889af 32 * - checks that the manifest applies to the local hardware
maygup01 0:11cc2b7889af 33 * - reports the Device, Vendor, and Device Class GUIDs to the update hub for validation.
maygup01 0:11cc2b7889af 34 * - searches for a matching dependency placeholder
maygup01 0:11cc2b7889af 35 * - if a match is found,
maygup01 0:11cc2b7889af 36 * - stores the manifest as a dependency
maygup01 0:11cc2b7889af 37 * - otherwise
maygup01 0:11cc2b7889af 38 * - TODO: Validates the timestamp.
maygup01 0:11cc2b7889af 39 * NOTE: Timestamp cannot be validated before this point since it is only validated on root manifests
maygup01 0:11cc2b7889af 40 * - stores the maninfest as a new root manifest
maygup01 0:11cc2b7889af 41 * - stores the firmware URI and hash (HACK: Also embeds the firmware size, inip vector and AES key in the hash)
maygup01 0:11cc2b7889af 42 * - stores a placeholder for each linked manifest
maygup01 0:11cc2b7889af 43 * - stores the manifest timestamp
maygup01 0:11cc2b7889af 44 * - The manifest manager searches for dependency placeholders
maygup01 0:11cc2b7889af 45 * - If there is a placeholder, report it to the hub and exit pending.
maygup01 0:11cc2b7889af 46 * - otherwise, report DONE to the hub.
maygup01 0:11cc2b7889af 47 * - If the update hub receives a manifest request,
maygup01 0:11cc2b7889af 48 * - It obtains that manifest and calls `manifest_manager_insert()` starting this process again.
maygup01 0:11cc2b7889af 49 * - If the update hub receives a DONE report,
maygup01 0:11cc2b7889af 50 * - It initiates a firmware request, using the `ARM_UC_mmFetchFirmwareInfo()` API
maygup01 0:11cc2b7889af 51 * - The manifest manager:
maygup01 0:11cc2b7889af 52 * - finds the most recent root manifest
maygup01 0:11cc2b7889af 53 * - searches for any firmware placeholders
maygup01 0:11cc2b7889af 54 * - reports the firmware to the hub
maygup01 0:11cc2b7889af 55 * - Until the hub receives a DONE report, it
maygup01 0:11cc2b7889af 56 * - extracts the firmware information using `ARM_UC_mmGetFirmwareInfo()`
maygup01 0:11cc2b7889af 57 * - fetches the firmware image
maygup01 0:11cc2b7889af 58 * - installs the firmware image
maygup01 0:11cc2b7889af 59 * - starts the search for the next firmware, using `ARM_UC_mmFetchNextFirmwareInfo()`
maygup01 0:11cc2b7889af 60 */
maygup01 0:11cc2b7889af 61 #include "update-client-manifest-manager-context.h"
maygup01 0:11cc2b7889af 62 #include "update-client-manifest-manager/update-client-manifest-types.h"
maygup01 0:11cc2b7889af 63 #include "update-client-manifest-manager/arm-pal-kv.h"
maygup01 0:11cc2b7889af 64 #include <stddef.h>
maygup01 0:11cc2b7889af 65
maygup01 0:11cc2b7889af 66 #ifdef __cplusplus
maygup01 0:11cc2b7889af 67 extern "C" {
maygup01 0:11cc2b7889af 68 #endif
maygup01 0:11cc2b7889af 69
maygup01 0:11cc2b7889af 70 extern const size_t arm_uc_mmDynamicContextSize;
maygup01 0:11cc2b7889af 71 /**
maygup01 0:11cc2b7889af 72 * @brief Result codes for the application event handler
maygup01 0:11cc2b7889af 73 * @details These result codes are passed to the event handler. They are used to indicate action required by the calling
maygup01 0:11cc2b7889af 74 * application and status of the manifest manager.
maygup01 0:11cc2b7889af 75 */
maygup01 0:11cc2b7889af 76 enum arm_uc_mmResultCode {
maygup01 0:11cc2b7889af 77 ARM_UC_MM_RC_ERROR = 0, /**< status: The manifest manager failed during the previous operation. Extract further
maygup01 0:11cc2b7889af 78 * error information using `ARM_UC_mmGetError()` */
maygup01 0:11cc2b7889af 79 ARM_UC_MM_RC_NONE, ///< action: No action necessary
maygup01 0:11cc2b7889af 80 ARM_UC_MM_RC_NEED_DEP, /**< action: The firmware manager needs the manifest specified by
maygup01 0:11cc2b7889af 81 * `ARM_UC_mmGetCurrentManifestDependency()` in order to keep processing the
maygup01 0:11cc2b7889af 82 * firmware update */
maygup01 0:11cc2b7889af 83 ARM_UC_MM_RC_NEED_FW, /**< action: The firmware manager needs the firmware specified by
maygup01 0:11cc2b7889af 84 * `ARM_UC_mmGetFirmwareInfo()` in order to keep processing the firmware update */
maygup01 0:11cc2b7889af 85 ARM_UC_MM_RC_DONE ///< status: The last operation completed successfully
maygup01 0:11cc2b7889af 86 };
maygup01 0:11cc2b7889af 87
maygup01 0:11cc2b7889af 88
maygup01 0:11cc2b7889af 89 /**
maygup01 0:11cc2b7889af 90 * @brief Initialize module and register event handler.
maygup01 0:11cc2b7889af 91 * @details The event handler is shared among all asynchronous calls.
maygup01 0:11cc2b7889af 92 *
maygup01 0:11cc2b7889af 93 * Walks the most recent manifest tree for validity of the tree and presence of the associated images
maygup01 0:11cc2b7889af 94 *
maygup01 0:11cc2b7889af 95 * @param[in] ctxbuf Context object for the manifest manager
maygup01 0:11cc2b7889af 96 * @param callback Function pointer to event handler.
maygup01 0:11cc2b7889af 97 * @param api Pointer to API structure for the key/value storage
maygup01 0:11cc2b7889af 98 * @return Error code.
maygup01 0:11cc2b7889af 99 */
maygup01 0:11cc2b7889af 100 arm_uc_error_t ARM_UC_mmInit(arm_uc_mmContext_t **ctxbuf, void (*event_handler)(uintptr_t),
maygup01 0:11cc2b7889af 101 const arm_pal_key_value_api *api);
maygup01 0:11cc2b7889af 102
maygup01 0:11cc2b7889af 103 /**
maygup01 0:11cc2b7889af 104 * @brief Insert manifest.
maygup01 0:11cc2b7889af 105 * @details Validates and parses manifest.
maygup01 0:11cc2b7889af 106 * Event is generated when call is complete.
maygup01 0:11cc2b7889af 107 *
maygup01 0:11cc2b7889af 108 * @param[in] buffer Struct containing pointer to byte array, maximum length,
maygup01 0:11cc2b7889af 109 * and actual length.
maygup01 0:11cc2b7889af 110 * @param[out] ID Pointer to a manifest handle. This handle will be populated on success.
maygup01 0:11cc2b7889af 111 * @return Error code, indicating parsing errors, validity of the manifest, etc. Error codes are TBD.
maygup01 0:11cc2b7889af 112 */
maygup01 0:11cc2b7889af 113 arm_uc_error_t ARM_UC_mmInsert(arm_uc_mmContext_t **ctx, arm_uc_buffer_t *buffer, arm_uc_buffer_t *certificateStorage,
maygup01 0:11cc2b7889af 114 arm_uc_manifest_handle_t *ID);
maygup01 0:11cc2b7889af 115
maygup01 0:11cc2b7889af 116 /**
maygup01 0:11cc2b7889af 117 * @brief Get manifest firmware information
maygup01 0:11cc2b7889af 118 * @details Fills the manifest_firmware_info_t struct with URL information.
maygup01 0:11cc2b7889af 119 *
maygup01 0:11cc2b7889af 120 * struct manifest_firmware {
maygup01 0:11cc2b7889af 121 * uint32_t size; ///< The size of the firmware in bytes
maygup01 0:11cc2b7889af 122 * arm_uc_buffer_t hash; ///< The hash of the firmware image
maygup01 0:11cc2b7889af 123 * arm_uc_buffer_t uri; ///< The location of the firmware
maygup01 0:11cc2b7889af 124 * arm_uc_buffer_t initVector; ///< AES initialization vector
maygup01 0:11cc2b7889af 125 * arm_uc_buffer_t keyID; ///< Identifier for a locally stored AES key
maygup01 0:11cc2b7889af 126 * arm_uc_buffer_t key; ///< An encrypted AES key
maygup01 0:11cc2b7889af 127 * manifest_guid_t format; ///< The format used for the firmware. This is either an enum when the first 96 bits
maygup01 0:11cc2b7889af 128 * /// are 0. Otherwise, this is a RFC4122 GUID. * /
maygup01 0:11cc2b7889af 129 * arm_uc_buffer_t version; ///< A text representation of the version number.
maygup01 0:11cc2b7889af 130 * };
maygup01 0:11cc2b7889af 131 *
maygup01 0:11cc2b7889af 132 *
maygup01 0:11cc2b7889af 133 * @param[in] ID Value identifying the manifest.
maygup01 0:11cc2b7889af 134 * @param[out] info Struct containing the URL.
maygup01 0:11cc2b7889af 135 *
maygup01 0:11cc2b7889af 136 * @return Error code.
maygup01 0:11cc2b7889af 137 */
maygup01 0:11cc2b7889af 138 arm_uc_error_t ARM_UC_mmFetchFirmwareInfo(arm_uc_mmContext_t **ctx, struct manifest_firmware_info_t *info,
maygup01 0:11cc2b7889af 139 const arm_uc_manifest_handle_t *ID);
maygup01 0:11cc2b7889af 140
maygup01 0:11cc2b7889af 141 /**
maygup01 0:11cc2b7889af 142 * @brief Starts extracting firmware information from a tree of manifests
maygup01 0:11cc2b7889af 143 * @details `ARM_UC_mmFetchFirmwareInfo()` begins the process of extracting firmware information in the config store
maygup01 0:11cc2b7889af 144 * This API should only be called once for a root manifest. It always completes asynchronously on success: a return of
maygup01 0:11cc2b7889af 145 *`ERR_NONE` will be followed by a callback with `ARM_UC_MM_RC_DONE`. Errors may be returned synchronously or
maygup01 0:11cc2b7889af 146 * asynchronously.
maygup01 0:11cc2b7889af 147 *
maygup01 0:11cc2b7889af 148 * The caller should wait for a callback via the function pointer provided in `manifest_manager_init()`. If the event
maygup01 0:11cc2b7889af 149 * provided to the callback is `ARM_UC_MM_RC_NEED_FW`, then a new firmware info block is ready for access via
maygup01 0:11cc2b7889af 150 * `ARM_UC_mmGetFirmwareInfo()`. If the event is `ARM_UC_MM_RC_DONE` then no more firmware info blocks are provided via
maygup01 0:11cc2b7889af 151 * this root manifest.
maygup01 0:11cc2b7889af 152 *
maygup01 0:11cc2b7889af 153 * @param[in] ID a handle for the manifest to search. TODO: The manifest manager currently just selects the latest root
maygup01 0:11cc2b7889af 154 * manifest.
maygup01 0:11cc2b7889af 155 * @return An error code on failure, ERR_NONE on success, or MFST_ERR_PENDING if the find has not completed.
maygup01 0:11cc2b7889af 156 */
maygup01 0:11cc2b7889af 157 // arm_uc_error_t ARM_UC_mmFetchFirmwareInfo(arm_uc_manifest_handle_t* ID);
maygup01 0:11cc2b7889af 158
maygup01 0:11cc2b7889af 159 /**
maygup01 0:11cc2b7889af 160 * @brief Continues extracting firmware information from a tree of manifests
maygup01 0:11cc2b7889af 161 * @details `ARM_UC_mmFetchNextFirmwareInfo()` obtains the next firmware information block in a tree of manifests. It
maygup01 0:11cc2b7889af 162 * always completes asynchronously on success: a return of `ERR_NONE` will be followed by a callback with
maygup01 0:11cc2b7889af 163 * `ARM_UC_MM_RC_DONE`.
maygup01 0:11cc2b7889af 164 *
maygup01 0:11cc2b7889af 165 * The caller should wait for a callback via the function pointer provided in `manifest_manager_init()`. If the event
maygup01 0:11cc2b7889af 166 * provided to the callback is `ARM_UC_MM_RC_NEED_FW`, then a new firmware info block is ready for access via
maygup01 0:11cc2b7889af 167 * `ARM_UC_mmGetFirmwareInfo()`. If the event is `ARM_UC_MM_RC_DONE` then no more firmware info blocks are provided via
maygup01 0:11cc2b7889af 168 * this root manifest.
maygup01 0:11cc2b7889af 169 *
maygup01 0:11cc2b7889af 170 * @return An error code on failure, ERR_NONE on success, or MFST_ERR_PENDING if the find has not completed.
maygup01 0:11cc2b7889af 171 */
maygup01 0:11cc2b7889af 172 arm_uc_error_t ARM_UC_mmFetchNextFirmwareInfo(struct manifest_firmware_info_t *info);
maygup01 0:11cc2b7889af 173
maygup01 0:11cc2b7889af 174 /**
maygup01 0:11cc2b7889af 175 * @brief Extract the last error reported to a callback with `ARM_UC_MM_RC_ERROR`
maygup01 0:11cc2b7889af 176 * @details Retrieves the internal error code stored in the manifest manager. When an error occurs in the manifest
maygup01 0:11cc2b7889af 177 * manager, during an asynchronous operation, it is not possible to pass this information directly to the application,
maygup01 0:11cc2b7889af 178 * so it is stored internally for later retrieval and an error event is queued for handling by the application event
maygup01 0:11cc2b7889af 179 * handler.
maygup01 0:11cc2b7889af 180 *
maygup01 0:11cc2b7889af 181 * @return The stored error code.
maygup01 0:11cc2b7889af 182 */
maygup01 0:11cc2b7889af 183 arm_uc_error_t ARM_UC_mmGetError(void);
maygup01 0:11cc2b7889af 184
maygup01 0:11cc2b7889af 185 /**
maygup01 0:11cc2b7889af 186 * @brief Extracts the current dependency manifest information
maygup01 0:11cc2b7889af 187 * @details When the manifest manager reports `ARM_UC_MM_RC_NEED_DEP` to the application event handler, it stores the
maygup01 0:11cc2b7889af 188 * manifest dependency that induced that request. When the application event handler processes the request, it can
maygup01 0:11cc2b7889af 189 * extract the manifest URI from the manifest manager using this function.
maygup01 0:11cc2b7889af 190 *
maygup01 0:11cc2b7889af 191 * @param[out] uri The buffer where the manifest URI should be stored.
maygup01 0:11cc2b7889af 192 * @return An error code on failure or ERR_NONE on success.
maygup01 0:11cc2b7889af 193 */
maygup01 0:11cc2b7889af 194 arm_uc_error_t ARM_UC_mmGetCurrentManifestDependency(arm_uc_buffer_t *uri);
maygup01 0:11cc2b7889af 195
maygup01 0:11cc2b7889af 196
maygup01 0:11cc2b7889af 197 int ARM_UC_mmCheckFormatUint32(manifest_guid_t* format, uint32_t expected);
maygup01 0:11cc2b7889af 198
maygup01 0:11cc2b7889af 199 #if ARM_UC_MM_ENABLE_TEST_VECTORS
maygup01 0:11cc2b7889af 200 arm_uc_error_t ARM_UC_mmRegisterTestHook(ARM_UC_mmTestHook_t hook);
maygup01 0:11cc2b7889af 201 #endif
maygup01 0:11cc2b7889af 202
maygup01 0:11cc2b7889af 203 #ifdef __cplusplus
maygup01 0:11cc2b7889af 204 }
maygup01 0:11cc2b7889af 205 #endif