1 /*
2  * Copyright (c) 2018-2022, Arm Limited. All rights reserved.
3  *
4  * SPDX-License-Identifier: BSD-3-Clause
5  *
6  */
7 
8 #ifndef __TFM_CRYPTO_API_H__
9 #define __TFM_CRYPTO_API_H__
10 
11 #ifdef __cplusplus
12 extern "C" {
13 #endif
14 
15 #include <limits.h>
16 #include <stdint.h>
17 #include "tfm_crypto_defs.h"
18 #include "tfm_crypto_key.h"
19 #include "psa/client.h"
20 
21 /**
22  * \brief List of possible operation types supported by the TFM based
23  *        implementation. This type is needed by the operation allocation,
24  *        lookup and release functions.
25  *
26  */
27 enum tfm_crypto_operation_type {
28     TFM_CRYPTO_OPERATION_NONE = 0,
29     TFM_CRYPTO_CIPHER_OPERATION = 1,
30     TFM_CRYPTO_MAC_OPERATION = 2,
31     TFM_CRYPTO_HASH_OPERATION = 3,
32     TFM_CRYPTO_KEY_DERIVATION_OPERATION = 4,
33     TFM_CRYPTO_AEAD_OPERATION = 5,
34 
35     /* Used to force the enum size */
36     TFM_CRYPTO_OPERATION_TYPE_MAX = INT_MAX
37 };
38 
39 /**
40  * \brief Initialise the service
41  *
42  * \return Return values as described in \ref psa_status_t
43  */
44 psa_status_t tfm_crypto_init(void);
45 
46 /**
47  * \brief Initialise the Alloc module
48  *
49  * \return Return values as described in \ref psa_status_t
50  */
51 psa_status_t tfm_crypto_init_alloc(void);
52 
53 /**
54  * \brief Returns the ID of the caller
55  *
56  * \param[out] id Pointer to hold the ID of the caller
57  *
58  * \return Return values as described in \ref psa_status_t
59  */
60 psa_status_t tfm_crypto_get_caller_id(int32_t *id);
61 
62 /**
63  * \brief Allocate an operation context in the backend
64  *
65  * \param[in]  type   Type of the operation context to allocate
66  * \param[out] handle Pointer to hold the allocated handle
67  * \param[out  ctx    Double pointer to the corresponding context
68  *
69  * \return Return values as described in \ref psa_status_t
70  */
71 psa_status_t tfm_crypto_operation_alloc(enum tfm_crypto_operation_type type,
72                                         uint32_t *handle,
73                                         void **ctx);
74 /**
75  * \brief Release an operation context in the backend
76  *
77  * \param[in/out] handle Pointer to the handle of the context to release
78  *
79  * \return Return values as described in \ref psa_status_t
80  */
81 psa_status_t tfm_crypto_operation_release(uint32_t *handle);
82 /**
83  * \brief Look up an operation context in the backend for the corresponding
84  *        frontend operation
85  *
86  * \param[in]  type   Type of the operation context to look up
87  * \param[in]  handle Handle of the context to lookup
88  * \param[out] ctx    Double pointer to the corresponding context
89  *
90  * \return Return values as described in \ref psa_status_t
91  */
92 psa_status_t tfm_crypto_operation_lookup(enum tfm_crypto_operation_type type,
93                                          uint32_t handle,
94                                          void **ctx);
95 /**
96  * \brief This function acts as interface for the Key management module
97  *
98  * \param[in]  in_vec   Array of invec parameters
99  * \param[out] out_vec  Array of outvec parameters
100  * \param[in]  encoded_key Key encoded with partition_id and key_id
101  *
102  * \return Return values as described in \ref psa_status_t
103  */
104 psa_status_t tfm_crypto_key_management_interface(psa_invec in_vec[],
105                                             psa_outvec out_vec[],
106                                             struct tfm_crypto_key_id_s *encoded_key);
107 /**
108  * \brief This function acts as interface for the MAC module
109  *
110  * \param[in]  in_vec   Array of invec parameters
111  * \param[out] out_vec  Array of outvec parameters
112  * \param[in]  encoded_key Key encoded with partition_id and key_id
113  *
114  * \return Return values as described in \ref psa_status_t
115  */
116 psa_status_t tfm_crypto_mac_interface(psa_invec in_vec[],
117                                       psa_outvec out_vec[],
118                                       struct tfm_crypto_key_id_s *encoded_key);
119 /**
120  * \brief This function acts as interface for the Cipher module
121  *
122  * \param[in]  in_vec   Array of invec parameters
123  * \param[out] out_vec  Array of outvec parameters
124  * \param[in]  encoded_key Key encoded with partition_id and key_id
125  *
126  * \return Return values as described in \ref psa_status_t
127  */
128 psa_status_t tfm_crypto_cipher_interface(psa_invec in_vec[],
129                                          psa_outvec out_vec[],
130                                          struct tfm_crypto_key_id_s *encoded_key);
131 /**
132  * \brief This function acts as interface for the AEAD module
133  *
134  * \param[in]  in_vec   Array of invec parameters
135  * \param[out] out_vec  Array of outvec parameters
136  * \param[in]  encoded_key Key encoded with partition_id and key_id
137  *
138  * \return Return values as described in \ref psa_status_t
139  */
140 psa_status_t tfm_crypto_aead_interface(psa_invec in_vec[],
141                                        psa_outvec out_vec[],
142                                        struct tfm_crypto_key_id_s *encoded_key);
143 
144 /**
145  * \brief This function acts as interface for the Asymmetric signing module
146  *
147  * \param[in]  in_vec   Array of invec parameters
148  * \param[out] out_vec  Array of outvec parameters
149  * \param[in]  encoded_key Key encoded with partition_id and key_id
150  *
151  * \return Return values as described in \ref psa_status_t
152  */
153 psa_status_t tfm_crypto_asymmetric_sign_interface(psa_invec in_vec[],
154                                                   psa_outvec out_vec[],
155                                                   struct tfm_crypto_key_id_s *encoded_key);
156 
157 /**
158  * \brief This function acts as interface for the Asymmetric encryption module
159  *
160  * \param[in]  in_vec   Array of invec parameters
161  * \param[out] out_vec  Array of outvec parameters
162  * \param[in]  encoded_key Key encoded with partition_id and key_id
163  *
164  * \return Return values as described in \ref psa_status_t
165  */
166 psa_status_t tfm_crypto_asymmetric_encrypt_interface(psa_invec in_vec[],
167                                                      psa_outvec out_vec[],
168                                                      struct tfm_crypto_key_id_s *encoded_key);
169 
170 /**
171  * \brief This function acts as interface for the Key derivation module
172  *
173  * \param[in]  in_vec   Array of invec parameters
174  * \param[out] out_vec  Array of outvec parameters
175  * \param[in]  encoded_key Key encoded with partition_id and key_id
176  *
177  * \return Return values as described in \ref psa_status_t
178  */
179 psa_status_t tfm_crypto_key_derivation_interface(psa_invec in_vec[],
180                                                  psa_outvec out_vec[],
181                                                  struct tfm_crypto_key_id_s *encoded_key);
182 /**
183  * \brief This function acts as interface for the Random module
184  *
185  * \param[in]  in_vec   Array of invec parameters
186  * \param[out] out_vec  Array of outvec parameters
187  *
188  * \return Return values as described in \ref psa_status_t
189  */
190 psa_status_t tfm_crypto_random_interface(psa_invec in_vec[],
191                                          psa_outvec out_vec[]);
192 /**
193  * \brief This function acts as interface for the Hash module
194  *
195  * \param[in]  in_vec   Array of invec parameters
196  * \param[out] out_vec  Array of outvec parameters
197  *
198  * \return Return values as described in \ref psa_status_t
199  */
200 psa_status_t tfm_crypto_hash_interface(psa_invec in_vec[],
201                                        psa_outvec out_vec[]);
202 
203 #ifdef __cplusplus
204 }
205 #endif
206 
207 #endif /* __TFM_CRYPTO_API_H__ */
208