| /* |
| * PSA crypto core internal interfaces |
| */ |
| /* |
| * Copyright The Mbed TLS Contributors |
| * SPDX-License-Identifier: Apache-2.0 |
| * |
| * 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 PSA_CRYPTO_CORE_H |
| #define PSA_CRYPTO_CORE_H |
| |
| #include "mbedtls/build_info.h" |
| |
| #include "psa/crypto.h" |
| #include "psa/crypto_se_driver.h" |
| |
| /** Constant-time buffer comparison |
| * |
| * \param[in] a Left-hand buffer for comparison. |
| * \param[in] b Right-hand buffer for comparison. |
| * \param n Amount of bytes to compare. |
| * |
| * \return 0 if the buffer contents are equal, non-zero otherwise |
| */ |
| static inline int mbedtls_psa_safer_memcmp( |
| const uint8_t *a, const uint8_t *b, size_t n ) |
| { |
| size_t i; |
| unsigned char diff = 0; |
| |
| for( i = 0; i < n; i++ ) |
| diff |= a[i] ^ b[i]; |
| |
| return( diff ); |
| } |
| |
| /** The data structure representing a key slot, containing key material |
| * and metadata for one key. |
| */ |
| typedef struct |
| { |
| psa_core_key_attributes_t attr; |
| |
| /* |
| * Number of locks on the key slot held by the library. |
| * |
| * This counter is incremented by one each time a library function |
| * retrieves through one of the dedicated internal API a pointer to the |
| * key slot. |
| * |
| * This counter is decremented by one each time a library function stops |
| * accessing the key slot and states it by calling the |
| * psa_unlock_key_slot() API. |
| * |
| * This counter is used to prevent resetting the key slot while the library |
| * may access it. For example, such control is needed in the following |
| * scenarios: |
| * . In case of key slot starvation, all key slots contain the description |
| * of a key, and the library asks for the description of a persistent |
| * key not present in the key slots, the key slots currently accessed by |
| * the library cannot be reclaimed to free a key slot to load the |
| * persistent key. |
| * . In case of a multi-threaded application where one thread asks to close |
| * or purge or destroy a key while it is in used by the library through |
| * another thread. |
| */ |
| size_t lock_count; |
| |
| /* Dynamically allocated key data buffer. |
| * Format as specified in psa_export_key(). */ |
| struct key_data |
| { |
| uint8_t *data; |
| size_t bytes; |
| } key; |
| } psa_key_slot_t; |
| |
| /* A mask of key attribute flags used only internally. |
| * Currently there aren't any. */ |
| #define PSA_KA_MASK_INTERNAL_ONLY ( \ |
| 0 ) |
| |
| /** Test whether a key slot is occupied. |
| * |
| * A key slot is occupied iff the key type is nonzero. This works because |
| * no valid key can have 0 as its key type. |
| * |
| * \param[in] slot The key slot to test. |
| * |
| * \return 1 if the slot is occupied, 0 otherwise. |
| */ |
| static inline int psa_is_key_slot_occupied( const psa_key_slot_t *slot ) |
| { |
| return( slot->attr.type != 0 ); |
| } |
| |
| /** Test whether a key slot is locked. |
| * |
| * A key slot is locked iff its lock counter is strictly greater than 0. |
| * |
| * \param[in] slot The key slot to test. |
| * |
| * \return 1 if the slot is locked, 0 otherwise. |
| */ |
| static inline int psa_is_key_slot_locked( const psa_key_slot_t *slot ) |
| { |
| return( slot->lock_count > 0 ); |
| } |
| |
| /** Retrieve flags from psa_key_slot_t::attr::core::flags. |
| * |
| * \param[in] slot The key slot to query. |
| * \param mask The mask of bits to extract. |
| * |
| * \return The key attribute flags in the given slot, |
| * bitwise-anded with \p mask. |
| */ |
| static inline uint16_t psa_key_slot_get_flags( const psa_key_slot_t *slot, |
| uint16_t mask ) |
| { |
| return( slot->attr.flags & mask ); |
| } |
| |
| /** Set flags in psa_key_slot_t::attr::core::flags. |
| * |
| * \param[in,out] slot The key slot to modify. |
| * \param mask The mask of bits to modify. |
| * \param value The new value of the selected bits. |
| */ |
| static inline void psa_key_slot_set_flags( psa_key_slot_t *slot, |
| uint16_t mask, |
| uint16_t value ) |
| { |
| slot->attr.flags = ( ( ~mask & slot->attr.flags ) | |
| ( mask & value ) ); |
| } |
| |
| /** Turn on flags in psa_key_slot_t::attr::core::flags. |
| * |
| * \param[in,out] slot The key slot to modify. |
| * \param mask The mask of bits to set. |
| */ |
| static inline void psa_key_slot_set_bits_in_flags( psa_key_slot_t *slot, |
| uint16_t mask ) |
| { |
| slot->attr.flags |= mask; |
| } |
| |
| /** Turn off flags in psa_key_slot_t::attr::core::flags. |
| * |
| * \param[in,out] slot The key slot to modify. |
| * \param mask The mask of bits to clear. |
| */ |
| static inline void psa_key_slot_clear_bits( psa_key_slot_t *slot, |
| uint16_t mask ) |
| { |
| slot->attr.flags &= ~mask; |
| } |
| |
| #if defined(MBEDTLS_PSA_CRYPTO_SE_C) |
| /** Get the SE slot number of a key from the key slot storing its description. |
| * |
| * \param[in] slot The key slot to query. This must be a key slot storing |
| * the description of a key of a dynamically registered |
| * secure element, otherwise the behaviour is undefined. |
| */ |
| static inline psa_key_slot_number_t psa_key_slot_get_slot_number( |
| const psa_key_slot_t *slot ) |
| { |
| return( *( (psa_key_slot_number_t *)( slot->key.data ) ) ); |
| } |
| #endif |
| |
| /** Completely wipe a slot in memory, including its policy. |
| * |
| * Persistent storage is not affected. |
| * |
| * \param[in,out] slot The key slot to wipe. |
| * |
| * \retval #PSA_SUCCESS |
| * Success. This includes the case of a key slot that was |
| * already fully wiped. |
| * \retval #PSA_ERROR_CORRUPTION_DETECTED |
| */ |
| psa_status_t psa_wipe_key_slot( psa_key_slot_t *slot ); |
| |
| /** Try to allocate a buffer to an empty key slot. |
| * |
| * \param[in,out] slot Key slot to attach buffer to. |
| * \param[in] buffer_length Requested size of the buffer. |
| * |
| * \retval #PSA_SUCCESS |
| * The buffer has been successfully allocated. |
| * \retval #PSA_ERROR_INSUFFICIENT_MEMORY |
| * Not enough memory was available for allocation. |
| * \retval #PSA_ERROR_ALREADY_EXISTS |
| * Trying to allocate a buffer to a non-empty key slot. |
| */ |
| psa_status_t psa_allocate_buffer_to_slot( psa_key_slot_t *slot, |
| size_t buffer_length ); |
| |
| /** Wipe key data from a slot. Preserves metadata such as the policy. */ |
| psa_status_t psa_remove_key_data_from_memory( psa_key_slot_t *slot ); |
| |
| /** Copy key data (in export format) into an empty key slot. |
| * |
| * This function assumes that the slot does not contain |
| * any key material yet. On failure, the slot content is unchanged. |
| * |
| * \param[in,out] slot Key slot to copy the key into. |
| * \param[in] data Buffer containing the key material. |
| * \param data_length Size of the key buffer. |
| * |
| * \retval #PSA_SUCCESS |
| * The key has been copied successfully. |
| * \retval #PSA_ERROR_INSUFFICIENT_MEMORY |
| * Not enough memory was available for allocation of the |
| * copy buffer. |
| * \retval #PSA_ERROR_ALREADY_EXISTS |
| * There was other key material already present in the slot. |
| */ |
| psa_status_t psa_copy_key_material_into_slot( psa_key_slot_t *slot, |
| const uint8_t *data, |
| size_t data_length ); |
| |
| /** Convert an mbed TLS error code to a PSA error code |
| * |
| * \note This function is provided solely for the convenience of |
| * Mbed TLS and may be removed at any time without notice. |
| * |
| * \param ret An mbed TLS-thrown error code |
| * |
| * \return The corresponding PSA error code |
| */ |
| psa_status_t mbedtls_to_psa_error( int ret ); |
| |
| /** Get Mbed TLS cipher information given the cipher algorithm PSA identifier |
| * as well as the PSA type and size of the key to be used with the cipher |
| * algorithm. |
| * |
| * \param alg PSA cipher algorithm identifier |
| * \param key_type PSA key type |
| * \param key_bits Size of the key in bits |
| * \param[out] cipher_id Mbed TLS cipher algorithm identifier |
| * |
| * \return The Mbed TLS cipher information of the cipher algorithm. |
| * \c NULL if the PSA cipher algorithm is not supported. |
| */ |
| const mbedtls_cipher_info_t *mbedtls_cipher_info_from_psa( |
| psa_algorithm_t alg, psa_key_type_t key_type, size_t key_bits, |
| mbedtls_cipher_id_t *cipher_id ); |
| |
| /** Import a key in binary format. |
| * |
| * \note The signature of this function is that of a PSA driver |
| * import_key entry point. This function behaves as an import_key |
| * entry point as defined in the PSA driver interface specification for |
| * transparent drivers. |
| * |
| * \param[in] attributes The attributes for the key to import. |
| * \param[in] data The buffer containing the key data in import |
| * format. |
| * \param[in] data_length Size of the \p data buffer in bytes. |
| * \param[out] key_buffer The buffer to contain the key data in output |
| * format upon successful return. |
| * \param[in] key_buffer_size Size of the \p key_buffer buffer in bytes. This |
| * size is greater or equal to \p data_length. |
| * \param[out] key_buffer_length The length of the data written in \p |
| * key_buffer in bytes. |
| * \param[out] bits The key size in number of bits. |
| * |
| * \retval #PSA_SUCCESS The key was imported successfully. |
| * \retval #PSA_ERROR_INVALID_ARGUMENT |
| * The key data is not correctly formatted. |
| * \retval #PSA_ERROR_NOT_SUPPORTED |
| * \retval #PSA_ERROR_INSUFFICIENT_MEMORY |
| * \retval #PSA_ERROR_CORRUPTION_DETECTED |
| */ |
| psa_status_t psa_import_key_into_slot( |
| const psa_key_attributes_t *attributes, |
| const uint8_t *data, size_t data_length, |
| uint8_t *key_buffer, size_t key_buffer_size, |
| size_t *key_buffer_length, size_t *bits ); |
| |
| /** Export a key in binary format |
| * |
| * \note The signature of this function is that of a PSA driver export_key |
| * entry point. This function behaves as an export_key entry point as |
| * defined in the PSA driver interface specification. |
| * |
| * \param[in] attributes The attributes for the key to export. |
| * \param[in] key_buffer Material or context of the key to export. |
| * \param[in] key_buffer_size Size of the \p key_buffer buffer in bytes. |
| * \param[out] data Buffer where the key data is to be written. |
| * \param[in] data_size Size of the \p data buffer in bytes. |
| * \param[out] data_length On success, the number of bytes written in |
| * \p data |
| * |
| * \retval #PSA_SUCCESS The key was exported successfully. |
| * \retval #PSA_ERROR_NOT_SUPPORTED |
| * \retval #PSA_ERROR_COMMUNICATION_FAILURE |
| * \retval #PSA_ERROR_HARDWARE_FAILURE |
| * \retval #PSA_ERROR_CORRUPTION_DETECTED |
| * \retval #PSA_ERROR_STORAGE_FAILURE |
| * \retval #PSA_ERROR_INSUFFICIENT_MEMORY |
| */ |
| psa_status_t psa_export_key_internal( |
| const psa_key_attributes_t *attributes, |
| const uint8_t *key_buffer, size_t key_buffer_size, |
| uint8_t *data, size_t data_size, size_t *data_length ); |
| |
| /** Export a public key or the public part of a key pair in binary format. |
| * |
| * \note The signature of this function is that of a PSA driver |
| * export_public_key entry point. This function behaves as an |
| * export_public_key entry point as defined in the PSA driver interface |
| * specification. |
| * |
| * \param[in] attributes The attributes for the key to export. |
| * \param[in] key_buffer Material or context of the key to export. |
| * \param[in] key_buffer_size Size of the \p key_buffer buffer in bytes. |
| * \param[out] data Buffer where the key data is to be written. |
| * \param[in] data_size Size of the \p data buffer in bytes. |
| * \param[out] data_length On success, the number of bytes written in |
| * \p data |
| * |
| * \retval #PSA_SUCCESS The public key was exported successfully. |
| * \retval #PSA_ERROR_NOT_SUPPORTED |
| * \retval #PSA_ERROR_COMMUNICATION_FAILURE |
| * \retval #PSA_ERROR_HARDWARE_FAILURE |
| * \retval #PSA_ERROR_CORRUPTION_DETECTED |
| * \retval #PSA_ERROR_STORAGE_FAILURE |
| * \retval #PSA_ERROR_INSUFFICIENT_MEMORY |
| */ |
| psa_status_t psa_export_public_key_internal( |
| const psa_key_attributes_t *attributes, |
| const uint8_t *key_buffer, size_t key_buffer_size, |
| uint8_t *data, size_t data_size, size_t *data_length ); |
| |
| /** |
| * \brief Generate a key. |
| * |
| * \note The signature of the function is that of a PSA driver generate_key |
| * entry point. |
| * |
| * \param[in] attributes The attributes for the key to generate. |
| * \param[out] key_buffer Buffer where the key data is to be written. |
| * \param[in] key_buffer_size Size of \p key_buffer in bytes. |
| * \param[out] key_buffer_length On success, the number of bytes written in |
| * \p key_buffer. |
| * |
| * \retval #PSA_SUCCESS |
| * The key was generated successfully. |
| * \retval #PSA_ERROR_INVALID_ARGUMENT |
| * \retval #PSA_ERROR_NOT_SUPPORTED |
| * Key size in bits or type not supported. |
| * \retval #PSA_ERROR_BUFFER_TOO_SMALL |
| * The size of \p key_buffer is too small. |
| */ |
| psa_status_t psa_generate_key_internal( const psa_key_attributes_t *attributes, |
| uint8_t *key_buffer, |
| size_t key_buffer_size, |
| size_t *key_buffer_length ); |
| |
| /** Sign a message with a private key. For hash-and-sign algorithms, |
| * this includes the hashing step. |
| * |
| * \note The signature of this function is that of a PSA driver |
| * sign_message entry point. This function behaves as a sign_message |
| * entry point as defined in the PSA driver interface specification for |
| * transparent drivers. |
| * |
| * \note This function will call the driver for psa_sign_hash |
| * and go through driver dispatch again. |
| * |
| * \param[in] attributes The attributes of the key to use for the |
| * operation. |
| * \param[in] key_buffer The buffer containing the key context. |
| * \param[in] key_buffer_size Size of the \p key_buffer buffer in bytes. |
| * \param[in] alg A signature algorithm that is compatible with |
| * the type of the key. |
| * \param[in] input The input message to sign. |
| * \param[in] input_length Size of the \p input buffer in bytes. |
| * \param[out] signature Buffer where the signature is to be written. |
| * \param[in] signature_size Size of the \p signature buffer in bytes. |
| * \param[out] signature_length On success, the number of bytes |
| * that make up the returned signature value. |
| * |
| * \retval #PSA_SUCCESS |
| * \retval #PSA_ERROR_BUFFER_TOO_SMALL |
| * The size of the \p signature buffer is too small. You can |
| * determine a sufficient buffer size by calling |
| * #PSA_SIGN_OUTPUT_SIZE(\c key_type, \c key_bits, \p alg) |
| * where \c key_type and \c key_bits are the type and bit-size |
| * respectively of the key. |
| * \retval #PSA_ERROR_NOT_SUPPORTED |
| * \retval #PSA_ERROR_INVALID_ARGUMENT |
| * \retval #PSA_ERROR_INSUFFICIENT_MEMORY |
| * \retval #PSA_ERROR_CORRUPTION_DETECTED |
| * \retval #PSA_ERROR_INSUFFICIENT_ENTROPY |
| */ |
| psa_status_t psa_sign_message_builtin( |
| const psa_key_attributes_t *attributes, |
| const uint8_t *key_buffer, size_t key_buffer_size, |
| psa_algorithm_t alg, const uint8_t *input, size_t input_length, |
| uint8_t *signature, size_t signature_size, size_t *signature_length ); |
| |
| /** Verify the signature of a message with a public key, using |
| * a hash-and-sign verification algorithm. |
| * |
| * \note The signature of this function is that of a PSA driver |
| * verify_message entry point. This function behaves as a verify_message |
| * entry point as defined in the PSA driver interface specification for |
| * transparent drivers. |
| * |
| * \note This function will call the driver for psa_verify_hash |
| * and go through driver dispatch again. |
| * |
| * \param[in] attributes The attributes of the key to use for the |
| * operation. |
| * \param[in] key_buffer The buffer containing the key context. |
| * \param[in] key_buffer_size Size of the \p key_buffer buffer in bytes. |
| * \param[in] alg A signature algorithm that is compatible with |
| * the type of the key. |
| * \param[in] input The message whose signature is to be verified. |
| * \param[in] input_length Size of the \p input buffer in bytes. |
| * \param[in] signature Buffer containing the signature to verify. |
| * \param[in] signature_length Size of the \p signature buffer in bytes. |
| * |
| * \retval #PSA_SUCCESS |
| * The signature is valid. |
| * \retval #PSA_ERROR_INVALID_SIGNATURE |
| * The calculation was performed successfully, but the passed |
| * signature is not a valid signature. |
| * \retval #PSA_ERROR_NOT_SUPPORTED |
| * \retval #PSA_ERROR_INVALID_ARGUMENT |
| * \retval #PSA_ERROR_INSUFFICIENT_MEMORY |
| */ |
| psa_status_t psa_verify_message_builtin( |
| const psa_key_attributes_t *attributes, |
| const uint8_t *key_buffer, size_t key_buffer_size, |
| psa_algorithm_t alg, const uint8_t *input, size_t input_length, |
| const uint8_t *signature, size_t signature_length ); |
| |
| /** Sign an already-calculated hash with a private key. |
| * |
| * \note The signature of this function is that of a PSA driver |
| * sign_hash entry point. This function behaves as a sign_hash |
| * entry point as defined in the PSA driver interface specification for |
| * transparent drivers. |
| * |
| * \param[in] attributes The attributes of the key to use for the |
| * operation. |
| * \param[in] key_buffer The buffer containing the key context. |
| * \param[in] key_buffer_size Size of the \p key_buffer buffer in bytes. |
| * \param[in] alg A signature algorithm that is compatible with |
| * the type of the key. |
| * \param[in] hash The hash or message to sign. |
| * \param[in] hash_length Size of the \p hash buffer in bytes. |
| * \param[out] signature Buffer where the signature is to be written. |
| * \param[in] signature_size Size of the \p signature buffer in bytes. |
| * \param[out] signature_length On success, the number of bytes |
| * that make up the returned signature value. |
| * |
| * \retval #PSA_SUCCESS |
| * \retval #PSA_ERROR_BUFFER_TOO_SMALL |
| * The size of the \p signature buffer is too small. You can |
| * determine a sufficient buffer size by calling |
| * #PSA_SIGN_OUTPUT_SIZE(\c key_type, \c key_bits, \p alg) |
| * where \c key_type and \c key_bits are the type and bit-size |
| * respectively of the key. |
| * \retval #PSA_ERROR_NOT_SUPPORTED |
| * \retval #PSA_ERROR_INVALID_ARGUMENT |
| * \retval #PSA_ERROR_INSUFFICIENT_MEMORY |
| * \retval #PSA_ERROR_CORRUPTION_DETECTED |
| * \retval #PSA_ERROR_INSUFFICIENT_ENTROPY |
| */ |
| psa_status_t psa_sign_hash_builtin( |
| const psa_key_attributes_t *attributes, |
| const uint8_t *key_buffer, size_t key_buffer_size, |
| psa_algorithm_t alg, const uint8_t *hash, size_t hash_length, |
| uint8_t *signature, size_t signature_size, size_t *signature_length ); |
| |
| /** |
| * \brief Verify the signature a hash or short message using a public key. |
| * |
| * \note The signature of this function is that of a PSA driver |
| * verify_hash entry point. This function behaves as a verify_hash |
| * entry point as defined in the PSA driver interface specification for |
| * transparent drivers. |
| * |
| * \param[in] attributes The attributes of the key to use for the |
| * operation. |
| * \param[in] key_buffer The buffer containing the key context. |
| * \param[in] key_buffer_size Size of the \p key_buffer buffer in bytes. |
| * \param[in] alg A signature algorithm that is compatible with |
| * the type of the key. |
| * \param[in] hash The hash or message whose signature is to be |
| * verified. |
| * \param[in] hash_length Size of the \p hash buffer in bytes. |
| * \param[in] signature Buffer containing the signature to verify. |
| * \param[in] signature_length Size of the \p signature buffer in bytes. |
| * |
| * \retval #PSA_SUCCESS |
| * The signature is valid. |
| * \retval #PSA_ERROR_INVALID_SIGNATURE |
| * The calculation was performed successfully, but the passed |
| * signature is not a valid signature. |
| * \retval #PSA_ERROR_NOT_SUPPORTED |
| * \retval #PSA_ERROR_INVALID_ARGUMENT |
| * \retval #PSA_ERROR_INSUFFICIENT_MEMORY |
| */ |
| psa_status_t psa_verify_hash_builtin( |
| const psa_key_attributes_t *attributes, |
| const uint8_t *key_buffer, size_t key_buffer_size, |
| psa_algorithm_t alg, const uint8_t *hash, size_t hash_length, |
| const uint8_t *signature, size_t signature_length ); |
| |
| /** |
| * \brief Validate the key bit size for unstructured keys. |
| * |
| * \note Check that the bit size is acceptable for a given key type for |
| * unstructured keys. |
| * |
| * \param[in] type The key type |
| * \param[in] bits The number of bits of the key |
| * |
| * \retval #PSA_SUCCESS |
| * The key type and size are valid. |
| * \retval #PSA_ERROR_INVALID_ARGUMENT |
| * The size in bits of the key is not valid. |
| * \retval #PSA_ERROR_NOT_SUPPORTED |
| * The type and/or the size in bits of the key or the combination of |
| * the two is not supported. |
| */ |
| psa_status_t psa_validate_unstructured_key_bit_size( psa_key_type_t type, |
| size_t bits ); |
| #endif /* PSA_CRYPTO_CORE_H */ |
