key_config_manager.h

Go to the documentation of this file.

// ----------------------------------------------------------------------------
// Copyright 2016-2017 ARM Ltd.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
// ----------------------------------------------------------------------------

#ifndef __KEYS_CONFIG_MANAGER_H__
#define __KEYS_CONFIG_MANAGER_H__

#include <stdlib.h>
#include <stdbool.h>
#include <inttypes.h>
#include "kcm_status.h"
#include "kcm_defs.h"

#ifdef __cplusplus
extern "C" {
#endif

    /* === Initialization and Finalization === */

    kcm_status_e kcm_init(void);

    kcm_status_e kcm_finalize(void);

    /* === Key, certificate, and configuration data storage === */

    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 kcm_item_info);

    /* === Key, certificate, and configuration data retrieval === */

    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);

    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);

    kcm_status_e kcm_item_get_size_and_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_size_out);

#ifdef MBED_CONF_MBED_CLOUD_CLIENT_PSA_SUPPORT

    /* === Key and Configuration Manager with Platform Secure Architecture (PSA) support uses PSA key IDs from 0x1 up to 0x2800 === */


    kcm_status_e kcm_item_get_handle(const uint8_t    *kcm_item_name,
                                     size_t            kcm_item_name_len,
                                     kcm_item_type_e   kcm_item_type,
                                     kcm_key_handle_t *key_handle_out);

    kcm_status_e kcm_item_close_handle(kcm_key_handle_t *key_handle);

#ifdef MBED_CONF_MBED_CLOUD_CLIENT_SECURE_ELEMENT_SUPPORT

#define KCM_ITEM_EXTRA_INFO_INIT {KCM_LOCATION_PSA, KCM_LOCATION_PSA}
    static inline kcm_item_extra_info_s kcm_item_extra_info_init(void)
    {
        const kcm_item_extra_info_s extra_info = KCM_ITEM_EXTRA_INFO_INIT;
        return (extra_info);
    }

    kcm_status_e kcm_item_get_location(const uint8_t *item_name,
                                       size_t item_name_len,
                                       kcm_item_type_e kcm_item_type,
                                       kcm_item_location_e *item_location_out);


    kcm_status_e kcm_se_private_key_get_slot(const uint8_t *prv_key_name,
                                             size_t prv_key_name_len,
                                             uint64_t *se_prv_key_slot);


#endif // #ifdef MBED_CONF_MBED_CLOUD_CLIENT_SECURE_ELEMENT_SUPPORT
#endif // #ifdef MBED_CONF_MBED_CLOUD_CLIENT_PSA_SUPPORT

    /* === Key, certificate, and configuration delete === */

    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);

    /* === Certificate chain APIs === */

    kcm_status_e kcm_cert_chain_create(kcm_cert_chain_handle *kcm_chain_handle,
                                       const uint8_t         *kcm_chain_name,
                                       size_t                 kcm_chain_name_len,
                                       size_t                 kcm_chain_len,
                                       bool                   kcm_chain_is_factory);

    kcm_status_e kcm_cert_chain_open(kcm_cert_chain_handle *kcm_chain_handle,
                                     const uint8_t         *kcm_chain_name,
                                     size_t                 kcm_chain_name_len,
                                     size_t                *kcm_chain_len_out);

    kcm_status_e kcm_cert_chain_add_next(kcm_cert_chain_handle kcm_chain_handle,
                                         const uint8_t        *kcm_cert_data,
                                         size_t                kcm_cert_data_size);

    kcm_status_e kcm_cert_chain_delete(const uint8_t *kcm_chain_name,
                                       size_t         kcm_chain_name_len);

    kcm_status_e kcm_cert_chain_get_next_size(kcm_cert_chain_handle kcm_chain_handle,
                                              size_t               *kcm_cert_data_size);

    kcm_status_e kcm_cert_chain_get_next_data(kcm_cert_chain_handle kcm_chain_handle,
                                              uint8_t              *kcm_cert_data,
                                              size_t                kcm_max_cert_data_size,
                                              size_t               *kcm_actual_cert_data_size);


    kcm_status_e kcm_cert_chain_close(kcm_cert_chain_handle kcm_chain_handle);


    /* === Factory Reset === */

    kcm_status_e kcm_factory_reset(void);


    kcm_status_e kcm_key_pair_generate_and_store(const kcm_crypto_key_scheme_e key_scheme,
                                                 const uint8_t                *private_key_name,
                                                 size_t                        private_key_name_len,
                                                 const uint8_t                *public_key_name,
                                                 size_t                        public_key_name_len,
                                                 bool                          kcm_item_is_factory,
                                                 const kcm_security_desc_s     kcm_item_info);


   kcm_status_e kcm_csr_generate(const uint8_t             *private_key_name,
                                  size_t                     private_key_name_len,
                                  const kcm_csr_params_s    *csr_params,
                                  uint8_t                   *csr_buff_out,
                                  size_t                     csr_buff_max_size,
                                  size_t                    *csr_buff_act_size);


    kcm_status_e kcm_generate_keys_and_csr(kcm_crypto_key_scheme_e     key_scheme,
                                           const uint8_t              *private_key_name,
                                           size_t                      private_key_name_len,
                                           const uint8_t              *public_key_name,
                                           size_t                      public_key_name_len,
                                           bool                        kcm_item_is_factory,
                                           const kcm_csr_params_s     *csr_params,
                                           uint8_t                    *csr_buff_out,
                                           size_t                      csr_buff_max_size,
                                           size_t                     *csr_buff_act_size_out,
                                           const kcm_security_desc_s   kcm_item_info);

    kcm_status_e kcm_certificate_verify_with_private_key(const uint8_t *kcm_cert_data,
                                                         size_t         kcm_cert_data_size,
                                                         const uint8_t *kcm_priv_key_name,
                                                         size_t         kcm_priv_key_name_len);


    kcm_status_e kcm_asymmetric_sign(
        const uint8_t              *private_key_name,
        size_t                      private_key_name_len,
        const uint8_t               *hash_digest,
        size_t                      hash_digest_size,
        uint8_t                     *signature_data_out,
        size_t                      signature_data_max_size,
        size_t                      *signature_data_act_size_out);


    kcm_status_e kcm_asymmetric_verify(
        const uint8_t              *public_key_name,
        size_t                      public_key_name_len,
        const uint8_t               *hash_digest,
        size_t                      hash_digest_size,
        const uint8_t               *signature,
        size_t                      signature_size);

    kcm_status_e kcm_generate_random(uint8_t *buffer, size_t buffer_size);

#ifndef MBED_CONF_MBED_CLOUD_CLIENT_PSA_SUPPORT
    /* Computes a shared secret using the elliptic curve Diffie-Hellman algorithm.
    *
    *    @param[in] private_key_name                            The private key name to fetch from storage.
    *    @param[in] private_key_name_len                        The length of the private key name.
    *    @param[in] peer_public_key                             The public key from a peer in DER format.
    *    @param[in] peer_public_key_size                        The length of the public key from a peer.
    *    @param[out] shared_secret                              A pointer to the output shared secret buffer.
    *    @param[in] shared_secret_max_size                      The size of the shared secret buffer. Must be at least ::KCM_EC_SECP256R1_SHARED_SECRET_SIZE bytes.
    *    @param[out] shared_secret_act_size_out                 The actual size of the shared secret buffer.
    *
    *    @returns
    *        KCM_STATUS_SUCCESS on success.
    *        KCM_STATUS_INVALID_PARAMETER if one of the parameters is illegal.
    *        One of the ::kcm_status_e errors otherwise.
    *
    */
    kcm_status_e kcm_ecdh_key_agreement(
        const uint8_t              *private_key_name,
        size_t                      private_key_name_len,
        const uint8_t               *peer_public_key,
        size_t                      peer_public_key_size,
        uint8_t                     *shared_secret,
        size_t                      shared_secret_max_size,
        size_t                      *shared_secret_act_size_out);
#else //MBED_CONF_MBED_CLOUD_CLIENT_PSA_SUPPORT

    /* Computes a shared secret using the elliptic curve Diffie-Hellman algorithm.
    *
    * A few limitations to consider:
    * (1) If a secure element exists, this function enables use of a single key only - ALG_ECDSA(ALG_SHA_256).
    * (2) If PSA and secure element do not exist, this function enables use of multiple keys, except LPC55S69_NS and CY8CKIT_062_WIFI_BT_PSA targets.
    *
    *    @param[in] private_key_name                            The private key name to fetch from storage.
    *    @param[in] private_key_name_len                        The length of the private key name.
    *    @param[in] peer_public_key                             The public key from a peer in DER format.
    *    @param[in] peer_public_key_size                        The length of the public key from a peer.
    *    @param[out] shared_secret                              A pointer to the output shared secret buffer.
    *    @param[in] shared_secret_max_size                      The size of the shared secret buffer. Must be at least ::KCM_EC_SECP256R1_SHARED_SECRET_SIZE bytes.
    *    @param[out] shared_secret_act_size_out                 The actual size of the shared secret buffer.
    *
    *    @returns
    *        KCM_STATUS_SUCCESS on success.
    *        KCM_STATUS_INVALID_PARAMETER if one of the parameters is illegal.
    *        One of the ::kcm_status_e errors otherwise.
    *
    * \deprecated for PSA configuration, due to `psa_set_key_enrollment_algorithm()` API deprecation in mbed-crypto that is used by `kcm_ecdh_key_agreement`.
    */
    kcm_status_e kcm_ecdh_key_agreement(
        const uint8_t              *private_key_name,
        size_t                      private_key_name_len,
        const uint8_t               *peer_public_key,
        size_t                      peer_public_key_size,
        uint8_t                     *shared_secret,
        size_t                      shared_secret_max_size,
        size_t                      *shared_secret_act_size_out);

#endif //MBED_CONF_MBED_CLOUD_CLIENT_PSA_SUPPORT

#ifdef __cplusplus
}
#endif

#endif //__KEYS_CONFIG_MANAGER_H__