psa_crypto_storage.h

00001 /**
00002  * \file psa_crypto_storage.h
00003  *
00004  * \brief PSA cryptography module: Mbed TLS key storage
00005  */
00006 /*
00007  *  Copyright (C) 2018, ARM Limited, All Rights Reserved
00008  *  SPDX-License-Identifier: Apache-2.0
00009  *
00010  *  Licensed under the Apache License, Version 2.0 (the "License"); you may
00011  *  not use this file except in compliance with the License.
00012  *  You may obtain a copy of the License at
00013  *
00014  *  http://www.apache.org/licenses/LICENSE-2.0
00015  *
00016  *  Unless required by applicable law or agreed to in writing, software
00017  *  distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
00018  *  WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00019  *  See the License for the specific language governing permissions and
00020  *  limitations under the License.
00021  *
00022  *  This file is part of mbed TLS (https://tls.mbed.org)
00023  */
00024 
00025 #ifndef PSA_CRYPTO_STORAGE_H
00026 #define PSA_CRYPTO_STORAGE_H
00027 
00028 #ifdef __cplusplus
00029 extern "C" {
00030 #endif
00031 
00032 #include "psa/crypto.h"
00033 #include "psa/crypto_se_driver.h"
00034 
00035 #include <stdint.h>
00036 #include <string.h>
00037 
00038 /* Limit the maximum key size in storage. This should have no effect
00039  * since the key size is limited in memory. */
00040 #define PSA_CRYPTO_MAX_STORAGE_SIZE ( PSA_BITS_TO_BYTES( PSA_MAX_KEY_BITS ) )
00041 /* Sanity check: a file size must fit in 32 bits. Allow a generous
00042  * 64kB of metadata. */
00043 #if PSA_CRYPTO_MAX_STORAGE_SIZE > 0xffff0000
00044 #error PSA_CRYPTO_MAX_STORAGE_SIZE > 0xffff0000
00045 #endif
00046 
00047 /** The maximum permitted persistent slot number.
00048  *
00049  * In Mbed Crypto 0.1.0b:
00050  * - Using the file backend, all key ids are ok except 0.
00051  * - Using the ITS backend, all key ids are ok except 0xFFFFFF52
00052  *   (#PSA_CRYPTO_ITS_RANDOM_SEED_UID) for which the file contains the
00053  *   device's random seed (if this feature is enabled).
00054  * - Only key ids from 1 to #PSA_KEY_SLOT_COUNT are actually used.
00055  *
00056  * Since we need to preserve the random seed, avoid using that key slot.
00057  * Reserve a whole range of key slots just in case something else comes up.
00058  *
00059  * This limitation will probably become moot when we implement client
00060  * separation for key storage.
00061  */
00062 #define PSA_MAX_PERSISTENT_KEY_IDENTIFIER PSA_KEY_ID_VENDOR_MAX
00063 
00064 /**
00065  * \brief Checks if persistent data is stored for the given key slot number
00066  *
00067  * This function checks if any key data or metadata exists for the key slot in
00068  * the persistent storage.
00069  *
00070  * \param key           Persistent identifier to check.
00071  *
00072  * \retval 0
00073  *         No persistent data present for slot number
00074  * \retval 1
00075  *         Persistent data present for slot number
00076  */
00077 int psa_is_key_present_in_storage( const psa_key_file_id_t key );
00078 
00079 /**
00080  * \brief Format key data and metadata and save to a location for given key
00081  *        slot.
00082  *
00083  * This function formats the key data and metadata and saves it to a
00084  * persistent storage backend. The storage location corresponding to the
00085  * key slot must be empty, otherwise this function will fail. This function
00086  * should be called after psa_import_key_into_slot() to ensure the
00087  * persistent key is not saved into a storage location corresponding to an
00088  * already occupied non-persistent key, as well as validating the key data.
00089  *
00090  *
00091  * \param[in] attr          The attributes of the key to save.
00092  *                          The key identifier field in the attributes
00093  *                          determines the key's location.
00094  * \param[in] data          Buffer containing the key data.
00095  * \param data_length       The number of bytes that make up the key data.
00096  *
00097  * \retval PSA_SUCCESS
00098  * \retval PSA_ERROR_INSUFFICIENT_MEMORY
00099  * \retval PSA_ERROR_INSUFFICIENT_STORAGE
00100  * \retval PSA_ERROR_STORAGE_FAILURE
00101  * \retval PSA_ERROR_ALREADY_EXISTS
00102  */
00103 psa_status_t psa_save_persistent_key( const psa_core_key_attributes_t *attr,
00104                                       const uint8_t *data,
00105                                       const size_t data_length );
00106 
00107 /**
00108  * \brief Parses key data and metadata and load persistent key for given
00109  * key slot number.
00110  *
00111  * This function reads from a storage backend, parses the key data and
00112  * metadata and writes them to the appropriate output parameters.
00113  *
00114  * Note: This function allocates a buffer and returns a pointer to it through
00115  * the data parameter. psa_free_persistent_key_data() must be called after
00116  * this function to zeroize and free this buffer, regardless of whether this
00117  * function succeeds or fails.
00118  *
00119  * \param[in,out] attr      On input, the key identifier field identifies
00120  *                          the key to load. Other fields are ignored.
00121  *                          On success, the attribute structure contains
00122  *                          the key metadata that was loaded from storage.
00123  * \param[out] data         Pointer to an allocated key data buffer on return.
00124  * \param[out] data_length  The number of bytes that make up the key data.
00125  *
00126  * \retval PSA_SUCCESS
00127  * \retval PSA_ERROR_INSUFFICIENT_MEMORY
00128  * \retval PSA_ERROR_STORAGE_FAILURE
00129  * \retval PSA_ERROR_DOES_NOT_EXIST
00130  */
00131 psa_status_t psa_load_persistent_key( psa_core_key_attributes_t *attr,
00132                                       uint8_t **data,
00133                                       size_t *data_length );
00134 
00135 /**
00136  * \brief Remove persistent data for the given key slot number.
00137  *
00138  * \param key           Persistent identifier of the key to remove
00139  *                      from persistent storage.
00140  *
00141  * \retval PSA_SUCCESS
00142  *         The key was successfully removed,
00143  *         or the key did not exist.
00144  * \retval PSA_ERROR_STORAGE_FAILURE
00145  */
00146 psa_status_t psa_destroy_persistent_key( const psa_key_file_id_t key );
00147 
00148 /**
00149  * \brief Free the temporary buffer allocated by psa_load_persistent_key().
00150  *
00151  * This function must be called at some point after psa_load_persistent_key()
00152  * to zeroize and free the memory allocated to the buffer in that function.
00153  *
00154  * \param key_data        Buffer for the key data.
00155  * \param key_data_length Size of the key data buffer.
00156  *
00157  */
00158 void psa_free_persistent_key_data( uint8_t *key_data, size_t key_data_length );
00159 
00160 /**
00161  * \brief Formats key data and metadata for persistent storage
00162  *
00163  * \param[in] data          Buffer containing the key data.
00164  * \param data_length       Length of the key data buffer.
00165  * \param[in] attr          The core attributes of the key.
00166  * \param[out] storage_data Output buffer for the formatted data.
00167  *
00168  */
00169 void psa_format_key_data_for_storage( const uint8_t *data,
00170                                       const size_t data_length,
00171                                       const psa_core_key_attributes_t *attr,
00172                                       uint8_t *storage_data );
00173 
00174 /**
00175  * \brief Parses persistent storage data into key data and metadata
00176  *
00177  * \param[in] storage_data     Buffer for the storage data.
00178  * \param storage_data_length  Length of the storage data buffer
00179  * \param[out] key_data        On output, pointer to a newly allocated buffer
00180  *                             containing the key data. This must be freed
00181  *                             using psa_free_persistent_key_data()
00182  * \param[out] key_data_length Length of the key data buffer
00183  * \param[out] attr            On success, the attribute structure is filled
00184  *                             with the loaded key metadata.
00185  *
00186  * \retval PSA_SUCCESS
00187  * \retval PSA_ERROR_INSUFFICIENT_STORAGE
00188  * \retval PSA_ERROR_INSUFFICIENT_MEMORY
00189  * \retval PSA_ERROR_STORAGE_FAILURE
00190  */
00191 psa_status_t psa_parse_key_data_from_storage( const uint8_t *storage_data,
00192                                               size_t storage_data_length,
00193                                               uint8_t **key_data,
00194                                               size_t *key_data_length,
00195                                               psa_core_key_attributes_t *attr );
00196 
00197 #if defined(MBEDTLS_PSA_CRYPTO_SE_C)
00198 /** This symbol is defined if transaction support is required. */
00199 #define PSA_CRYPTO_STORAGE_HAS_TRANSACTIONS
00200 #endif
00201 
00202 #if defined(PSA_CRYPTO_STORAGE_HAS_TRANSACTIONS)
00203 
00204 /** The type of transaction that is in progress.
00205  */
00206 /* This is an integer type rather than an enum for two reasons: to support
00207  * unknown values when loading a transaction file, and to ensure that the
00208  * type has a known size.
00209  */
00210 typedef uint16_t psa_crypto_transaction_type_t;
00211 
00212 /** No transaction is in progress.
00213  *
00214  * This has the value 0, so zero-initialization sets a transaction's type to
00215  * this value.
00216  */
00217 #define PSA_CRYPTO_TRANSACTION_NONE             ( (psa_crypto_transaction_type_t) 0x0000 )
00218 
00219 /** A key creation transaction.
00220  *
00221  * This is only used for keys in an external cryptoprocessor (secure element).
00222  * Keys in RAM or in internal storage are created atomically in storage
00223  * (simple file creation), so they do not need a transaction mechanism.
00224  */
00225 #define PSA_CRYPTO_TRANSACTION_CREATE_KEY       ( (psa_crypto_transaction_type_t) 0x0001 )
00226 
00227 /** A key destruction transaction.
00228  *
00229  * This is only used for keys in an external cryptoprocessor (secure element).
00230  * Keys in RAM or in internal storage are destroyed atomically in storage
00231  * (simple file deletion), so they do not need a transaction mechanism.
00232  */
00233 #define PSA_CRYPTO_TRANSACTION_DESTROY_KEY      ( (psa_crypto_transaction_type_t) 0x0002 )
00234 
00235 /** Transaction data.
00236  *
00237  * This type is designed to be serialized by writing the memory representation
00238  * and reading it back on the same device.
00239  *
00240  * \note The transaction mechanism is designed for a single active transaction
00241  *       at a time. The transaction object is #psa_crypto_transaction.
00242  *
00243  * \note If an API call starts a transaction, it must complete this transaction
00244  *       before returning to the application.
00245  *
00246  * The lifetime of a transaction is the following (note that only one
00247  * transaction may be active at a time):
00248  *
00249  * -# Call psa_crypto_prepare_transaction() to initialize the transaction
00250  *    object in memory and declare the type of transaction that is starting.
00251  * -# Fill in the type-specific fields of #psa_crypto_transaction.
00252  * -# Call psa_crypto_save_transaction() to start the transaction. This
00253  *    saves the transaction data to internal storage.
00254  * -# Perform the work of the transaction by modifying files, contacting
00255  *    external entities, or whatever needs doing. Note that the transaction
00256  *    may be interrupted by a power failure, so you need to have a way
00257  *    recover from interruptions either by undoing what has been done
00258  *    so far or by resuming where you left off.
00259  * -# If there are intermediate stages in the transaction, update
00260  *    the fields of #psa_crypto_transaction and call
00261  *    psa_crypto_save_transaction() again when each stage is reached.
00262  * -# When the transaction is over, call psa_crypto_stop_transaction() to
00263  *    remove the transaction data in storage and in memory.
00264  *
00265  * If the system crashes while a transaction is in progress, psa_crypto_init()
00266  * calls psa_crypto_load_transaction() and takes care of completing or
00267  * rewinding the transaction. This is done in psa_crypto_recover_transaction()
00268  * in psa_crypto.c. If you add a new type of transaction, be
00269  * sure to add code for it in psa_crypto_recover_transaction().
00270  */
00271 typedef union
00272 {
00273     /* Each element of this union must have the following properties
00274      * to facilitate serialization and deserialization:
00275      *
00276      * - The element is a struct.
00277      * - The first field of the struct is `psa_crypto_transaction_type_t type`.
00278      * - Elements of the struct are arranged such a way that there is
00279      *   no padding.
00280      */
00281     struct psa_crypto_transaction_unknown_s
00282     {
00283         psa_crypto_transaction_type_t type;
00284         uint16_t unused1;
00285         uint32_t unused2;
00286         uint64_t unused3;
00287         uint64_t unused4;
00288     } unknown;
00289     /* ::type is #PSA_CRYPTO_TRANSACTION_CREATE_KEY or
00290      * #PSA_CRYPTO_TRANSACTION_DESTROY_KEY. */
00291     struct psa_crypto_transaction_key_s
00292     {
00293         psa_crypto_transaction_type_t type;
00294         uint16_t unused1;
00295         psa_key_lifetime_t lifetime;
00296         psa_key_slot_number_t slot;
00297         psa_key_id_t id;
00298     } key;
00299 } psa_crypto_transaction_t;
00300 
00301 /** The single active transaction.
00302  */
00303 extern psa_crypto_transaction_t psa_crypto_transaction;
00304 
00305 /** Prepare for a transaction.
00306  *
00307  * There must not be an ongoing transaction.
00308  *
00309  * \param type          The type of transaction to start.
00310  */
00311 static inline void psa_crypto_prepare_transaction(
00312     psa_crypto_transaction_type_t type )
00313 {
00314     psa_crypto_transaction.unknown.type = type;
00315 }
00316 
00317 /** Save the transaction data to storage.
00318  *
00319  * You may call this function multiple times during a transaction to
00320  * atomically update the transaction state.
00321  *
00322  * \retval #PSA_SUCCESS
00323  * \retval #PSA_ERROR_INSUFFICIENT_STORAGE
00324  * \retval #PSA_ERROR_STORAGE_FAILURE
00325  */
00326 psa_status_t psa_crypto_save_transaction( void );
00327 
00328 /** Load the transaction data from storage, if any.
00329  *
00330  * This function is meant to be called from psa_crypto_init() to recover
00331  * in case a transaction was interrupted by a system crash.
00332  *
00333  * \retval #PSA_SUCCESS
00334  *         The data about the ongoing transaction has been loaded to
00335  *         #psa_crypto_transaction.
00336  * \retval #PSA_ERROR_DOES_NOT_EXIST
00337  *         There is no ongoing transaction.
00338  * \retval #PSA_ERROR_STORAGE_FAILURE
00339  */
00340 psa_status_t psa_crypto_load_transaction( void );
00341 
00342 /** Indicate that the current transaction is finished.
00343  *
00344  * Call this function at the very end of transaction processing.
00345  * This function does not "commit" or "abort" the transaction: the storage
00346  * subsystem has no concept of "commit" and "abort", just saving and
00347  * removing the transaction information in storage.
00348  *
00349  * This function erases the transaction data in storage (if any) and
00350  * resets the transaction data in memory.
00351  *
00352  * \retval #PSA_SUCCESS
00353  *         There was transaction data in storage.
00354  * \retval #PSA_ERROR_DOES_NOT_EXIST
00355  *         There was no transaction data in storage.
00356  * \retval #PSA_ERROR_STORAGE_FAILURE
00357  *         It was impossible to determine whether there was transaction data
00358  *         in storage, or the transaction data could not be erased.
00359  */
00360 psa_status_t psa_crypto_stop_transaction( void );
00361 
00362 /** The ITS file identifier for the transaction data.
00363  *
00364  * 0xffffffNN = special file; 0x74 = 't' for transaction.
00365  */
00366 #define PSA_CRYPTO_ITS_TRANSACTION_UID ( (psa_key_id_t) 0xffffff74 )
00367 
00368 #endif /* PSA_CRYPTO_STORAGE_HAS_TRANSACTIONS */
00369 
00370 #if defined(MBEDTLS_PSA_INJECT_ENTROPY)
00371 /** Backend side of mbedtls_psa_inject_entropy().
00372  *
00373  * This function stores the supplied data into the entropy seed file.
00374  *
00375  * \retval #PSA_SUCCESS
00376  *         Success
00377  * \retval #PSA_ERROR_STORAGE_FAILURE
00378  * \retval #PSA_ERROR_INSUFFICIENT_STORAGE
00379  * \retval #PSA_ERROR_NOT_PERMITTED
00380  *         The entropy seed file already exists.
00381  */
00382 psa_status_t mbedtls_psa_storage_inject_entropy( const unsigned char *seed,
00383                                                  size_t seed_size );
00384 #endif /* MBEDTLS_PSA_INJECT_ENTROPY */
00385 
00386 #ifdef __cplusplus
00387 }
00388 #endif
00389 
00390 #endif /* PSA_CRYPTO_STORAGE_H */