Simple interface for Mbed Cloud Client
Embed:
(wiki syntax)
Show/hide line numbers
factory_configurator_client.h
Go to the documentation of this file.
00001 // ---------------------------------------------------------------------------- 00002 // Copyright 2016-2017 ARM Ltd. 00003 // 00004 // Licensed under the Apache License, Version 2.0 (the "License"); 00005 // you may not use this file except in compliance with the License. 00006 // You may obtain a copy of the License at 00007 // 00008 // http://www.apache.org/licenses/LICENSE-2.0 00009 // 00010 // Unless required by applicable law or agreed to in writing, software 00011 // distributed under the License is distributed on an "AS IS" BASIS, 00012 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 00013 // See the License for the specific language governing permissions and 00014 // limitations under the License. 00015 // ---------------------------------------------------------------------------- 00016 00017 #ifndef __FACTORY_CONFIGURATOR_CLIENT_H__ 00018 #define __FACTORY_CONFIGURATOR_CLIENT_H__ 00019 00020 #include <stdlib.h> 00021 #include <inttypes.h> 00022 #include "fcc_status.h" 00023 #include "fcc_output_info_handler.h" 00024 00025 #ifdef __cplusplus 00026 extern "C" { 00027 #endif 00028 00029 /** 00030 * @file factory_configurator_client.h 00031 * \brief factory configurator client APIs. 00032 */ 00033 00034 /* === Initialization and Finalization === */ 00035 00036 /** Initiates the FCC module. Must be called before any other fcc's APIs. Otherwise relevant error will be returned. 00037 * 00038 * @returns 00039 * FCC_STATUS_SUCCESS in case of success or one of the `::fcc_status_e` errors otherwise. 00040 */ 00041 fcc_status_e fcc_init(void); 00042 00043 00044 /** Finalizes the FCC module. 00045 * Finalizes and frees file storage resources. 00046 * 00047 * @returns 00048 * FCC_STATUS_SUCCESS in case of success or one of the `::fcc_status_e` errors otherwise. 00049 */ 00050 00051 fcc_status_e fcc_finalize(void); 00052 00053 /* === Factory clean operation === */ 00054 00055 /** Cleans from the device all data that was saved during the factory process. 00056 * Should be called if the process failed and needs to be executed again. 00057 * 00058 * @returns 00059 * FCC_STATUS_SUCCESS in case of success or one of the `::fcc_status_e` errors otherwise. 00060 */ 00061 fcc_status_e fcc_storage_delete(void); 00062 00063 00064 /* === Warning and errors data operations === */ 00065 00066 /** The function retrieves pointer to warning and errors structure. 00067 * Should be called after fcc_verify_device_configured_4mbed_cloud, when possible warning and errors was 00068 * stored in the structure. 00069 * The structure contains data of last fcc_verify_device_configured_4mbed_cloud run.* 00070 * @returns pointer to fcc_output_info_s structure. 00071 */ 00072 fcc_output_info_s* fcc_get_error_and_warning_data(void); 00073 00074 /* === Verification === */ 00075 00076 /** Verifies that all mandatory fields needed to connect to mbed Cloud are in place on the device. 00077 * Should be called in the end of the factory process 00078 * 00079 * @returns 00080 * FCC_STATUS_SUCCESS in case of success or one of the `::fcc_status_e` errors otherwise. 00081 */ 00082 fcc_status_e fcc_verify_device_configured_4mbed_cloud(void); 00083 00084 00085 /* === Secure Time === */ 00086 00087 /** Sets device time. This function will set the device time to what the user provides. 00088 * Device time must be set in order to enable certificate expiration validations. 00089 * 00090 * @param time The device time to set. As epoch time (number of seconds that have elapsed since January 1, 1970) 00091 * 00092 * @returns 00093 * Operation status. 00094 */ 00095 fcc_status_e fcc_time_set(uint64_t time); 00096 00097 00098 /* === Entropy and RoT injection === */ 00099 00100 /** Sets Entropy. 00101 * If device does not have its own entropy - this function must be called after fcc_init() and prior to any other FCC or KCM functions. 00102 * This API should be used if device has its own entropy and user wishes to add his own entropy. 00103 * 00104 * @param buf The buffer containing the entropy. 00105 * @param buf_size The size of buf in bytes. Must be exactly FCC_ENTROPY_SIZE. 00106 * 00107 * @returns 00108 * Operation status. 00109 */ 00110 fcc_status_e fcc_entropy_set(const uint8_t *buf, size_t buf_size); 00111 00112 /** Sets root of trust 00113 * If user wishes to set his own root of trust, this function must be called after fcc_init() and fcc_entropy_set() (if user sets his own entropy), 00114 * and prior to any other FCC or KCM functions. 00115 * 00116 * @param buf The buffer containing the root of trust. 00117 * @param buf_size The size of buf in bytes. Must be exactly FCC_ROT_SIZE. 00118 * 00119 * @returns 00120 * Operation status. 00121 */ 00122 fcc_status_e fcc_rot_set(const uint8_t *buf, size_t buf_size); 00123 00124 /* === Bootstrap CA certificate identification storage === */ 00125 00126 /** The function sets bootstrap ca identification and stores it. 00127 * Should be called only after storing bootstrap ca certificate on the device. 00128 * 00129 * @returns 00130 * Operation status. 00131 */ 00132 fcc_status_e fcc_trust_ca_cert_id_set(void); 00133 00134 00135 /* === Factory flow disable === */ 00136 /** Sets Factory disabled flag to disable further use of the factory flow. 00137 * 00138 * @returns 00139 * Operation status. 00140 */ 00141 fcc_status_e fcc_factory_disable(void); 00142 00143 /** Returns true if the factory flow was disabled by calling fcc_factory_disable() API, outherwise 00144 * returns false. 00145 * 00146 * - If the factory flow is already disabled any FCC API(s) will fail. 00147 * 00148 * @param fcc_factory_disable An output parameter, will be set to "true" in case factory 00149 * flow is already disabled, "false" otherwise. 00150 * 00151 * @returns 00152 * FCC_STATUS_SUCCESS in case of success or one of the `::fcc_status_e` errors otherwise. 00153 */ 00154 fcc_status_e fcc_is_factory_disabled(bool *fcc_factory_disable); 00155 00156 /* === Developer flow === */ 00157 00158 /** This API is for developers only. 00159 * You can download the `mbed_cloud_dev_credentials.c` file from the portal and thus, skip running FCU on PC side. 00160 * The API reads all credentials from the `mbed_cloud_dev_credentials.c` file and stores them in the KCM. 00161 * RoT, Entropy and Time configurations are not a part of fcc_developer_flow() API. Devices that need to set RoT or Entropy 00162 * should call `fcc_rot_set()`/`fcc_entropy_set()` APIs before fcc_developer_flow(). 00163 * If device does not have it's own time configuration and `fcc_time_set()` was not called before fcc_developer_flow(), 00164 * during fcc_verify_device_configured_4mbed_cloud() certificate time validity will not be checked. 00165 * 00166 * 00167 * @returns 00168 * FCC_STATUS_SUCCESS in case of success or one of the `::fcc_status_e` errors otherwise. 00169 */ 00170 fcc_status_e fcc_developer_flow(void); 00171 00172 00173 #ifdef __cplusplus 00174 } 00175 #endif 00176 00177 #endif //__FACTORY_CONFIGURATOR_CLIENT_H__
Generated on Tue Jul 12 2022 19:01:34 by 1.7.2