crypto_se_driver.h

Go to the documentation of this file.

/*
 *  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_SE_DRIVER_H
#define PSA_CRYPTO_SE_DRIVER_H
#include "mbedtls/private_access.h"

#include "crypto_driver_common.h"

#ifdef __cplusplus
extern "C" {
#endif

typedef struct {
    const void *const MBEDTLS_PRIVATE(persistent_data);

    const size_t MBEDTLS_PRIVATE(persistent_data_size);

    uintptr_t MBEDTLS_PRIVATE(transient_data);
} psa_drv_se_context_t;

typedef psa_status_t (*psa_drv_se_init_t)(psa_drv_se_context_t *drv_context,
                                          void *persistent_data,
                                          psa_key_location_t location);

#if defined(__DOXYGEN_ONLY__) || !defined(MBEDTLS_PSA_CRYPTO_SE_C)
/* Mbed Crypto with secure element support enabled defines this type in
 * crypto_types.h because it is also visible to applications through an
 * implementation-specific extension.
 * For the PSA Cryptography specification, this type is only visible
 * via crypto_se_driver.h. */
typedef uint64_t psa_key_slot_number_t;
#endif /* __DOXYGEN_ONLY__ || !MBEDTLS_PSA_CRYPTO_SE_C */

typedef psa_status_t (*psa_drv_se_mac_setup_t)(psa_drv_se_context_t *drv_context,
                                               void *op_context,
                                               psa_key_slot_number_t key_slot,
                                               psa_algorithm_t algorithm);

typedef psa_status_t (*psa_drv_se_mac_update_t)(void *op_context,
                                                const uint8_t *p_input,
                                                size_t input_length);

typedef psa_status_t (*psa_drv_se_mac_finish_t)(void *op_context,
                                                uint8_t *p_mac,
                                                size_t mac_size,
                                                size_t *p_mac_length);

typedef psa_status_t (*psa_drv_se_mac_finish_verify_t)(void *op_context,
                                                       const uint8_t *p_mac,
                                                       size_t mac_length);

typedef psa_status_t (*psa_drv_se_mac_abort_t)(void *op_context);

typedef psa_status_t (*psa_drv_se_mac_generate_t)(psa_drv_se_context_t *drv_context,
                                                  const uint8_t *p_input,
                                                  size_t input_length,
                                                  psa_key_slot_number_t key_slot,
                                                  psa_algorithm_t alg,
                                                  uint8_t *p_mac,
                                                  size_t mac_size,
                                                  size_t *p_mac_length);

typedef psa_status_t (*psa_drv_se_mac_verify_t)(psa_drv_se_context_t *drv_context,
                                                const uint8_t *p_input,
                                                size_t input_length,
                                                psa_key_slot_number_t key_slot,
                                                psa_algorithm_t alg,
                                                const uint8_t *p_mac,
                                                size_t mac_length);

typedef struct {
    size_t                    MBEDTLS_PRIVATE(context_size);
    psa_drv_se_mac_setup_t          MBEDTLS_PRIVATE(p_setup);
    psa_drv_se_mac_update_t         MBEDTLS_PRIVATE(p_update);
    psa_drv_se_mac_finish_t         MBEDTLS_PRIVATE(p_finish);
    psa_drv_se_mac_finish_verify_t  MBEDTLS_PRIVATE(p_finish_verify);
    psa_drv_se_mac_abort_t          MBEDTLS_PRIVATE(p_abort);
    psa_drv_se_mac_generate_t       MBEDTLS_PRIVATE(p_mac);
    psa_drv_se_mac_verify_t         MBEDTLS_PRIVATE(p_mac_verify);
} psa_drv_se_mac_t;
typedef psa_status_t (*psa_drv_se_cipher_setup_t)(psa_drv_se_context_t *drv_context,
                                                  void *op_context,
                                                  psa_key_slot_number_t key_slot,
                                                  psa_algorithm_t algorithm,
                                                  psa_encrypt_or_decrypt_t direction);

typedef psa_status_t (*psa_drv_se_cipher_set_iv_t)(void *op_context,
                                                   const uint8_t *p_iv,
                                                   size_t iv_length);

typedef psa_status_t (*psa_drv_se_cipher_update_t)(void *op_context,
                                                   const uint8_t *p_input,
                                                   size_t input_size,
                                                   uint8_t *p_output,
                                                   size_t output_size,
                                                   size_t *p_output_length);

typedef psa_status_t (*psa_drv_se_cipher_finish_t)(void *op_context,
                                                   uint8_t *p_output,
                                                   size_t output_size,
                                                   size_t *p_output_length);

typedef psa_status_t (*psa_drv_se_cipher_abort_t)(void *op_context);

typedef psa_status_t (*psa_drv_se_cipher_ecb_t)(psa_drv_se_context_t *drv_context,
                                                psa_key_slot_number_t key_slot,
                                                psa_algorithm_t algorithm,
                                                psa_encrypt_or_decrypt_t direction,
                                                const uint8_t *p_input,
                                                size_t input_size,
                                                uint8_t *p_output,
                                                size_t output_size);

typedef struct {
    size_t               MBEDTLS_PRIVATE(context_size);
    psa_drv_se_cipher_setup_t  MBEDTLS_PRIVATE(p_setup);
    psa_drv_se_cipher_set_iv_t MBEDTLS_PRIVATE(p_set_iv);
    psa_drv_se_cipher_update_t MBEDTLS_PRIVATE(p_update);
    psa_drv_se_cipher_finish_t MBEDTLS_PRIVATE(p_finish);
    psa_drv_se_cipher_abort_t  MBEDTLS_PRIVATE(p_abort);
    psa_drv_se_cipher_ecb_t    MBEDTLS_PRIVATE(p_ecb);
} psa_drv_se_cipher_t;

typedef psa_status_t (*psa_drv_se_asymmetric_sign_t)(psa_drv_se_context_t *drv_context,
                                                     psa_key_slot_number_t key_slot,
                                                     psa_algorithm_t alg,
                                                     const uint8_t *p_hash,
                                                     size_t hash_length,
                                                     uint8_t *p_signature,
                                                     size_t signature_size,
                                                     size_t *p_signature_length);

typedef psa_status_t (*psa_drv_se_asymmetric_verify_t)(psa_drv_se_context_t *drv_context,
                                                       psa_key_slot_number_t key_slot,
                                                       psa_algorithm_t alg,
                                                       const uint8_t *p_hash,
                                                       size_t hash_length,
                                                       const uint8_t *p_signature,
                                                       size_t signature_length);

typedef psa_status_t (*psa_drv_se_asymmetric_encrypt_t)(psa_drv_se_context_t *drv_context,
                                                        psa_key_slot_number_t key_slot,
                                                        psa_algorithm_t alg,
                                                        const uint8_t *p_input,
                                                        size_t input_length,
                                                        const uint8_t *p_salt,
                                                        size_t salt_length,
                                                        uint8_t *p_output,
                                                        size_t output_size,
                                                        size_t *p_output_length);

typedef psa_status_t (*psa_drv_se_asymmetric_decrypt_t)(psa_drv_se_context_t *drv_context,
                                                        psa_key_slot_number_t key_slot,
                                                        psa_algorithm_t alg,
                                                        const uint8_t *p_input,
                                                        size_t input_length,
                                                        const uint8_t *p_salt,
                                                        size_t salt_length,
                                                        uint8_t *p_output,
                                                        size_t output_size,
                                                        size_t *p_output_length);

typedef struct {
    psa_drv_se_asymmetric_sign_t    MBEDTLS_PRIVATE(p_sign);
    psa_drv_se_asymmetric_verify_t  MBEDTLS_PRIVATE(p_verify);
    psa_drv_se_asymmetric_encrypt_t MBEDTLS_PRIVATE(p_encrypt);
    psa_drv_se_asymmetric_decrypt_t MBEDTLS_PRIVATE(p_decrypt);
} psa_drv_se_asymmetric_t;

typedef psa_status_t (*psa_drv_se_aead_encrypt_t)(psa_drv_se_context_t *drv_context,
                                                  psa_key_slot_number_t key_slot,
                                                  psa_algorithm_t algorithm,
                                                  const uint8_t *p_nonce,
                                                  size_t nonce_length,
                                                  const uint8_t *p_additional_data,
                                                  size_t additional_data_length,
                                                  const uint8_t *p_plaintext,
                                                  size_t plaintext_length,
                                                  uint8_t *p_ciphertext,
                                                  size_t ciphertext_size,
                                                  size_t *p_ciphertext_length);

typedef psa_status_t (*psa_drv_se_aead_decrypt_t)(psa_drv_se_context_t *drv_context,
                                                  psa_key_slot_number_t key_slot,
                                                  psa_algorithm_t algorithm,
                                                  const uint8_t *p_nonce,
                                                  size_t nonce_length,
                                                  const uint8_t *p_additional_data,
                                                  size_t additional_data_length,
                                                  const uint8_t *p_ciphertext,
                                                  size_t ciphertext_length,
                                                  uint8_t *p_plaintext,
                                                  size_t plaintext_size,
                                                  size_t *p_plaintext_length);

typedef struct {
    psa_drv_se_aead_encrypt_t MBEDTLS_PRIVATE(p_encrypt);
    psa_drv_se_aead_decrypt_t MBEDTLS_PRIVATE(p_decrypt);
} psa_drv_se_aead_t;
typedef enum
{
    PSA_KEY_CREATION_IMPORT, 
    PSA_KEY_CREATION_GENERATE, 
    PSA_KEY_CREATION_DERIVE, 
    PSA_KEY_CREATION_COPY, 
#ifndef __DOXYGEN_ONLY__

    PSA_KEY_CREATION_REGISTER,
#endif
} psa_key_creation_method_t;

typedef psa_status_t (*psa_drv_se_allocate_key_t)(
    psa_drv_se_context_t *drv_context,
    void *persistent_data,
    const psa_key_attributes_t *attributes,
    psa_key_creation_method_t method,
    psa_key_slot_number_t *key_slot);

typedef psa_status_t (*psa_drv_se_validate_slot_number_t)(
    psa_drv_se_context_t *drv_context,
    void *persistent_data,
    const psa_key_attributes_t *attributes,
    psa_key_creation_method_t method,
    psa_key_slot_number_t key_slot);

typedef psa_status_t (*psa_drv_se_import_key_t)(
    psa_drv_se_context_t *drv_context,
    psa_key_slot_number_t key_slot,
    const psa_key_attributes_t *attributes,
    const uint8_t *data,
    size_t data_length,
    size_t *bits);

typedef psa_status_t (*psa_drv_se_destroy_key_t)(
    psa_drv_se_context_t *drv_context,
    void *persistent_data,
    psa_key_slot_number_t key_slot);

typedef psa_status_t (*psa_drv_se_export_key_t)(psa_drv_se_context_t *drv_context,
                                                psa_key_slot_number_t key,
                                                uint8_t *p_data,
                                                size_t data_size,
                                                size_t *p_data_length);

typedef psa_status_t (*psa_drv_se_generate_key_t)(
    psa_drv_se_context_t *drv_context,
    psa_key_slot_number_t key_slot,
    const psa_key_attributes_t *attributes,
    uint8_t *pubkey, size_t pubkey_size, size_t *pubkey_length);

typedef struct {
    psa_drv_se_allocate_key_t   MBEDTLS_PRIVATE(p_allocate);
    psa_drv_se_validate_slot_number_t MBEDTLS_PRIVATE(p_validate_slot_number);
    psa_drv_se_import_key_t     MBEDTLS_PRIVATE(p_import);
    psa_drv_se_generate_key_t   MBEDTLS_PRIVATE(p_generate);
    psa_drv_se_destroy_key_t    MBEDTLS_PRIVATE(p_destroy);
    psa_drv_se_export_key_t     MBEDTLS_PRIVATE(p_export);
    psa_drv_se_export_key_t     MBEDTLS_PRIVATE(p_export_public);
} psa_drv_se_key_management_t;

typedef psa_status_t (*psa_drv_se_key_derivation_setup_t)(psa_drv_se_context_t *drv_context,
                                                          void *op_context,
                                                          psa_algorithm_t kdf_alg,
                                                          psa_key_slot_number_t source_key);

typedef psa_status_t (*psa_drv_se_key_derivation_collateral_t)(void *op_context,
                                                               uint32_t collateral_id,
                                                               const uint8_t *p_collateral,
                                                               size_t collateral_size);

typedef psa_status_t (*psa_drv_se_key_derivation_derive_t)(void *op_context,
                                                          psa_key_slot_number_t dest_key);

typedef psa_status_t (*psa_drv_se_key_derivation_export_t)(void *op_context,
                                                           uint8_t *p_output,
                                                           size_t output_size,
                                                           size_t *p_output_length);

typedef struct {
    size_t                           MBEDTLS_PRIVATE(context_size);
    psa_drv_se_key_derivation_setup_t      MBEDTLS_PRIVATE(p_setup);
    psa_drv_se_key_derivation_collateral_t MBEDTLS_PRIVATE(p_collateral);
    psa_drv_se_key_derivation_derive_t     MBEDTLS_PRIVATE(p_derive);
    psa_drv_se_key_derivation_export_t     MBEDTLS_PRIVATE(p_export);
} psa_drv_se_key_derivation_t;

typedef struct {
    uint32_t MBEDTLS_PRIVATE(hal_version);

    size_t MBEDTLS_PRIVATE(persistent_data_size);

    psa_drv_se_init_t MBEDTLS_PRIVATE(p_init);

    const psa_drv_se_key_management_t *MBEDTLS_PRIVATE(key_management);
    const psa_drv_se_mac_t *MBEDTLS_PRIVATE(mac);
    const psa_drv_se_cipher_t *MBEDTLS_PRIVATE(cipher);
    const psa_drv_se_aead_t *MBEDTLS_PRIVATE(aead);
    const psa_drv_se_asymmetric_t *MBEDTLS_PRIVATE(asymmetric);
    const psa_drv_se_key_derivation_t *MBEDTLS_PRIVATE(derivation);
} psa_drv_se_t;

/* 0.0.0 patchlevel 5 */
#define PSA_DRV_SE_HAL_VERSION 0x00000005

psa_status_t psa_register_se_driver(
    psa_key_location_t location,
    const psa_drv_se_t *methods);

#ifdef __cplusplus
}
#endif

#endif /* PSA_CRYPTO_SE_DRIVER_H */