key_config_manager.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 __KEYS_CONFIG_MANAGER_H__
00018 #define __KEYS_CONFIG_MANAGER_H__
00019 
00020 #include <stdlib.h>
00021 #include <stdbool.h>
00022 #include <inttypes.h>
00023 #include "kcm_status.h"
00024 #include "kcm_defs.h"
00025 
00026 #ifdef __cplusplus
00027 extern "C" {
00028 #endif
00029 
00030 /**
00031 * @file key_config_manager.h
00032 *  \brief Keys and Configuration Manager (KCM) APIs.
00033 */
00034 
00035 /* === Initialization and Finalization === */
00036 
00037 /**
00038 *   Initiate the KCM module.
00039 *   Allocates and initializes file storage resources.
00040 *
00041 *    @returns
00042 *       KCM_STATUS_SUCCESS in case of success or one of the `::kcm_status_e` errors otherwise.
00043 */
00044 kcm_status_e kcm_init(void);
00045 
00046 /**
00047 *   Finalize the KCM module.
00048 *   Finalizes and frees file storage resources.
00049 *
00050 *    @returns
00051 *       KCM_STATUS_SUCCESS in case of success or one of the `::kcm_status_e` errors otherwise.
00052 */
00053 kcm_status_e kcm_finalize(void);
00054 
00055 /* === Keys, Certificates and Configuration data storage === */
00056 
00057 /** Store the KCM item into a secure storage.
00058 *
00059 *    @param[in] kcm_item_name KCM item name.
00060 *    @param[in] kcm_item_name_len KCM item name length.
00061 *    @param[in] kcm_item_type KCM item type as defined in `::kcm_item_type_e`
00062 *    @param[in] kcm_item_is_factory True if the KCM item is a factory item, otherwise false.
00063 *    @param[in] kcm_item_data KCM item data buffer. Can be NULL if `kcm_item_data_size` is 0.
00064 *    @param[in] kcm_item_data_size KCM item data buffer size in bytes. Can be 0 if you wish to store an empty file.
00065 *    @param[in] security_desc Security descriptor.
00066 *
00067 *    @returns
00068 *        KCM_STATUS_SUCCESS in case of success or one of the `::kcm_status_e` errors otherwise.
00069 */
00070 kcm_status_e kcm_item_store(const uint8_t *kcm_item_name, size_t kcm_item_name_len, kcm_item_type_e kcm_item_type, bool kcm_item_is_factory, const uint8_t *kcm_item_data, size_t kcm_item_data_size, const kcm_security_desc_s security_desc);
00071 
00072 /* === Keys, Certificates and Configuration data retrieval === */
00073 
00074 /** Retrieve the KCM item data size from a secure storage.
00075 *
00076 *    @param[in] kcm_item_name KCM item name.
00077 *    @param[in] kcm_item_name_len KCM item name length.
00078 *    @param[in] kcm_item_type KCM item type as defined in `::kcm_item_type_e`
00079 *    @param[out] kcm_item_data_size_out KCM item data size in bytes.
00080 *
00081 *    @returns
00082 *        KCM_STATUS_SUCCESS in case of success or one of the `::kcm_status_e` errors otherwise.
00083 */
00084 kcm_status_e kcm_item_get_data_size(const uint8_t *kcm_item_name, size_t kcm_item_name_len, kcm_item_type_e kcm_item_type, size_t *kcm_item_data_size_out);
00085 
00086 /** Retrieve KCM item data from a secure storage.
00087 *
00088 *    @param[in] kcm_item_name KCM item name.
00089 *    @param[in] kcm_item_name_len KCM item name length.
00090 *    @param[in] kcm_item_type KCM item type as defined in `::kcm_item_type_e`
00091 *    @param[out] kcm_item_data_out KCM item data output buffer. Can be NULL if `kcm_item_data_size` is 0.
00092 *    @param[in] kcm_item_data_max_size The maximum size of the KCM item data output buffer in bytes.
00093 *    @param[out] kcm_item_data_act_size_out Actual KCM item data output buffer size in bytes.
00094 *
00095 *    @returns
00096 *        KCM_STATUS_SUCCESS in case of success or one of the `::kcm_status_e` errors otherwise.
00097 */
00098 kcm_status_e kcm_item_get_data(const uint8_t *kcm_item_name, size_t kcm_item_name_len, kcm_item_type_e kcm_item_type, uint8_t *kcm_item_data_out, size_t kcm_item_data_max_size, size_t * kcm_item_data_act_size_out);
00099 
00100 /* === Keys, Certificates and Configuration update === */
00101 
00102 /** Update KCM item data in a secure storage.
00103 *
00104 *    @param[in] kcm_item_name KCM item name.
00105 *    @param[in] kcm_item_name_len KCM item name length.
00106 *    @param[in] kcm_item_type KCM item type as defined in `::kcm_item_type_e`
00107 *    @param[in] kcm_item_data KCM item data buffer.
00108 *    @param[in] kcm_item_data_size KCM item data buffer size in bytes.
00109 *
00110 *    @returns
00111 *        KCM_STATUS_SUCCESS in case of success or one of the `::kcm_status_e` errors otherwise.
00112 */
00113 kcm_status_e kcm_item_update_data(const uint8_t *kcm_item_name, size_t kcm_item_name_len, kcm_item_type_e kcm_item_type, const uint8_t *kcm_item_data, size_t kcm_item_data_size);
00114 
00115 /* === Keys, Certificates and Configuration delete === */
00116 
00117 /** Delete a KCM item from a secure storage.
00118 *
00119 *    @param[in] kcm_item_name KCM item name.
00120 *    @param[in] kcm_item_name_len KCM item name length.
00121 *    @param[in] kcm_item_type KCM item type as defined in `::kcm_item_type_e`
00122 *
00123 *    @returns
00124 *        KCM_STATUS_SUCCESS status in case of success or one of ::kcm_status_e errors otherwise.
00125 */
00126 kcm_status_e kcm_item_delete(const uint8_t *kcm_item_name, size_t kcm_item_name_len, kcm_item_type_e kcm_item_type);
00127 
00128 
00129 /* === Factory Reset === */
00130 
00131 /**  Reset the KCM secure storage to factory state.
00132 *
00133 *    @returns
00134 *        KCM_STATUS_SUCCESS in case of success or one of the `::kcm_status_e` errors otherwise.
00135 */
00136 kcm_status_e kcm_factory_reset(void);
00137 
00138 
00139 
00140 #ifndef __DOXYGEN__
00141 /* === Keys and CSR generation === */
00142 
00143 /**  Generate a key pair complying the given crypto scheme DER.
00144 *    Saves the private key and exposes the public key.
00145 *
00146 *      @param key_scheme The crypto scheme.
00147 *      @param key_name The key name for which a key pair is generated.
00148 *      @param key_name_len Key name length.
00149 *      @param pub_key_der_out Public key to generate in DER format.
00150 *      @param pub_key_der_size Public key size in bytes.
00151 *      @param priv_key_sec_desc Private key security descriptor.
00152 *      @param pub_key_sec_desc Public key security descriptor.
00153 *
00154 *      @returns
00155 *        Operation status.
00156 */
00157 kcm_status_e kcm_key_pair_generate_and_store(kcm_crypto_key_scheme_s key_scheme, const uint8_t *key_name, size_t key_name_len,
00158         uint8_t *pub_key_der_out, size_t pub_key_der_size,
00159         const kcm_security_desc_s priv_key_sec_desc, const kcm_security_desc_s pub_key_sec_desc);
00160 
00161 /** Generate a general CSR from the given private and public keys.
00162 *   Further design is needed
00163 *
00164 *     @param key_name The key name to fetch from storage(public/private).
00165 *     @param key_name_len The key name len.
00166 *     @param csr_out Pointer to generated E2E CSR.
00167 *     @param csr_size_out Size of the E2E CSR.
00168 *
00169 *     @returns
00170 *        Operation status.
00171 */
00172 kcm_status_e kcm_csr_generate(const uint8_t *key_name, size_t key_name_len,
00173                               uint8_t **csr_out, size_t *csr_size_out);
00174 #endif //#ifndef __DOXYGEN__
00175 
00176 #ifdef __cplusplus
00177 }
00178 #endif
00179 
00180 #endif //__KEYS_CONFIG_MANAGER_H__
00181