1 /*
2  * Copyright (c) 2023-2024, The TrustedFirmware-M Contributors. All rights reserved.
3  *
4  * SPDX-License-Identifier: BSD-3-Clause
5  *
6  */
7 
8 /** @file cc3xx_crypto_primitives_private.h
9  *
10  * This file contains the definition of types associated
11  * to the CC3XX driver, based on the refactored cc3xx-rom driver
12  * only. Once the migration of the PSA driver API is completed,
13  * this will be become the only private type definition header.
14  * Private in this context means that the header contains the
15  * implementation details of the types required by the driver
16  */
17 
18 #ifndef __CC3XX_CRYPTO_PRIMITIVES_PRIVATE_H__
19 #define __CC3XX_CRYPTO_PRIMITIVES_PRIVATE_H__
20 
21 #include "cc3xx_psa_api_config.h"
22 #include "psa/crypto.h"
23 
24 /* Include for the refactored low level driver components */
25 #include "cc3xx_hash.h"
26 #include "cc3xx_drbg.h"
27 #include "cc3xx_hmac.h"
28 #include "cc3xx_chacha.h"
29 #include "cc3xx_aes.h"
30 
31 #ifdef __cplusplus
32 extern "C" {
33 #endif
34 
35 /** \defgroup internal_types These types are required only by the internal cipher module
36  *
37  *  Type definitions required by the internal cipher module
38  *
39  *  @{
40  */
41 
42 typedef cc3xx_err_t (*block_cipher_update_t)(const uint8_t* in, size_t in_len);
43 typedef void (*block_cipher_set_output_buffer_t)(uint8_t *out, size_t out_len);
44 
45 /**
46  * @brief When an underlying block cipher is used as a stream cipher (AES-CTR or CHACHA-20)
47  *        it possible to use multipart operations and avoid lagging the output by up to
48  *        1 block size, by keeping track of the keystream
49  *
50  * @note  This adds more complexity to the driver layer and increases size requirements of
51  *        the multipart contexts, so it is recommended to disable it when not needed
52  */
53 struct cc3xx_internal_cipher_stream_t {
54     uint8_t buf[64]; /*!< This supports only Chacha20, i.e. CC3XX_CHACHA_BLOCK_SIZE */
55     uint8_t idx; /*!< valid range: [0, sizeof(buf)-1], sizeof(buf) means empty */
56     block_cipher_update_t update; /*!< Function pointer to trigger an update using the underlying block cipher */
57     block_cipher_set_output_buffer_t set_output_buffer; /*!<  Function pointer to set the output buffer for the underlying block cipher */
58 };
59 /** @} */ // end of internal_types
60 
61 /*!
62  * @struct cc3xx_hash_operation_s
63  *
64  * @brief A structure holding state information for an Hash operation
65  */
66 struct cc3xx_hash_operation_s {
67     struct cc3xx_hash_state_t ctx; /*!< Low-level hash context */
68 };
69 
70 /*!
71  * @struct cc3xx_random_context_s
72  *
73  * @brief A structure holding the state information associated to a DRBG
74  */
75 struct cc3xx_random_context_s {
76     struct cc3xx_drbg_state_t state; /* State of the generic DRBG interface for CC3XX */
77 };
78 
79 /*!
80  * \struct cc3xx_mac_operation_s
81  *
82  * \brief A structure holding state information for a MAC operation
83  */
84 struct cc3xx_mac_operation_s {
85     union {
86         struct cc3xx_hmac_state_t hmac; /*!< Underlying state of HMAC */
87         struct cc3xx_aes_state_t cmac;  /*!< Underlying state of AES configured in CMAC mode */
88     };
89     psa_algorithm_t alg; /*!< MAC algorithm used in this context */
90 };
91 
92 /*!
93  * \struct cc3xx_cipher_operation_s
94  *
95  * \brief A structure holding state information for a Cipher operation
96  */
97 struct cc3xx_cipher_operation_s {
98     union {
99         struct cc3xx_aes_state_t aes; /*!< Underlying state of AES related cipher modes */
100         struct cc3xx_chacha_state_t chacha; /*!< Underlying state of CHACHA related cipher modes */
101     };
102 
103 #if defined(CC3XX_CONFIG_ENABLE_STREAM_CIPHER)
104     struct cc3xx_internal_cipher_stream_t stream; /*!< Holds the keystream if alg is PSA_ALG_STREAM_CIPHER */
105 #endif /* CC3XX_CONFIG_ENABLE_STREAM_CIPHER */
106 
107 #if defined(PSA_WANT_ALG_CBC_PKCS7)
108     uint8_t pkcs7_last_block[AES_BLOCK_SIZE]; /*!< In multipart decryption, PKCS#7 needs to cache the last block */
109     size_t pkcs7_last_block_size; /*!< Size of data currently held in ::cc3xx_cipher_operation_s.pkcs7_last_block */
110 #endif /* PSA_WANT_ALG_CBC_PKCS7 */
111 
112     psa_algorithm_t alg; /*!< Cipher algorithm used in this context */
113     psa_key_type_t key_type; /*!< The key type identifies if it's Chacha or AES */
114     size_t key_bits; /*!< Size in bits of the key used on this context */
115     size_t last_output_num_bytes; /*!< Number of bytes produced at the time of the last API call */
116     bool cipher_is_initialized; /*!< Track if the cipher state has been configured or not yet */
117     size_t iv_length; /* Generic IV length passed from the PSA API layer */
118 };
119 
120 /*! @typedef cc3xx_hash_operation_t
121  *
122  * @brief A concise way to refer to \ref cc3xx_hash_operation_s
123  *
124  */
125 typedef struct cc3xx_hash_operation_s cc3xx_hash_operation_t;
126 
127 /*! @typedef cc3xx_cipher_operation_t
128  *
129  * @brief A concise way to refer to \ref cc3xx_cipher_operation_s
130  *
131  */
132 typedef struct cc3xx_cipher_operation_s cc3xx_cipher_operation_t;
133 
134 /*! @typedef cc3xx_mac_operation_t
135  *
136  * @brief A concise way to refer to \ref cc3xx_mac_operation_s
137  *
138  */
139 typedef struct cc3xx_mac_operation_s cc3xx_mac_operation_t;
140 
141 /*! @typedef cc3xx_aead_operation_t
142  *
143  * @brief A AEAD operation is completely described by the underlying
144  *        cipher operation object, i.e. it acts as an alias
145  *
146  */
147 typedef struct cc3xx_cipher_operation_s cc3xx_aead_operation_t;
148 
149 /*! @typedef cc3xx_random_context_t
150  *
151  * @brief A concise way to refer to \ref cc3xx_random_context_s
152  *
153  */
154 typedef struct cc3xx_random_context_s cc3xx_random_context_t;
155 
156 #ifdef __cplusplus
157 }
158 #endif
159 
160 #endif /* __CC3XX_CRYPTO_PRIMITIVES_PRIVATE_H__ */
161