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     * Item name restrictions (the kcm_item_name argument):
00059     * If you are using Mbed OS 5.11 or higher with the built-in secure storage (KVStore), or your own secure storage (ported to the Pelion client), kcm_item_name must only include the following characters: 'a'-'z', 'A'-'Z', '0'-'9', '_', '-', '.'.
00060     * If you are using the Pelion client secure storage (SOTP and ESFS), KCM file names have no character restrictions. Note that this feature will be deprecated in the future and the same character restriction will apply ('a'-'z', 'A'-'Z', '0'-'9', '_', '-', '.').
00061     * 
00062     *
00063     *    @param[in] kcm_item_name KCM item name. See comment above.
00064     *    @param[in] kcm_item_name_len KCM item name length. kcm_item_name_len must be at most ::KCM_MAX_FILENAME_SIZE bytes.
00065     *    @param[in] kcm_item_type KCM item type as defined in `::kcm_item_type_e`
00066     *    @param[in] kcm_item_is_factory True if the KCM item is a factory item, otherwise false.
00067     *    @param[in] kcm_item_data KCM item data buffer. Can be NULL if `kcm_item_data_size` is 0.
00068     *    @param[in] kcm_item_data_size KCM item data buffer size in bytes. Can be 0 if you wish to store an empty file.
00069     *    @param[in] security_desc Security descriptor.
00070     *
00071     *    @returns
00072     *        KCM_STATUS_SUCCESS in success.
00073     *        KCM_STATUS_FILE_EXIST if trying to store an item that already exists.
00074     *        KCM_STATUS_FILE_NAME_TOO_LONG if kcm_item_name_len is too long.
00075     *        KCM_STATUS_FILE_NAME_INVALID if kcm_item_name contains illegal characters.
00076     *        One of the `::kcm_status_e` errors otherwise.
00077     */
00078     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);
00079 
00080     /* === Keys, Certificates and Configuration data retrieval === */
00081 
00082     /** Retrieve the KCM item data size from a secure storage.
00083     *
00084     *    @param[in] kcm_item_name KCM item name.
00085     *    @param[in] kcm_item_name_len KCM item name length.
00086     *    @param[in] kcm_item_type KCM item type as defined in `::kcm_item_type_e`
00087     *    @param[out] kcm_item_data_size_out KCM item data size in bytes.
00088     *
00089     *    @returns
00090     *        KCM_STATUS_SUCCESS in case of success or one of the `::kcm_status_e` errors otherwise.
00091     */
00092     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);
00093 
00094     /** Retrieve KCM item data from a secure storage.
00095     *
00096     *    @param[in] kcm_item_name KCM item name.
00097     *    @param[in] kcm_item_name_len KCM item name length.
00098     *    @param[in] kcm_item_type KCM item type as defined in `::kcm_item_type_e`
00099     *    @param[out] kcm_item_data_out KCM item data output buffer. Can be NULL if `kcm_item_data_size` is 0.
00100     *    @param[in] kcm_item_data_max_size The maximum size of the KCM item data output buffer in bytes.
00101     *    @param[out] kcm_item_data_act_size_out Actual KCM item data output buffer size in bytes.
00102     *
00103     *    @returns
00104     *        KCM_STATUS_SUCCESS in case of success or one of the `::kcm_status_e` errors otherwise.
00105     */
00106     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);
00107 
00108     /* === Keys, Certificates and Configuration delete === */
00109 
00110     /** Delete a KCM item from a secure storage.
00111     *
00112     *    @param[in] kcm_item_name KCM item name.
00113     *    @param[in] kcm_item_name_len KCM item name length.
00114     *    @param[in] kcm_item_type KCM item type as defined in `::kcm_item_type_e`
00115     *
00116     *    @returns
00117     *        KCM_STATUS_SUCCESS status in case of success or one of ::kcm_status_e errors otherwise.
00118     */
00119     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);
00120 
00121     /* === Certificates chain APIs === */
00122 
00123     /** The API initializes the chain context for the write chain operation.
00124     *   It should be called before `::kcm_cert_chain_add_next` API.
00125     *
00126     *    @param[out] kcm_chain_handle                 A pointer to the certificate chain handle.
00127     *    @param[in]  kcm_chain_name                   A pointer to the certificate chain name.
00128     *    @param[in]  kcm_chain_name_len               The length of the certificate name buffer.
00129     *    @param[in]  kcm_chain_len                    The number of certificates in the chain.
00130     *    @param[in]  kcm_chain_is_factory             True if the KCM chain is a factory item, otherwise false.
00131     *
00132     *    @returns
00133     *        KCM_STATUS_SUCCESS in case of success or one of the `::kcm_status_e` errors otherwise.
00134     */
00135     kcm_status_e  kcm_cert_chain_create(kcm_cert_chain_handle *kcm_chain_handle,
00136                                        const uint8_t *kcm_chain_name,
00137                                        size_t kcm_chain_name_len,
00138                                        size_t kcm_chain_len,
00139                                        bool kcm_chain_is_factory);
00140 
00141     /** The API initializes the chain context for the read chain operation.
00142     *   This API should be called before `::kcm_cert_chain_get_next_size` and `::kcm_cert_chain_get_next_data` APIs.
00143     *
00144     *    @param[out] kcm_chain_handle                  A pointer to the certificate chain handle.
00145     *    @param[in]  kcm_chain_name                    A pointer to the certificate chain name.
00146     *    @param[in]  kcm_chain_name_len                The size of the certificate name buffer.
00147     *    @param[out] kcm_chain_len                     The length of the certificate chain.
00148     *
00149     *    @returns
00150     *        KCM_STATUS_SUCCESS in case of success or one of the `::kcm_status_e` errors otherwise.
00151     */
00152     kcm_status_e  kcm_cert_chain_open(kcm_cert_chain_handle *kcm_chain_handle,
00153                                      const uint8_t *kcm_chain_name,
00154                                      size_t kcm_chain_name_len,
00155                                      size_t *kcm_chain_len_out);
00156 
00157     /** This API adds the next chain of certificates to the storage. 
00158     *
00159     *  It also validates the previous certificate (unless it is the first certificate) with the public key from `kcm_cert_data`.
00160     *  The certificates should be added in the order from lowest child, followed by the certificate that signs it and so on, all the way to the root of the chain.
00161     *
00162     *    @param[in] kcm_chain_handle                 The certificate chain handle.
00163     *    @param[in] kcm_cert_data                    A pointer to the certificate data in DER format.
00164     *    @param[in] kcm_cert_data_size               The size of the certificate data buffer.
00165     *
00166     *    @returns
00167     *        KCM_STATUS_SUCCESS in case of success. 
00168     *        KCM_STATUS_CERTIFICATE_CHAIN_VERIFICATION_FAILED if one of the certificates in the chain failed to verify its predecessor.
00169     *        In other cases, one of the `::kcm_status_e` errors.
00170     *       
00171     */
00172     kcm_status_e  kcm_cert_chain_add_next(kcm_cert_chain_handle kcm_chain_handle,
00173                                          const uint8_t *kcm_cert_data,
00174                                          size_t kcm_cert_data_size);
00175 
00176     /** The API deletes all certificates of the chain from the storage.
00177     *  In case of invalid chain the API deletes all reachable certificates and return relevant error for indication.
00178     *
00179     *    @param[in] kcm_chain_name                A pointer to certificate chain name.
00180     *    @param[in] kcm_chain_name_len            The length of certificate chain name.
00181     *
00182     *    @returns
00183     *        KCM_STATUS_SUCCESS in success or one of the `::kcm_status_e` errors otherwise.
00184     */
00185     kcm_status_e  kcm_cert_chain_delete(const uint8_t *kcm_chain_name,
00186                                        size_t kcm_chain_name_len);
00187 
00188     /** This API returns the size of the next certificate in the chain.
00189     *  It should be called before `::kcm_cert_chain_get_next_data`.
00190     *  This operation does not increase the chain's context iterator.
00191     *
00192     *    @param[in]  kcm_chain_handle        The certificate chain handle.
00193     *    @param[out] kcm_cert_data_size      The pointer size of the next certificate.
00194     *
00195     *    @returns
00196     *        KCM_STATUS_SUCCESS in success.
00197     *        KCM_STATUS_INVALID_NUM_OF_CERT_IN_CHAIN if the end of the chain was reached.
00198     *        Otherwise, one of the `::kcm_status_e` errors.
00199     */
00200     kcm_status_e  kcm_cert_chain_get_next_size(kcm_cert_chain_handle kcm_chain_handle,
00201                                               size_t *kcm_cert_data_size);
00202 
00203     /** This API returns the data of the next certificate in the chain.
00204     *   To get the exact size of the next certificate, use `::kcm_cert_chain_get_next_size`.
00205     *   In the end of the get data operation, the chain context points to the next certificate of the current chain.
00206     *
00207     *    @param[in] kcm_chain_handle                    The certificate chain handle.
00208     *    @param[in/out] kcm_cert_data                   A pointer to the certificate data in DER format.
00209     *    @param[in] kcm_max_cert_data_size              The max size of the certificate data buffer.
00210     *    @param[out] kcm_actual_cert_data_size          The actual size of the certificate data.
00211     *
00212     *    @returns
00213     *        KCM_STATUS_SUCCESS in success.
00214     *        KCM_STATUS_INVALID_NUM_OF_CERT_IN_CHAIN if the end of the chain was reached.
00215     *        Otherwise, one of the `::kcm_status_e` errors.
00216     */
00217     kcm_status_e  kcm_cert_chain_get_next_data(kcm_cert_chain_handle kcm_chain_handle,
00218                                               uint8_t *kcm_cert_data,
00219                                               size_t kcm_max_cert_data_size,
00220                                               size_t *kcm_actual_cert_data_size);
00221 
00222 
00223     /** The API releases the context and frees allocated resources.
00224     *   When the operation type is creation and if the total number of added/stored certificates is not equal to the number
00225     *   of certificates in the chain, the API returns an error.
00226     *
00227     *    @param[in] kcm_chain_handle                    The certificate chain handle.
00228     *
00229     *    @returns
00230     *        ::KCM_STATUS_SUCCESS in success.
00231     *        ::KCM_STATUS_CLOSE_INCOMPLETE_CHAIN if all certificates were not saved. In this case the chain will be deleted.
00232     *        Otherwise, one of the `::kcm_status_e` errors.
00233     */
00234     kcm_status_e  kcm_cert_chain_close(kcm_cert_chain_handle kcm_chain_handle);
00235 
00236 
00237     /* === Factory Reset === */
00238 
00239     /**  Reset the KCM secure storage to factory state.
00240     *
00241     *    @returns
00242     *        ::KCM_STATUS_SUCCESS in success.
00243     *        Otherwise, one of the `::kcm_status_e` errors.
00244     */
00245     kcm_status_e  kcm_factory_reset(void);
00246 
00247 
00248     /** Generate a key pair complying the given cryptographic scheme in DER format.
00249     *    Saves the private and public key if provided.
00250     *
00251     *      @param key_scheme The cryptographic scheme.
00252     *      @param private_key_name The private key name for which a key pair is generated.
00253     *      @param private_key_name_len The length of the private key name.
00254     *      @param public_key_name The public key name for which a key pair is generated.
00255     *      This parameter is optional. If not provided, the key will be generated, but not stored.
00256     *      @param public_key_name_len The length of the public key name.
00257     *      Must be 0, if `::public_key_name` not provided.
00258     *      @param kcm_item_is_factory True if the KCM item is a factory item, otherwise false.
00259     *      @param kcm_params Additional `kcm_params`. Currently void.
00260     *
00261     *      @returns
00262     *         KCM_STATUS_SUCCESS in success.
00263     *         Otherwise, one of the `::kcm_status_e` errors.
00264     */
00265     kcm_status_e  kcm_key_pair_generate_and_store(
00266         const kcm_crypto_key_scheme_e     key_scheme,
00267         const uint8_t                     *private_key_name,
00268         size_t                            private_key_name_len,
00269         const uint8_t                     *public_key_name,
00270         size_t                            public_key_name_len,
00271         bool                              kcm_item_is_factory,
00272         const kcm_security_desc_s         *kcm_params
00273     );
00274 
00275 
00276     /** Generate a general CSR from the given private key.
00277    *
00278    *     @param private_key_name The private key name to fetch from storage.
00279    *     @param private_key_name_len The length of the private key name.
00280    *     @param csr_params CSR parameters.
00281    *     @param csr_buff_out A pointer to the generated CSR buffer to fill.
00282    *     @param csr_buff_max_size The size of the supplied CSR buffer.
00283    *     @param csr_buff_act_size The actual size of the filled CSR buffer.
00284    *
00285    *     @returns
00286    *         KCM_STATUS_SUCCESS in success.
00287    *         Otherwise, one of the `::kcm_status_e` errors.
00288    */
00289     kcm_status_e  kcm_csr_generate(
00290         const uint8_t              *private_key_name,
00291         size_t                     private_key_name_len,
00292         const kcm_csr_params_s     *csr_params,
00293         uint8_t                    *csr_buff_out,
00294         size_t                     csr_buff_max_size,
00295         size_t                     *csr_buff_act_size
00296     );
00297 
00298 
00299     /** Generate private and public key and CSR from the generated keys.
00300     *
00301     *     @param key_scheme The cryptographic scheme.
00302     *     @param private_key_name The private key name to generate.
00303     *     @param private_key_name_len The length of the private key name.
00304     *     @param public_key_name The public key name for which a key pair is generated.
00305     *     This parameter is optional. If not provided, the key will be generated, but not stored.
00306     *     @param public_key_name_len The length of the public key name.
00307     *     Must be 0, if `::public_key_name` is not provided.
00308     *     @param kcm_item_is_factory True if the KCM item is a factory item, otherwise false.
00309     *     @param csr_params CSR parameters.
00310     *     @param csr_buff_out A pointer to the generated CSR buffer to fill.
00311     *     @param csr_buff_max_size The size of the supplied CSR buffer.
00312     *     @param csr_buff_act_size The actual size of the filled CSR buffer.
00313     *     @param kcm_data_pkcm_params Additional `kcm_params`. Currently void.
00314     *
00315     *     @returns
00316     *         KCM_STATUS_SUCCESS in success.
00317     *         Otherwise, one of the `::kcm_status_e` errors.
00318     */
00319     kcm_status_e  kcm_generate_keys_and_csr(
00320         kcm_crypto_key_scheme_e     key_scheme,
00321         const uint8_t               *private_key_name,
00322         size_t                      private_key_name_len,
00323         const uint8_t               *public_key_name,
00324         size_t                      public_key_name_len,
00325         bool                        kcm_item_is_factory,
00326         const kcm_csr_params_s      *csr_params,
00327         uint8_t                     *csr_buff_out,
00328         size_t                      csr_buff_max_size,
00329         size_t                      *csr_buff_act_size_out,
00330         const kcm_security_desc_s   *kcm_params
00331     );
00332 
00333     /** Verify the device-generated certificate against the given private key name from storage.
00334     * This function can be called when the certificate creation is initiated by the device using `kcm_generate_keys_and_csr` or `kcm_csr_generate` functions.
00335     * In this case, the function checks the correlation between certificate's public key and given private key generated by the device and saved in device storage.
00336     *
00337     *    @param[in] kcm_cert_data The DER certificate data buffer.
00338     *    @param[in] kcm_cert_data_size The size of the DER certificate data buffer in bytes.
00339     *    @param[in] kcm_priv_key_name The private key name of the certificate. The function assumes that the key was generated by the device and saved in the storage.
00340     *    @param[in] kcm_priv_key_name_len The length of the private key name of the certificate.
00341     *
00342     *    @returns
00343     *        KCM_STATUS_SUCCESS in case of success.
00344     *        KCM_STATUS_ITEM_NOT_FOUND if the private key was not found in the storage.
00345     *        Otherwise, one of the `::kcm_status_e` errors.
00346     */
00347     kcm_status_e  kcm_certificate_verify_with_private_key(
00348         const uint8_t * kcm_cert_data,
00349         size_t kcm_cert_data_size,
00350         const uint8_t * kcm_priv_key_name,
00351         size_t kcm_priv_key_name_len);
00352 
00353 
00354 
00355 #ifdef __cplusplus
00356 }
00357 #endif
00358 
00359 #endif //__KEYS_CONFIG_MANAGER_H__
00360