psa_crypto_se.h

00001 /*
00002  *  PSA crypto support for secure element drivers
00003  */
00004 /*  Copyright (C) 2019, ARM Limited, All Rights Reserved
00005  *  SPDX-License-Identifier: Apache-2.0
00006  *
00007  *  Licensed under the Apache License, Version 2.0 (the "License"); you may
00008  *  not use this file except in compliance with the License.
00009  *  You may obtain a copy of the License at
00010  *
00011  *  http://www.apache.org/licenses/LICENSE-2.0
00012  *
00013  *  Unless required by applicable law or agreed to in writing, software
00014  *  distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
00015  *  WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00016  *  See the License for the specific language governing permissions and
00017  *  limitations under the License.
00018  *
00019  *  This file is part of Mbed TLS (https://tls.mbed.org)
00020  */
00021 
00022 #ifndef PSA_CRYPTO_SE_H
00023 #define PSA_CRYPTO_SE_H
00024 
00025 #if !defined(MBEDTLS_CONFIG_FILE)
00026 #include "mbedtls/config.h"
00027 #else
00028 #include MBEDTLS_CONFIG_FILE
00029 #endif
00030 
00031 #include "psa/crypto.h"
00032 #include "psa/crypto_se_driver.h"
00033 
00034 /** The maximum lifetime value that this implementation supports
00035  * for a secure element.
00036  *
00037  * This is not a characteristic that each PSA implementation has, but a
00038  * limitation of the current implementation due to the constraints imposed
00039  * by storage. See #PSA_CRYPTO_SE_DRIVER_ITS_UID_BASE.
00040  *
00041  * The minimum lifetime value for a secure element is 2, like on any
00042  * PSA implementation (0=volatile and 1=internal-storage are taken).
00043  */
00044 #define PSA_MAX_SE_LIFETIME 255
00045 
00046 /** The base of the range of ITS file identifiers for secure element
00047  * driver persistent data.
00048  *
00049  * We use a slice of the implemenation reserved range 0xffff0000..0xffffffff,
00050  * specifically the range 0xfffffe00..0xfffffeff. The length of this range
00051  * drives the value of #PSA_MAX_SE_LIFETIME.
00052  * The identifiers 0xfffffe00 and 0xfffffe01 are actually not used since
00053  * they correspond to #PSA_KEY_LIFETIME_VOLATILE and
00054  * #PSA_KEY_LIFETIME_PERSISTENT which don't have a driver.
00055  */
00056 #define PSA_CRYPTO_SE_DRIVER_ITS_UID_BASE ( (psa_key_id_t) 0xfffffe00 )
00057 
00058 /** The maximum number of registered secure element driver lifetimes. */
00059 #define PSA_MAX_SE_DRIVERS 4
00060 
00061 /** Unregister all secure element drivers.
00062  *
00063  * \warning Do not call this function while the library is in the initialized
00064  *          state. This function is only intended to be called at the end
00065  *          of mbedtls_psa_crypto_free().
00066  */
00067 void psa_unregister_all_se_drivers( void );
00068 
00069 /** Initialize all secure element drivers.
00070  *
00071  * Called from psa_crypto_init().
00072  */
00073 psa_status_t psa_init_all_se_drivers( void );
00074 
00075 /** A structure that describes a registered secure element driver.
00076  *
00077  * A secure element driver table entry contains a pointer to the
00078  * driver's method table as well as the driver context structure.
00079  */
00080 typedef struct psa_se_drv_table_entry_s psa_se_drv_table_entry_t;
00081 
00082 /** Return the secure element driver information for a lifetime value.
00083  *
00084  * \param lifetime              The lifetime value to query.
00085  * \param[out] p_methods        On output, if there is a driver,
00086  *                              \c *methods points to its method table.
00087  *                              Otherwise \c *methods is \c NULL.
00088  * \param[out] p_drv_context    On output, if there is a driver,
00089  *                              \c *drv_context points to its context
00090  *                              structure.
00091  *                              Otherwise \c *drv_context is \c NULL.
00092  *
00093  * \retval 1
00094  *         \p lifetime corresponds to a registered driver.
00095  * \retval 0
00096  *         \p lifetime does not correspond to a registered driver.
00097  */
00098 int psa_get_se_driver( psa_key_lifetime_t lifetime,
00099                        const psa_drv_se_t **p_methods,
00100                        psa_drv_se_context_t **p_drv_context);
00101 
00102 /** Return the secure element driver table entry for a lifetime value.
00103  *
00104  * \param lifetime      The lifetime value to query.
00105  *
00106  * \return The driver table entry for \p lifetime, or
00107  *         \p NULL if \p lifetime does not correspond to a registered driver.
00108  */
00109 psa_se_drv_table_entry_t *psa_get_se_driver_entry(
00110     psa_key_lifetime_t lifetime );
00111 
00112 /** Return the method table for a secure element driver.
00113  *
00114  * \param[in] driver    The driver table entry to access, or \c NULL.
00115  *
00116  * \return The driver's method table.
00117  *         \c NULL if \p driver is \c NULL.
00118  */
00119 const psa_drv_se_t *psa_get_se_driver_methods(
00120     const psa_se_drv_table_entry_t *driver );
00121 
00122 /** Return the context of a secure element driver.
00123  *
00124  * \param[in] driver    The driver table entry to access, or \c NULL.
00125  *
00126  * \return A pointer to the driver context.
00127  *         \c NULL if \p driver is \c NULL.
00128  */
00129 psa_drv_se_context_t *psa_get_se_driver_context(
00130     psa_se_drv_table_entry_t *driver );
00131 
00132 /** Find a free slot for a key that is to be created.
00133  *
00134  * This function calls the relevant method in the driver to find a suitable
00135  * slot for a key with the given attributes.
00136  *
00137  * \param[in] attributes    Metadata about the key that is about to be created.
00138  * \param[in] driver        The driver table entry to query.
00139  * \param[out] slot_number  On success, a slot number that is free in this
00140  *                          secure element.
00141  */
00142 psa_status_t psa_find_se_slot_for_key(
00143     const psa_key_attributes_t *attributes,
00144     psa_key_creation_method_t method,
00145     psa_se_drv_table_entry_t *driver,
00146     psa_key_slot_number_t *slot_number );
00147 
00148 /** Destoy a key in a secure element.
00149  *
00150  * This function calls the relevant driver method to destroy a key
00151  * and updates the driver's persistent data.
00152  */
00153 psa_status_t psa_destroy_se_key( psa_se_drv_table_entry_t *driver,
00154                                  psa_key_slot_number_t slot_number );
00155 
00156 /** Load the persistent data of a secure element driver.
00157  *
00158  * \param driver        The driver table entry containing the persistent
00159  *                      data to load from storage.
00160  */
00161 psa_status_t psa_load_se_persistent_data(
00162     const psa_se_drv_table_entry_t *driver );
00163 
00164 /** Save the persistent data of a secure element driver.
00165  *
00166  * \param[in] driver    The driver table entry containing the persistent
00167  *                      data to save to storage.
00168  */
00169 psa_status_t psa_save_se_persistent_data(
00170     const psa_se_drv_table_entry_t *driver );
00171 
00172 /** Destroy the persistent data of a secure element driver.
00173  *
00174  * This is currently only used for testing.
00175  *
00176  * \param[in] lifetime  The driver lifetime whose persistent data should
00177  *                      be erased.
00178  */
00179 psa_status_t psa_destroy_se_persistent_data( psa_key_lifetime_t lifetime );
00180 
00181 
00182 /** The storage representation of a key whose data is in a secure element.
00183  */
00184 typedef struct
00185 {
00186     uint8_t slot_number[sizeof( psa_key_slot_number_t )];
00187     uint8_t bits[sizeof( psa_key_bits_t )];
00188 } psa_se_key_data_storage_t;
00189 
00190 #endif /* PSA_CRYPTO_SE_H */