Toyomasa Watarai / simple-mbed-cloud-client

Important changes to repositories hosted on mbed.com

Mbed hosted mercurial repositories are deprecated and are due to be permanently deleted in July 2026.

To keep a copy of this software download the repository Zip archive or clone locally using Mercurial.

It is also possible to export all your personal repositories from the account settings page.

Dependents:  

mbed-cloud-client/update-client-hub/modules/manifest-manager/update-client-manifest-manager/update-client-manifest-manager.h@0:276e7a263c35, 2018-07-02 (annotated)

Committer:
MACRUM
Date:
Mon Jul 02 06:30:39 2018 +0000
Revision:
0:276e7a263c35
Initial commit

Who changed what in which revision?

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