Simple interface for Mbed Cloud Client
Embed:
(wiki syntax)
Show/hide line numbers
update-client-manifest-manager.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 /** 00020 * @file draft-api.h 00021 * @brief Manifest Manager API 00022 * @details This file specifies the API used to interact with the manifest manager 00023 * # Expected API call pattern 00024 * The update hub should call the API in the following way: 00025 * - The update hub initializes the manifest manager: `manifest_manager_init()` 00026 * - TODO: The manifest manager checks internal consistency of the latest manifest. 00027 * - The udpate hub passes a manifest to the manifest manager: `manifest_manager_insert()` 00028 * - The manifest manager: 00029 * - checks for validity of the manifest and exits with a failure if it is invalid. 00030 * - validates the integrity of the manifest (hash) 00031 * - validates the authenticity of the manifest (signature) 00032 * - checks that the manifest applies to the local hardware 00033 * - reports the Device, Vendor, and Device Class GUIDs to the update hub for validation. 00034 * - searches for a matching dependency placeholder 00035 * - if a match is found, 00036 * - stores the manifest as a dependency 00037 * - otherwise 00038 * - TODO: Validates the timestamp. 00039 * NOTE: Timestamp cannot be validated before this point since it is only validated on root manifests 00040 * - stores the maninfest as a new root manifest 00041 * - stores the firmware URI and hash (HACK: Also embeds the firmware size, inip vector and AES key in the hash) 00042 * - stores a placeholder for each linked manifest 00043 * - stores the manifest timestamp 00044 * - The manifest manager searches for dependency placeholders 00045 * - If there is a placeholder, report it to the hub and exit pending. 00046 * - otherwise, report DONE to the hub. 00047 * - If the update hub receives a manifest request, 00048 * - It obtains that manifest and calls `manifest_manager_insert()` starting this process again. 00049 * - If the update hub receives a DONE report, 00050 * - It initiates a firmware request, using the `ARM_UC_mmFetchFirmwareInfo()` API 00051 * - The manifest manager: 00052 * - finds the most recent root manifest 00053 * - searches for any firmware placeholders 00054 * - reports the firmware to the hub 00055 * - Until the hub receives a DONE report, it 00056 * - extracts the firmware information using `ARM_UC_mmGetFirmwareInfo()` 00057 * - fetches the firmware image 00058 * - installs the firmware image 00059 * - starts the search for the next firmware, using `ARM_UC_mmFetchNextFirmwareInfo()` 00060 */ 00061 #include "update-client-manifest-manager-context.h" 00062 #include "update-client-manifest-manager/update-client-manifest-types.h" 00063 #include "update-client-manifest-manager/arm-pal-kv.h" 00064 #include <stddef.h> 00065 00066 #ifdef __cplusplus 00067 extern "C" { 00068 #endif 00069 00070 extern const size_t arm_uc_mmDynamicContextSize; 00071 /** 00072 * @brief Result codes for the application event handler 00073 * @details These result codes are passed to the event handler. They are used to indicate action required by the calling 00074 * application and status of the manifest manager. 00075 */ 00076 enum arm_uc_mmResultCode { 00077 ARM_UC_MM_RC_ERROR = 0, /**< status: The manifest manager failed during the previous operation. Extract further 00078 * error information using `ARM_UC_mmGetError()` */ 00079 ARM_UC_MM_RC_NONE, ///< action: No action necessary 00080 ARM_UC_MM_RC_NEED_DEP, /**< action: The firmware manager needs the manifest specified by 00081 * `ARM_UC_mmGetCurrentManifestDependency()` in order to keep processing the 00082 * firmware update */ 00083 ARM_UC_MM_RC_NEED_FW, /**< action: The firmware manager needs the firmware specified by 00084 * `ARM_UC_mmGetFirmwareInfo()` in order to keep processing the firmware update */ 00085 ARM_UC_MM_RC_DONE ///< status: The last operation completed successfully 00086 }; 00087 00088 00089 /** 00090 * @brief Initialize module and register event handler. 00091 * @details The event handler is shared among all asynchronous calls. 00092 * 00093 * Walks the most recent manifest tree for validity of the tree and presence of the associated images 00094 * 00095 * @param[in] ctxbuf Context object for the manifest manager 00096 * @param callback Function pointer to event handler. 00097 * @param api Pointer to API structure for the key/value storage 00098 * @return Error code. 00099 */ 00100 arm_uc_error_t ARM_UC_mmInit(arm_uc_mmContext_t** ctxbuf, void (*event_handler)(uint32_t), const arm_pal_key_value_api* api); 00101 00102 /** 00103 * @brief Insert manifest. 00104 * @details Validates and parses manifest. 00105 * Event is generated when call is complete. 00106 * 00107 * @param[in] buffer Struct containing pointer to byte array, maximum length, 00108 * and actual length. 00109 * @param[out] ID Pointer to a manifest handle. This handle will be populated on success. 00110 * @return Error code, indicating parsing errors, validity of the manifest, etc. Error codes are TBD. 00111 */ 00112 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); 00113 00114 /** 00115 * @brief Get manifest firmware information 00116 * @details Fills the manifest_firmware_info_t struct with URL information. 00117 * 00118 * struct manifest_firmware { 00119 * uint32_t size; ///< The size of the firmware in bytes 00120 * arm_uc_buffer_t hash; ///< The hash of the firmware image 00121 * arm_uc_buffer_t uri; ///< The location of the firmware 00122 * arm_uc_buffer_t initVector; ///< AES initialization vector 00123 * arm_uc_buffer_t keyID; ///< Identifier for a locally stored AES key 00124 * arm_uc_buffer_t key; ///< An encrypted AES key 00125 * manifest_guid_t format; ///< The format used for the firmware. This is either an enum when the first 96 bits 00126 * /// are 0. Otherwise, this is a RFC4122 GUID. * / 00127 * arm_uc_buffer_t version; ///< A text representation of the version number. 00128 * }; 00129 * 00130 * 00131 * @param[in] ID Value identifying the manifest. 00132 * @param[out] info Struct containing the URL. 00133 * 00134 * @return Error code. 00135 */ 00136 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); 00137 00138 /** 00139 * @brief Starts extracting firmware information from a tree of manifests 00140 * @details `ARM_UC_mmFetchFirmwareInfo()` begins the process of extracting firmware information in the config store 00141 * This API should only be called once for a root manifest. It always completes asynchronously on success: a return of 00142 *`MFST_ERR_NONE` will be followed by a callback with `ARM_UC_MM_RC_DONE`. Errors may be returned synchronously or 00143 * asynchronously. 00144 * 00145 * The caller should wait for a callback via the function pointer provided in `manifest_manager_init()`. If the event 00146 * provided to the callback is `ARM_UC_MM_RC_NEED_FW`, then a new firmware info block is ready for access via 00147 * `ARM_UC_mmGetFirmwareInfo()`. If the event is `ARM_UC_MM_RC_DONE` then no more firmware info blocks are provided via 00148 * this root manifest. 00149 * 00150 * @param[in] ID a handle for the manifest to search. TODO: The manifest manager currently just selects the latest root 00151 * manifest. 00152 * @return An error code on failure, MFST_ERR_NONE on success, or MFST_ERR_PENDING if the find has not completed. 00153 */ 00154 // arm_uc_error_t ARM_UC_mmFetchFirmwareInfo(arm_uc_manifest_handle_t* ID); 00155 00156 /** 00157 * @brief Continues extracting firmware information from a tree of manifests 00158 * @details `ARM_UC_mmFetchNextFirmwareInfo()` obtains the next firmware information block in a tree of manifests. It 00159 * always completes asynchronously on success: a return of `MFST_ERR_NONE` will be followed by a callback with 00160 * `ARM_UC_MM_RC_DONE`. 00161 * 00162 * The caller should wait for a callback via the function pointer provided in `manifest_manager_init()`. If the event 00163 * provided to the callback is `ARM_UC_MM_RC_NEED_FW`, then a new firmware info block is ready for access via 00164 * `ARM_UC_mmGetFirmwareInfo()`. If the event is `ARM_UC_MM_RC_DONE` then no more firmware info blocks are provided via 00165 * this root manifest. 00166 * 00167 * @return An error code on failure, MFST_ERR_NONE on success, or MFST_ERR_PENDING if the find has not completed. 00168 */ 00169 arm_uc_error_t ARM_UC_mmFetchNextFirmwareInfo(struct manifest_firmware_info_t* info); 00170 00171 /** 00172 * @brief Extract the last error reported to a callback with `ARM_UC_MM_RC_ERROR` 00173 * @details Retrieves the internal error code stored in the manifest manager. When an error occurs in the manifest 00174 * manager, during an asynchronous operation, it is not possible to pass this information directly to the application, 00175 * so it is stored internally for later retrieval and an error event is queued for handling by the application event 00176 * handler. 00177 * 00178 * @return The stored error code. 00179 */ 00180 arm_uc_error_t ARM_UC_mmGetError(void); 00181 00182 /** 00183 * @brief Extracts the current dependency manifest information 00184 * @details When the manifest manager reports `ARM_UC_MM_RC_NEED_DEP` to the application event handler, it stores the 00185 * manifest dependency that induced that request. When the application event handler processes the request, it can 00186 * extract the manifest URI from the manifest manager using this function. 00187 * 00188 * @param[out] uri The buffer where the manifest URI should be stored. 00189 * @return An error code on failure or MFST_ERR_NONE on success. 00190 */ 00191 arm_uc_error_t ARM_UC_mmGetCurrentManifestDependency(arm_uc_buffer_t* uri); 00192 00193 #if ARM_UC_MM_ENABLE_TEST_VECTORS 00194 arm_uc_error_t ARM_UC_mmRegisterTestHook(ARM_UC_mmTestHook_t hook); 00195 #endif 00196 00197 #ifdef __cplusplus 00198 } 00199 #endif
Generated on Tue Jul 12 2022 19:01:38 by 1.7.2