crypto.h

Go to the documentation of this file.

/*
 *  Copyright The Mbed TLS Contributors
 *  Copyright 2022-2024, Texas Instruments Incorporated
 *  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.
 *
 *  Modified by Texas Instruments to:
 *  - Replace interruptable hash signing operations with psa_hash_suspend()
 *    and psa_hash_resume().
 *  - Replace 'mbedtls_svc_key_id_t' with 'psa_key_id_t'.
 *  - Remove conditional compile for MBEDTLS_PSA_CRYPTO_STRUCT_FILE.
 */

#ifndef PSA_CRYPTO_H
#define PSA_CRYPTO_H

/* clang-format off */

#include <stddef.h>

#ifdef __DOXYGEN_ONLY__
/* This __DOXYGEN_ONLY__ block contains mock definitions for things that
 * must be defined in the crypto_platform.h header. These mock definitions
 * are present in this file as a convenience to generate pretty-printed
 * documentation that includes those definitions. */

#endif /* __DOXYGEN_ONLY__ */

/* The file "crypto_types.h" declares types that encode errors,
 * algorithms, key types, policies, etc. */
#include "crypto_types.h"

#define PSA_CRYPTO_API_VERSION_MAJOR 1

#define PSA_CRYPTO_API_VERSION_MINOR 0

/* The file "crypto_values.h" declares macros to build and analyze values
 * of integral types defined in "crypto_types.h". */
#include "crypto_values.h"

#ifdef __cplusplus
extern "C" {
#endif

psa_status_t psa_crypto_init(void);

#ifdef __DOXYGEN_ONLY__
    /* This is an example definition for documentation purposes.
     * Implementations should define a suitable value in `crypto_struct.h`.
     */
    #define PSA_KEY_ATTRIBUTES_INIT \
        {                           \
            0                       \
        }
#endif

static psa_key_attributes_t psa_key_attributes_init(void);

static void psa_set_key_id(psa_key_attributes_t *attributes, psa_key_id_t key);

#ifdef MBEDTLS_PSA_CRYPTO_KEY_ID_ENCODES_OWNER

static void mbedtls_set_key_owner_id(psa_key_attributes_t *attributes,
                                     mbedtls_key_owner_id_t owner);
#endif

static void psa_set_key_lifetime(psa_key_attributes_t *attributes, psa_key_lifetime_t lifetime);

static psa_key_id_t psa_get_key_id(const psa_key_attributes_t *attributes);

static psa_key_lifetime_t psa_get_key_lifetime(const psa_key_attributes_t *attributes);

static void psa_set_key_usage_flags(psa_key_attributes_t *attributes, psa_key_usage_t usage_flags);

static psa_key_usage_t psa_get_key_usage_flags(const psa_key_attributes_t *attributes);

static void psa_set_key_algorithm(psa_key_attributes_t *attributes, psa_algorithm_t alg);

static psa_algorithm_t psa_get_key_algorithm(const psa_key_attributes_t *attributes);

static void psa_set_key_type(psa_key_attributes_t *attributes, psa_key_type_t type);

static void psa_set_key_bits(psa_key_attributes_t *attributes, size_t bits);

static psa_key_type_t psa_get_key_type(const psa_key_attributes_t *attributes);

static size_t psa_get_key_bits(const psa_key_attributes_t *attributes);

psa_status_t psa_get_key_attributes(psa_key_id_t key, psa_key_attributes_t *attributes);

void psa_reset_key_attributes(psa_key_attributes_t *attributes);

psa_status_t psa_purge_key(psa_key_id_t key);

psa_status_t psa_copy_key(psa_key_id_t source_key, const psa_key_attributes_t *attributes, psa_key_id_t *target_key);

psa_status_t psa_destroy_key(psa_key_id_t key);

psa_status_t psa_import_key(const psa_key_attributes_t *attributes,
                            const uint8_t *data,
                            size_t data_length,
                            psa_key_id_t *key);


psa_status_t psa_export_key(psa_key_id_t key, uint8_t *data, size_t data_size, size_t *data_length);

psa_status_t psa_export_public_key(psa_key_id_t key, uint8_t *data, size_t data_size, size_t *data_length);

psa_status_t psa_hash_compute(psa_algorithm_t alg,
                              const uint8_t *input,
                              size_t input_length,
                              uint8_t *hash,
                              size_t hash_size,
                              size_t *hash_length);

psa_status_t psa_hash_compare(psa_algorithm_t alg,
                              const uint8_t *input,
                              size_t input_length,
                              const uint8_t *hash,
                              size_t hash_length);

typedef struct psa_hash_operation_s psa_hash_operation_t;

#ifdef __DOXYGEN_ONLY__
    /* This is an example definition for documentation purposes.
     * Implementations should define a suitable value in `crypto_struct.h`.
     */
    #define PSA_HASH_OPERATION_INIT \
        {                           \
            0                       \
        }
#endif

static psa_hash_operation_t psa_hash_operation_init(void);

psa_status_t psa_hash_setup(psa_hash_operation_t *operation,
                            psa_algorithm_t alg);

psa_status_t psa_hash_update(psa_hash_operation_t *operation,
                             const uint8_t *input,
                             size_t input_length);

psa_status_t psa_hash_finish(psa_hash_operation_t *operation,
                             uint8_t *hash,
                             size_t hash_size,
                             size_t *hash_length);

psa_status_t psa_hash_verify(psa_hash_operation_t *operation,
                             const uint8_t *hash,
                             size_t hash_length);

psa_status_t psa_hash_abort(psa_hash_operation_t *operation);

psa_status_t psa_hash_clone(const psa_hash_operation_t *source_operation,
                            psa_hash_operation_t *target_operation);

psa_status_t psa_mac_compute(psa_key_id_t key,
                             psa_algorithm_t alg,
                             const uint8_t *input,
                             size_t input_length,
                             uint8_t *mac,
                             size_t mac_size,
                             size_t *mac_length);

psa_status_t psa_mac_verify(psa_key_id_t key,
                            psa_algorithm_t alg,
                            const uint8_t *input,
                            size_t input_length,
                            const uint8_t *mac,
                            size_t mac_length);

typedef struct psa_mac_operation_s psa_mac_operation_t;

#ifdef __DOXYGEN_ONLY__
    /* This is an example definition for documentation purposes.
     * Implementations should define a suitable value in `crypto_struct.h`.
     */
    #define PSA_MAC_OPERATION_INIT \
        {                          \
            0                      \
        }
#endif

static psa_mac_operation_t psa_mac_operation_init(void);

psa_status_t psa_mac_sign_setup(psa_mac_operation_t *operation, psa_key_id_t key, psa_algorithm_t alg);

psa_status_t psa_mac_verify_setup(psa_mac_operation_t *operation, psa_key_id_t key, psa_algorithm_t alg);

psa_status_t psa_mac_update(psa_mac_operation_t *operation,
                            const uint8_t *input,
                            size_t input_length);

psa_status_t psa_mac_sign_finish(psa_mac_operation_t *operation,
                                 uint8_t *mac,
                                 size_t mac_size,
                                 size_t *mac_length);

psa_status_t psa_mac_verify_finish(psa_mac_operation_t *operation,
                                   const uint8_t *mac,
                                   size_t mac_length);

psa_status_t psa_mac_abort(psa_mac_operation_t *operation);

psa_status_t psa_cipher_encrypt(psa_key_id_t key,
                                psa_algorithm_t alg,
                                const uint8_t *input,
                                size_t input_length,
                                uint8_t *output,
                                size_t output_size,
                                size_t *output_length);

psa_status_t psa_cipher_decrypt(psa_key_id_t key,
                                psa_algorithm_t alg,
                                const uint8_t *input,
                                size_t input_length,
                                uint8_t *output,
                                size_t output_size,
                                size_t *output_length);

typedef struct psa_cipher_operation_s psa_cipher_operation_t;

#ifdef __DOXYGEN_ONLY__
    /* This is an example definition for documentation purposes.
     * Implementations should define a suitable value in `crypto_struct.h`.
     */
    #define PSA_CIPHER_OPERATION_INIT \
        {                             \
            0                         \
        }
#endif

static psa_cipher_operation_t psa_cipher_operation_init(void);

psa_status_t psa_cipher_encrypt_setup(psa_cipher_operation_t *operation, psa_key_id_t key, psa_algorithm_t alg);

psa_status_t psa_cipher_decrypt_setup(psa_cipher_operation_t *operation, psa_key_id_t key, psa_algorithm_t alg);

psa_status_t psa_cipher_generate_iv(psa_cipher_operation_t *operation,
                                    uint8_t *iv,
                                    size_t iv_size,
                                    size_t *iv_length);

psa_status_t psa_cipher_set_iv(psa_cipher_operation_t *operation,
                               const uint8_t *iv,
                               size_t iv_length);

psa_status_t psa_cipher_update(psa_cipher_operation_t *operation,
                               const uint8_t *input,
                               size_t input_length,
                               uint8_t *output,
                               size_t output_size,
                               size_t *output_length);

psa_status_t psa_cipher_finish(psa_cipher_operation_t *operation,
                               uint8_t *output,
                               size_t output_size,
                               size_t *output_length);

psa_status_t psa_cipher_abort(psa_cipher_operation_t *operation);

psa_status_t psa_aead_encrypt(psa_key_id_t key,
                              psa_algorithm_t alg,
                              const uint8_t *nonce,
                              size_t nonce_length,
                              const uint8_t *additional_data,
                              size_t additional_data_length,
                              const uint8_t *plaintext,
                              size_t plaintext_length,
                              uint8_t *ciphertext,
                              size_t ciphertext_size,
                              size_t *ciphertext_length);

psa_status_t psa_aead_decrypt(psa_key_id_t key,
                              psa_algorithm_t alg,
                              const uint8_t *nonce,
                              size_t nonce_length,
                              const uint8_t *additional_data,
                              size_t additional_data_length,
                              const uint8_t *ciphertext,
                              size_t ciphertext_length,
                              uint8_t *plaintext,
                              size_t plaintext_size,
                              size_t *plaintext_length);

typedef struct psa_aead_operation_s psa_aead_operation_t;

#ifdef __DOXYGEN_ONLY__
    /* This is an example definition for documentation purposes.
     * Implementations should define a suitable value in `crypto_struct.h`.
     */
    #define PSA_AEAD_OPERATION_INIT \
        {                           \
            0                       \
        }
#endif

static psa_aead_operation_t psa_aead_operation_init(void);

psa_status_t psa_aead_encrypt_setup(psa_aead_operation_t *operation, psa_key_id_t key, psa_algorithm_t alg);

psa_status_t psa_aead_decrypt_setup(psa_aead_operation_t *operation, psa_key_id_t key, psa_algorithm_t alg);

psa_status_t psa_aead_generate_nonce(psa_aead_operation_t *operation,
                                     uint8_t *nonce,
                                     size_t nonce_size,
                                     size_t *nonce_length);

psa_status_t psa_aead_set_nonce(psa_aead_operation_t *operation,
                                const uint8_t *nonce,
                                size_t nonce_length);

psa_status_t psa_aead_set_lengths(psa_aead_operation_t *operation,
                                  size_t ad_length,
                                  size_t plaintext_length);

psa_status_t psa_aead_update_ad(psa_aead_operation_t *operation,
                                const uint8_t *input,
                                size_t input_length);

psa_status_t psa_aead_update(psa_aead_operation_t *operation,
                             const uint8_t *input,
                             size_t input_length,
                             uint8_t *output,
                             size_t output_size,
                             size_t *output_length);

psa_status_t psa_aead_finish(psa_aead_operation_t *operation,
                             uint8_t *ciphertext,
                             size_t ciphertext_size,
                             size_t *ciphertext_length,
                             uint8_t *tag,
                             size_t tag_size,
                             size_t *tag_length);

psa_status_t psa_aead_verify(psa_aead_operation_t *operation,
                             uint8_t *plaintext,
                             size_t plaintext_size,
                             size_t *plaintext_length,
                             const uint8_t *tag,
                             size_t tag_length);

psa_status_t psa_aead_abort(psa_aead_operation_t *operation);

psa_status_t psa_sign_message(psa_key_id_t key,
                              psa_algorithm_t alg,
                              const uint8_t *input,
                              size_t input_length,
                              uint8_t *signature,
                              size_t signature_size,
                              size_t *signature_length);

psa_status_t psa_verify_message(psa_key_id_t key,
                                psa_algorithm_t alg,
                                const uint8_t *input,
                                size_t input_length,
                                const uint8_t *signature,
                                size_t signature_length);

psa_status_t psa_sign_hash(psa_key_id_t key,
                           psa_algorithm_t alg,
                           const uint8_t *hash,
                           size_t hash_length,
                           uint8_t *signature,
                           size_t signature_size,
                           size_t *signature_length);

psa_status_t psa_verify_hash(psa_key_id_t key,
                             psa_algorithm_t alg,
                             const uint8_t *hash,
                             size_t hash_length,
                             const uint8_t *signature,
                             size_t signature_length);

psa_status_t psa_asymmetric_encrypt(psa_key_id_t key,
                                    psa_algorithm_t alg,
                                    const uint8_t *input,
                                    size_t input_length,
                                    const uint8_t *salt,
                                    size_t salt_length,
                                    uint8_t *output,
                                    size_t output_size,
                                    size_t *output_length);

psa_status_t psa_asymmetric_decrypt(psa_key_id_t key,
                                    psa_algorithm_t alg,
                                    const uint8_t *input,
                                    size_t input_length,
                                    const uint8_t *salt,
                                    size_t salt_length,
                                    uint8_t *output,
                                    size_t output_size,
                                    size_t *output_length);

typedef struct psa_key_derivation_s psa_key_derivation_operation_t;

#ifdef __DOXYGEN_ONLY__
    /* This is an example definition for documentation purposes.
     * Implementations should define a suitable value in `crypto_struct.h`.
     */
    #define PSA_KEY_DERIVATION_OPERATION_INIT \
        {                                     \
            0                                 \
        }
#endif

static psa_key_derivation_operation_t psa_key_derivation_operation_init(void);

psa_status_t psa_key_derivation_setup(psa_key_derivation_operation_t *operation, psa_algorithm_t alg);

psa_status_t psa_key_derivation_get_capacity(const psa_key_derivation_operation_t *operation, size_t *capacity);

psa_status_t psa_key_derivation_set_capacity(psa_key_derivation_operation_t *operation, size_t capacity);

#define PSA_KEY_DERIVATION_UNLIMITED_CAPACITY ((size_t) (-1))

psa_status_t psa_key_derivation_input_bytes(psa_key_derivation_operation_t *operation,
                                            psa_key_derivation_step_t step,
                                            const uint8_t *data,
                                            size_t data_length);

psa_status_t psa_key_derivation_input_integer(
    psa_key_derivation_operation_t *operation,
    psa_key_derivation_step_t step,
    uint64_t value);

psa_status_t psa_key_derivation_input_key(psa_key_derivation_operation_t *operation,
                                          psa_key_derivation_step_t step,
                                          psa_key_id_t key);

psa_status_t psa_key_derivation_key_agreement(psa_key_derivation_operation_t *operation,
                                              psa_key_derivation_step_t step,
                                              psa_key_id_t private_key,
                                              const uint8_t *peer_key,
                                              size_t peer_key_length);

psa_status_t psa_key_derivation_output_bytes(psa_key_derivation_operation_t *operation,
                                             uint8_t *output,
                                             size_t output_length);

psa_status_t psa_key_derivation_output_key(
    const psa_key_attributes_t *attributes,
    psa_key_derivation_operation_t *operation,
    psa_key_id_t *key);

psa_status_t psa_key_derivation_verify_bytes(
    psa_key_derivation_operation_t *operation,
    const uint8_t *expected_output,
    size_t output_length);

psa_status_t psa_key_derivation_verify_key(
    psa_key_derivation_operation_t *operation,
    psa_key_id_t expected);

psa_status_t psa_key_derivation_abort(psa_key_derivation_operation_t *operation);

psa_status_t psa_raw_key_agreement(psa_algorithm_t alg,
                                   psa_key_id_t private_key,
                                   const uint8_t *peer_key,
                                   size_t peer_key_length,
                                   uint8_t *output,
                                   size_t output_size,
                                   size_t *output_length);

psa_status_t psa_generate_random(uint8_t *output, size_t output_size);

psa_status_t psa_generate_key(const psa_key_attributes_t *attributes, psa_key_id_t *key);

#if 1 /* Texas Instruments modification */

psa_status_t psa_hash_resume(psa_hash_operation_t *operation, const uint8_t *hash_state, size_t hash_state_length);

psa_status_t psa_hash_suspend(psa_hash_operation_t *operation,
                              uint8_t *hash_state,
                              size_t hash_state_size,
                              size_t *hash_state_length);

#else

typedef struct psa_sign_hash_interruptible_operation_s psa_sign_hash_interruptible_operation_t;

typedef struct psa_verify_hash_interruptible_operation_s psa_verify_hash_interruptible_operation_t;

void psa_interruptible_set_max_ops(uint32_t max_ops);

uint32_t psa_interruptible_get_max_ops(void);

uint32_t psa_sign_hash_get_num_ops(
    const psa_sign_hash_interruptible_operation_t *operation);

uint32_t psa_verify_hash_get_num_ops(
    const psa_verify_hash_interruptible_operation_t *operation);

psa_status_t psa_sign_hash_start(
    psa_sign_hash_interruptible_operation_t *operation,
    psa_key_id_t key, psa_algorithm_t alg,
    const uint8_t *hash, size_t hash_length);

psa_status_t psa_sign_hash_complete(
    psa_sign_hash_interruptible_operation_t *operation,
    uint8_t *signature, size_t signature_size,
    size_t *signature_length);

psa_status_t psa_sign_hash_abort(
    psa_sign_hash_interruptible_operation_t *operation);

psa_status_t psa_verify_hash_start(
    psa_verify_hash_interruptible_operation_t *operation,
    psa_key_id_t key, psa_algorithm_t alg,
    const uint8_t *hash, size_t hash_length,
    const uint8_t *signature, size_t signature_length);

psa_status_t psa_verify_hash_complete(
    psa_verify_hash_interruptible_operation_t *operation);

psa_status_t psa_verify_hash_abort(
    psa_verify_hash_interruptible_operation_t *operation);
#endif

#ifdef __cplusplus
}
#endif

/* The file "crypto_sizes.h" contains definitions for size calculation
 * macros whose definitions are implementation-specific. */
#include "crypto_sizes.h"

/* The file "crypto_struct.h" contains definitions for
 * implementation-specific structs that are declared above. */
#include "crypto_struct.h"

/* The file "crypto_extra.h" contains vendor-specific definitions. This
 * can include vendor-defined algorithms, extra functions, etc. */
#include "crypto_extra.h"

#endif /* PSA_CRYPTO_H */