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)(uintptr_t),
00101                              const arm_pal_key_value_api *api);
00102 
00103 /**
00104  * @brief Insert manifest.
00105  * @details Validates and parses manifest.
00106  *          Event is generated when call is complete.
00107  *
00108  * @param[in]  buffer Struct containing pointer to byte array, maximum length,
00109  *               and actual length.
00110  * @param[out] ID Pointer to a manifest handle. This handle will be populated on success.
00111  * @return Error code, indicating parsing errors, validity of the manifest, etc. Error codes are TBD.
00112  */
00113 arm_uc_error_t ARM_UC_mmInsert(arm_uc_mmContext_t **ctx, arm_uc_buffer_t *buffer, arm_uc_buffer_t *certificateStorage,
00114                                arm_uc_manifest_handle_t *ID);
00115 
00116 /**
00117  * @brief Get manifest firmware information
00118  * @details Fills the manifest_firmware_info_t struct with URL information.
00119  *
00120  * struct manifest_firmware {
00121  *     uint32_t        size;       ///< The size of the firmware in bytes
00122  *     arm_uc_buffer_t hash;       ///< The hash of the firmware image
00123  *     arm_uc_buffer_t uri;        ///< The location of the firmware
00124  *     arm_uc_buffer_t initVector; ///< AES initialization vector
00125  *     arm_uc_buffer_t keyID;      ///< Identifier for a locally stored AES key
00126  *     arm_uc_buffer_t key;        ///< An encrypted AES key
00127  *     manifest_guid_t format;     ///< The format used for the firmware. This is either an enum when the first 96 bits
00128  *                                 ///  are 0. Otherwise, this is a RFC4122 GUID. * /
00129  *     arm_uc_buffer_t  version;   ///< A text representation of the version number.
00130  * };
00131  *
00132  *
00133  * @param[in]  ID   Value identifying the manifest.
00134  * @param[out] info Struct containing the URL.
00135  *
00136  * @return Error code.
00137  */
00138 arm_uc_error_t ARM_UC_mmFetchFirmwareInfo(arm_uc_mmContext_t **ctx, struct manifest_firmware_info_t *info,
00139                                           const arm_uc_manifest_handle_t *ID);
00140 
00141 /**
00142  * @brief Starts extracting firmware information from a tree of manifests
00143  * @details `ARM_UC_mmFetchFirmwareInfo()` begins the process of extracting firmware information in the config store
00144  * This API should only be called once for a root manifest. It always completes asynchronously on success: a return of
00145  *`ERR_NONE` will be followed by a callback with `ARM_UC_MM_RC_DONE`. Errors may be returned synchronously or
00146  * asynchronously.
00147  *
00148  * The caller should wait for a callback via the function pointer provided in `manifest_manager_init()`. If the event
00149  * provided to the callback is `ARM_UC_MM_RC_NEED_FW`, then a new firmware info block is ready for access via
00150  * `ARM_UC_mmGetFirmwareInfo()`. If the event is `ARM_UC_MM_RC_DONE` then no more firmware info blocks are provided via
00151  * this root manifest.
00152  *
00153  * @param[in]  ID a handle for the manifest to search. TODO: The manifest manager currently just selects the latest root
00154  *                manifest.
00155  * @return     An error code on failure, ERR_NONE on success, or MFST_ERR_PENDING if the find has not completed.
00156  */
00157 // arm_uc_error_t ARM_UC_mmFetchFirmwareInfo(arm_uc_manifest_handle_t* ID);
00158 
00159 /**
00160  * @brief Continues extracting firmware information from a tree of manifests
00161  * @details `ARM_UC_mmFetchNextFirmwareInfo()` obtains the next firmware information block in a tree of manifests. It
00162  * always completes asynchronously on success: a return of `ERR_NONE` will be followed by a callback with
00163  * `ARM_UC_MM_RC_DONE`.
00164  *
00165  * The caller should wait for a callback via the function pointer provided in `manifest_manager_init()`. If the event
00166  * provided to the callback is `ARM_UC_MM_RC_NEED_FW`, then a new firmware info block is ready for access via
00167  * `ARM_UC_mmGetFirmwareInfo()`. If the event is `ARM_UC_MM_RC_DONE` then no more firmware info blocks are provided via
00168  * this root manifest.
00169  *
00170  * @return     An error code on failure, ERR_NONE on success, or MFST_ERR_PENDING if the find has not completed.
00171  */
00172 arm_uc_error_t ARM_UC_mmFetchNextFirmwareInfo(struct manifest_firmware_info_t *info);
00173 
00174 /**
00175  * @brief Extract the last error reported to a callback with `ARM_UC_MM_RC_ERROR`
00176  * @details Retrieves the internal error code stored in the manifest manager. When an error occurs in the manifest
00177  * manager, during an asynchronous operation, it is not possible to pass this information directly to the application,
00178  * so it is stored internally for later retrieval and an error event is queued for handling by the application event
00179  * handler.
00180  *
00181  * @return The stored error code.
00182  */
00183 arm_uc_error_t ARM_UC_mmGetError(void);
00184 
00185 /**
00186  * @brief Extracts the current dependency manifest information
00187  * @details When the manifest manager reports `ARM_UC_MM_RC_NEED_DEP` to the application event handler, it stores the
00188  * manifest dependency that induced that request. When the application event handler processes the request, it can
00189  * extract the manifest URI from the manifest manager using this function.
00190  *
00191  * @param[out] uri The buffer where the manifest URI should be stored.
00192  * @return     An error code on failure or ERR_NONE on success.
00193  */
00194 arm_uc_error_t ARM_UC_mmGetCurrentManifestDependency(arm_uc_buffer_t *uri);
00195 
00196 
00197 int ARM_UC_mmCheckFormatUint32(manifest_guid_t* format, uint32_t expected);
00198 
00199 #if ARM_UC_MM_ENABLE_TEST_VECTORS
00200 arm_uc_error_t ARM_UC_mmRegisterTestHook(ARM_UC_mmTestHook_t hook);
00201 #endif
00202 
00203 #ifdef __cplusplus
00204 }
00205 #endif