factory_configurator_client.h

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 /* === Defines === */
00035 #define FCC_ENTROPY_SIZE                   56
00036 #define FCC_ROT_SIZE                       24
00037 
00038 /* === Initialization and Finalization === */
00039 
00040 /** Initiates the FCC module.
00041 *
00042 *   @returns
00043 *       FCC_STATUS_SUCCESS in case of success or one of the `::fcc_status_e` errors otherwise.
00044 */
00045 fcc_status_e fcc_init(void);
00046 
00047 
00048 /** Finalizes the FCC module.
00049 *   Finalizes and frees file storage resources.
00050 *
00051 *    @returns
00052 *       FCC_STATUS_SUCCESS in case of success or one of the `::fcc_status_e` errors otherwise.
00053 */
00054 
00055 fcc_status_e fcc_finalize(void);
00056 
00057 /* === Factory clean operation === */
00058 
00059 /** Cleans from the device all data that was saved during the factory process.
00060 *  Should be called if the process failed and needs to be executed again.
00061 *
00062 *   @returns
00063 *       FCC_STATUS_SUCCESS in case of success or one of the `::fcc_status_e` errors otherwise.
00064 */
00065 fcc_status_e fcc_storage_delete(void);
00066 
00067 
00068 /* === Warning and errors data operations === */
00069 
00070 /** The function retrieves pointer to warning and errors structure.
00071 *  Should be called after fcc_verify_device_configured_4mbed_cloud, when possible warning and errors was
00072 *  stored in the structure.
00073 *  The structure contains data of last fcc_verify_device_configured_4mbed_cloud run.*
00074 *   @returns pointer to fcc_output_info_s structure.
00075 */
00076 fcc_output_info_s* fcc_get_error_and_warning_data(void);
00077 
00078 /* === Verification === */
00079 
00080 /** Verifies that all mandatory fields needed to connect to mbed Cloud are in place on the device.
00081  *  Should be called in the end of the factory process
00082  *
00083  *    @returns
00084  *       FCC_STATUS_SUCCESS in case of success or one of the `::fcc_status_e` errors otherwise.
00085  */
00086 fcc_status_e fcc_verify_device_configured_4mbed_cloud(void);
00087 
00088 
00089 /* === Developer flow === */
00090 
00091 /** This API is for developers only.
00092 *   You can download the `mbed_cloud_dev_credentials.c` file from the portal and thus, skip running FCU on PC side.
00093 *   The API reads all credentials from the `mbed_cloud_dev_credentials.c` file and stores them in the KCM.
00094 *   RoT, Entropy and Time configurations are not a part of fcc_developer_flow() API. Devices that need to set RoT or Entropy
00095 *   should call `fcc_rot_set()`/`fcc_entropy_set()` APIs before fcc_developer_flow().
00096 *   If device does not have it's own time configuration and `fcc_secure_time_set()` was not called before  fcc_developer_flow(),
00097 *   during fcc_verify_device_configured_4mbed_cloud() certificate time validity will not be checked.
00098 *
00099 *
00100 *   @returns
00101 *       FCC_STATUS_SUCCESS in case of success or one of the `::fcc_status_e` errors otherwise.
00102 */
00103 fcc_status_e fcc_developer_flow(void);
00104 
00105 #ifndef __DOXYGEN__ //Not implemented features
00106 
00107 /* === Secure Time === */
00108 
00109 /** Sets Secure time. This function will set the secure time to what the user provides.
00110 *   Secure time must be set in order to enable certificate expiration validations.
00111 *
00112 *     @param time The secure time to set.
00113 *
00114 *     @returns
00115 *        Operation status.
00116 */
00117 fcc_status_e fcc_secure_time_set(uint64_t time);
00118 
00119 /* === Entropy and RoT injection === */
00120 /** Sets Entropy.
00121 *   If user wishes to set his own entropy, this function must be called after fcc_init() and prior to any other FCC or KCM functions.
00122 *
00123 *     @param buf The buffer containing the entropy.
00124 *     @param buf_size The size of buf in bytes. Must be exactly FCC_ENTROPY_SIZE.
00125 *
00126 *     @returns
00127 *        Operation status.
00128 */
00129 fcc_status_e fcc_entropy_set(const uint8_t *buf, size_t buf_size);
00130 
00131 /** Sets root of trust
00132 *   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),
00133 and prior to any other FCC or KCM functions.
00134 *
00135 *     @param buf The buffer containing the root of trust.
00136 *     @param buf_size The size of buf in bytes. Must be exactly FCC_ROT_SIZE.
00137 *
00138 *     @returns
00139 *        Operation status.
00140 */
00141 fcc_status_e fcc_rot_set(const uint8_t *buf, size_t buf_size);
00142 
00143 
00144 /* === Factory flow disable === */
00145 /** Sets Factory disabled flag to disable further use of the factory flow.
00146 *
00147 *     @returns
00148 *        Operation status.
00149 */
00150 fcc_status_e fcc_factory_disable(void);
00151 
00152 /** Returns true if the factory flow was disabled by calling fcc_factory_disable() API, outherwise
00153 *   returns false.
00154 *
00155 *   - If the factory flow is already disabled any FCC API(s) will fail.
00156 *
00157 *     @param fcc_factory_disable An output parameter, will be set to "true" in case factory
00158 *                                     flow is already disabled, "false" otherwise.
00159 *
00160 *   @returns
00161 *       FCC_STATUS_SUCCESS in case of success or one of the `::fcc_status_e` errors otherwise.
00162 */
00163 fcc_status_e fcc_is_factory_disabled(bool *fcc_factory_disable);
00164 
00165 /* === CSR generation === */
00166 
00167 /** Generates bootstrap CSR from a given private and public keys in DER encoding scheme.
00168 *   Further design is needed
00169 *
00170 *     @param key_name The key name to fetch from storage(public/private).
00171 *     @param key_name_len The key name len.
00172 *     @param bootstrap_csr_out Pointer to generated bootstrap CSR.
00173 *     @param bootstrap_csr_size_out Size of the CSR.
00174 *
00175 *     @returns
00176 *        Operation status.
00177 */
00178 fcc_status_e fcc_bootstrap_csr_generate(const uint8_t *key_name, size_t key_name_len,
00179                                         uint8_t **bootstrap_csr_out, size_t *bootstrap_csr_size_out);
00180 
00181 
00182 /** Generates E2E CSR from a given private and public keys
00183 *   Further design is needed
00184 *
00185 *     @param key_name The key name to fetch from storage(public/private).
00186 *     @param key_name_len The key name len.
00187 *     @param e2e_csr_out Pointer to generated E2E CSR.
00188 *     @param e2e_csr_size_out Size of the E2E CSR.
00189 *
00190 *     @returns
00191 *        Operation status.
00192 */
00193 fcc_status_e fcc_e2e_csr_generate(const uint8_t *key_name, size_t key_name_len,
00194                                   uint8_t **e2e_csr_out, size_t *e2e_csr_size_out);
00195 
00196 #endif
00197 #ifdef __cplusplus
00198 }
00199 #endif
00200 
00201 #endif //__FACTORY_CONFIGURATOR_CLIENT_H__