psa_crypto_slot_management.h

00001 /*
00002  *  PSA crypto layer on top of Mbed TLS crypto
00003  */
00004 /*  Copyright (C) 2018, 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_SLOT_MANAGEMENT_H
00023 #define PSA_CRYPTO_SLOT_MANAGEMENT_H
00024 
00025 #include "psa/crypto.h"
00026 #include "psa_crypto_se.h"
00027 
00028 /* Number of key slots (plus one because 0 is not used).
00029  * The value is a compile-time constant for now, for simplicity. */
00030 #define PSA_KEY_SLOT_COUNT 32
00031 
00032 /** Access a key slot at the given handle.
00033  *
00034  * \param handle        Key handle to query.
00035  * \param[out] p_slot   On success, `*p_slot` contains a pointer to the
00036  *                      key slot in memory designated by \p handle.
00037  *
00038  * \retval PSA_SUCCESS
00039  *         Success: \p handle is a handle to `*p_slot`. Note that `*p_slot`
00040  *         may be empty or occupied.
00041  * \retval PSA_ERROR_INVALID_HANDLE
00042  *         \p handle is out of range or is not in use.
00043  * \retval PSA_ERROR_BAD_STATE
00044  *         The library has not been initialized.
00045  */
00046 psa_status_t psa_get_key_slot( psa_key_handle_t handle,
00047                                psa_key_slot_t **p_slot );
00048 
00049 /** Initialize the key slot structures.
00050  *
00051  * \retval PSA_SUCCESS
00052  *         Currently this function always succeeds.
00053  */
00054 psa_status_t psa_initialize_key_slots( void );
00055 
00056 /** Delete all data from key slots in memory.
00057  *
00058  * This does not affect persistent storage. */
00059 void psa_wipe_all_key_slots( void );
00060 
00061 /** Find a free key slot.
00062  *
00063  * This function returns a key slot that is available for use and is in its
00064  * ground state (all-bits-zero).
00065  *
00066  * \param[out] handle   On success, a slot number that can be used as a
00067  *                      handle to the slot.
00068  * \param[out] p_slot   On success, a pointer to the slot.
00069  *
00070  * \retval #PSA_SUCCESS
00071  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
00072  * \retval #PSA_ERROR_BAD_STATE
00073  */
00074 psa_status_t psa_get_empty_key_slot( psa_key_handle_t *handle,
00075                                      psa_key_slot_t **p_slot );
00076 
00077 /** Test whether a lifetime designates a key in an external cryptoprocessor.
00078  *
00079  * \param lifetime      The lifetime to test.
00080  *
00081  * \retval 1
00082  *         The lifetime designates an external key. There should be a
00083  *         registered driver for this lifetime, otherwise the key cannot
00084  *         be created or manipulated.
00085  * \retval 0
00086  *         The lifetime designates a key that is volatile or in internal
00087  *         storage.
00088  */
00089 static inline int psa_key_lifetime_is_external( psa_key_lifetime_t lifetime )
00090 {
00091     return( lifetime != PSA_KEY_LIFETIME_VOLATILE &&
00092             lifetime != PSA_KEY_LIFETIME_PERSISTENT );
00093 }
00094 
00095 /** Test whether the given parameters are acceptable for a persistent key.
00096  *
00097  * This function does not access the storage in any way. It only tests
00098  * whether the parameters are meaningful and permitted by general policy.
00099  * It does not test whether the a file by the given id exists or could be
00100  * created.
00101  *
00102  * If the key is in external storage, this function returns the corresponding
00103  * driver.
00104  *
00105  * \param lifetime      The lifetime to test.
00106  * \param id            The key id to test.
00107  * \param[out] p_drv    On output, if \p lifetime designates a key
00108  *                      in an external processor, \c *p_drv is a pointer
00109  *                      to the driver table entry fot this lifetime.
00110  *                      If \p lifetime designates a transparent key,
00111  *                      \c *p_drv is \c NULL.
00112  * \param creating      0 if attempting to open an existing key.
00113  *                      Nonzero if attempting to create a key.
00114  *
00115  * \retval PSA_SUCCESS
00116  *         The given parameters are valid.
00117  * \retval PSA_ERROR_INVALID_ARGUMENT
00118  *         \p lifetime is volatile or is invalid.
00119  * \retval PSA_ERROR_INVALID_ARGUMENT
00120  *         \p id is invalid.
00121  */
00122 psa_status_t psa_validate_persistent_key_parameters(
00123     psa_key_lifetime_t lifetime,
00124     psa_key_file_id_t id,
00125     psa_se_drv_table_entry_t **p_drv,
00126     int creating );
00127 
00128 
00129 #endif /* PSA_CRYPTO_SLOT_MANAGEMENT_H */