NCBI C++ ToolKit
psa_crypto_core.h
Go to the documentation of this file.

Go to the SVN repository for this file.

1 /*
2  * PSA crypto core internal interfaces
3  */
4 /*
5  * Copyright The Mbed TLS Contributors
6  * SPDX-License-Identifier: Apache-2.0
7  *
8  * Licensed under the Apache License, Version 2.0 (the "License"); you may
9  * not use this file except in compliance with the License.
10  * You may obtain a copy of the License at
11  *
12  * http://www.apache.org/licenses/LICENSE-2.0
13  *
14  * Unless required by applicable law or agreed to in writing, software
15  * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
16  * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
17  * See the License for the specific language governing permissions and
18  * limitations under the License.
19  */
20 
21 #ifndef PSA_CRYPTO_CORE_H
22 #define PSA_CRYPTO_CORE_H
23 
24 #if !defined(MBEDTLS_CONFIG_FILE)
25 #include "mbedtls/config.h"
26 #else
27 #include MBEDTLS_CONFIG_FILE
28 #endif
29 
30 #include "psa/crypto.h"
31 #include "psa/crypto_se_driver.h"
32 
33 /** Constant-time buffer comparison
34  *
35  * \param[in] a Left-hand buffer for comparison.
36  * \param[in] b Right-hand buffer for comparison.
37  * \param n Amount of bytes to compare.
38  *
39  * \return 0 if the buffer contents are equal, non-zero otherwise
40  */
41 static inline int mbedtls_psa_safer_memcmp(
42  const uint8_t *a, const uint8_t *b, size_t n)
43 {
44  size_t i;
45  unsigned char diff = 0;
46 
47  for (i = 0; i < n; i++) {
48  diff |= a[i] ^ b[i];
49  }
50 
51  return diff;
52 }
53 
54 /** The data structure representing a key slot, containing key material
55  * and metadata for one key.
56  */
57 typedef struct {
59 
60  /*
61  * Number of locks on the key slot held by the library.
62  *
63  * This counter is incremented by one each time a library function
64  * retrieves through one of the dedicated internal API a pointer to the
65  * key slot.
66  *
67  * This counter is decremented by one each time a library function stops
68  * accessing the key slot and states it by calling the
69  * psa_unlock_key_slot() API.
70  *
71  * This counter is used to prevent resetting the key slot while the library
72  * may access it. For example, such control is needed in the following
73  * scenarios:
74  * . In case of key slot starvation, all key slots contain the description
75  * of a key, and the library asks for the description of a persistent
76  * key not present in the key slots, the key slots currently accessed by
77  * the library cannot be reclaimed to free a key slot to load the
78  * persistent key.
79  * . In case of a multi-threaded application where one thread asks to close
80  * or purge or destroy a key while it is in used by the library through
81  * another thread.
82  */
83  size_t lock_count;
84 
85  /* Dynamically allocated key data buffer.
86  * Format as specified in psa_export_key(). */
87  struct key_data {
89  size_t bytes;
90  } key;
92 
93 /* A mask of key attribute flags used only internally.
94  * Currently there aren't any. */
95 #define PSA_KA_MASK_INTERNAL_ONLY ( \
96  0)
97 
98 /** Test whether a key slot is occupied.
99  *
100  * A key slot is occupied iff the key type is nonzero. This works because
101  * no valid key can have 0 as its key type.
102  *
103  * \param[in] slot The key slot to test.
104  *
105  * \return 1 if the slot is occupied, 0 otherwise.
106  */
107 static inline int psa_is_key_slot_occupied(const psa_key_slot_t *slot)
108 {
109  return slot->attr.type != 0;
110 }
111 
112 /** Test whether a key slot is locked.
113  *
114  * A key slot is locked iff its lock counter is strictly greater than 0.
115  *
116  * \param[in] slot The key slot to test.
117  *
118  * \return 1 if the slot is locked, 0 otherwise.
119  */
120 static inline int psa_is_key_slot_locked(const psa_key_slot_t *slot)
121 {
122  return slot->lock_count > 0;
123 }
124 
125 /** Retrieve flags from psa_key_slot_t::attr::core::flags.
126  *
127  * \param[in] slot The key slot to query.
128  * \param mask The mask of bits to extract.
129  *
130  * \return The key attribute flags in the given slot,
131  * bitwise-anded with \p mask.
132  */
134  uint16_t mask)
135 {
136  return slot->attr.flags & mask;
137 }
138 
139 /** Set flags in psa_key_slot_t::attr::core::flags.
140  *
141  * \param[in,out] slot The key slot to modify.
142  * \param mask The mask of bits to modify.
143  * \param value The new value of the selected bits.
144  */
145 static inline void psa_key_slot_set_flags(psa_key_slot_t *slot,
146  uint16_t mask,
147  uint16_t value)
148 {
149  slot->attr.flags = ((~mask & slot->attr.flags) |
150  (mask & value));
151 }
152 
153 /** Turn on flags in psa_key_slot_t::attr::core::flags.
154  *
155  * \param[in,out] slot The key slot to modify.
156  * \param mask The mask of bits to set.
157  */
159  uint16_t mask)
160 {
161  slot->attr.flags |= mask;
162 }
163 
164 /** Turn off flags in psa_key_slot_t::attr::core::flags.
165  *
166  * \param[in,out] slot The key slot to modify.
167  * \param mask The mask of bits to clear.
168  */
169 static inline void psa_key_slot_clear_bits(psa_key_slot_t *slot,
170  uint16_t mask)
171 {
172  slot->attr.flags &= ~mask;
173 }
174 
175 #if defined(MBEDTLS_PSA_CRYPTO_SE_C)
176 /** Get the SE slot number of a key from the key slot storing its description.
177  *
178  * \param[in] slot The key slot to query. This must be a key slot storing
179  * the description of a key of a dynamically registered
180  * secure element, otherwise the behaviour is undefined.
181  */
182 static inline psa_key_slot_number_t psa_key_slot_get_slot_number(
183  const psa_key_slot_t *slot)
184 {
185  return *((psa_key_slot_number_t *) (slot->key.data));
186 }
187 #endif
188 
189 /** Completely wipe a slot in memory, including its policy.
190  *
191  * Persistent storage is not affected.
192  *
193  * \param[in,out] slot The key slot to wipe.
194  *
195  * \retval #PSA_SUCCESS
196  * Success. This includes the case of a key slot that was
197  * already fully wiped.
198  * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription
199  */
201 
202 /** Try to allocate a buffer to an empty key slot.
203  *
204  * \param[in,out] slot Key slot to attach buffer to.
205  * \param[in] buffer_length Requested size of the buffer.
206  *
207  * \retval #PSA_SUCCESS
208  * The buffer has been successfully allocated.
209  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
210  * Not enough memory was available for allocation.
211  * \retval #PSA_ERROR_ALREADY_EXISTS
212  * Trying to allocate a buffer to a non-empty key slot.
213  */
215  size_t buffer_length);
216 
217 /** Wipe key data from a slot. Preserves metadata such as the policy. */
219 
220 /** Copy key data (in export format) into an empty key slot.
221  *
222  * This function assumes that the slot does not contain
223  * any key material yet. On failure, the slot content is unchanged.
224  *
225  * \param[in,out] slot Key slot to copy the key into.
226  * \param[in] data Buffer containing the key material.
227  * \param data_length Size of the key buffer.
228  *
229  * \retval #PSA_SUCCESS
230  * The key has been copied successfully.
231  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
232  * Not enough memory was available for allocation of the
233  * copy buffer.
234  * \retval #PSA_ERROR_ALREADY_EXISTS
235  * There was other key material already present in the slot.
236  */
238  const uint8_t *data,
239  size_t data_length);
240 
241 /** Convert an mbed TLS error code to a PSA error code
242  *
243  * \note This function is provided solely for the convenience of
244  * Mbed TLS and may be removed at any time without notice.
245  *
246  * \param ret An mbed TLS-thrown error code
247  *
248  * \return The corresponding PSA error code
249  */
251 
252 /** Import a key in binary format.
253  *
254  * \note The signature of this function is that of a PSA driver
255  * import_key entry point. This function behaves as an import_key
256  * entry point as defined in the PSA driver interface specification for
257  * transparent drivers.
258  *
259  * \param[in] attributes The attributes for the key to import.
260  * \param[in] data The buffer containing the key data in import
261  * format.
262  * \param[in] data_length Size of the \p data buffer in bytes.
263  * \param[out] key_buffer The buffer to contain the key data in output
264  * format upon successful return.
265  * \param[in] key_buffer_size Size of the \p key_buffer buffer in bytes. This
266  * size is greater or equal to \p data_length.
267  * \param[out] key_buffer_length The length of the data written in \p
268  * key_buffer in bytes.
269  * \param[out] bits The key size in number of bits.
270  *
271  * \retval #PSA_SUCCESS The key was imported successfully.
272  * \retval #PSA_ERROR_INVALID_ARGUMENT
273  * The key data is not correctly formatted.
274  * \retval #PSA_ERROR_NOT_SUPPORTED \emptydescription
275  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription
276  * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription
277  */
280  const uint8_t *data, size_t data_length,
281  uint8_t *key_buffer, size_t key_buffer_size,
282  size_t *key_buffer_length, size_t *bits);
283 
284 /** Export a key in binary format
285  *
286  * \note The signature of this function is that of a PSA driver export_key
287  * entry point. This function behaves as an export_key entry point as
288  * defined in the PSA driver interface specification.
289  *
290  * \param[in] attributes The attributes for the key to export.
291  * \param[in] key_buffer Material or context of the key to export.
292  * \param[in] key_buffer_size Size of the \p key_buffer buffer in bytes.
293  * \param[out] data Buffer where the key data is to be written.
294  * \param[in] data_size Size of the \p data buffer in bytes.
295  * \param[out] data_length On success, the number of bytes written in
296  * \p data
297  *
298  * \retval #PSA_SUCCESS The key was exported successfully.
299  * \retval #PSA_ERROR_NOT_SUPPORTED \emptydescription
300  * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription
301  * \retval #PSA_ERROR_HARDWARE_FAILURE \emptydescription
302  * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription
303  * \retval #PSA_ERROR_STORAGE_FAILURE \emptydescription
304  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription
305  */
308  const uint8_t *key_buffer, size_t key_buffer_size,
309  uint8_t *data, size_t data_size, size_t *data_length);
310 
311 /** Export a public key or the public part of a key pair in binary format.
312  *
313  * \note The signature of this function is that of a PSA driver
314  * export_public_key entry point. This function behaves as an
315  * export_public_key entry point as defined in the PSA driver interface
316  * specification.
317  *
318  * \param[in] attributes The attributes for the key to export.
319  * \param[in] key_buffer Material or context of the key to export.
320  * \param[in] key_buffer_size Size of the \p key_buffer buffer in bytes.
321  * \param[out] data Buffer where the key data is to be written.
322  * \param[in] data_size Size of the \p data buffer in bytes.
323  * \param[out] data_length On success, the number of bytes written in
324  * \p data
325  *
326  * \retval #PSA_SUCCESS The public key was exported successfully.
327  * \retval #PSA_ERROR_NOT_SUPPORTED \emptydescription
328  * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription
329  * \retval #PSA_ERROR_HARDWARE_FAILURE \emptydescription
330  * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription
331  * \retval #PSA_ERROR_STORAGE_FAILURE \emptydescription
332  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription
333  */
336  const uint8_t *key_buffer, size_t key_buffer_size,
337  uint8_t *data, size_t data_size, size_t *data_length);
338 
339 /**
340  * \brief Generate a key.
341  *
342  * \note The signature of the function is that of a PSA driver generate_key
343  * entry point.
344  *
345  * \param[in] attributes The attributes for the key to generate.
346  * \param[out] key_buffer Buffer where the key data is to be written.
347  * \param[in] key_buffer_size Size of \p key_buffer in bytes.
348  * \param[out] key_buffer_length On success, the number of bytes written in
349  * \p key_buffer.
350  *
351  * \retval #PSA_SUCCESS
352  * The key was generated successfully.
353  * \retval #PSA_ERROR_INVALID_ARGUMENT \emptydescription
354  * \retval #PSA_ERROR_NOT_SUPPORTED
355  * Key size in bits or type not supported.
356  * \retval #PSA_ERROR_BUFFER_TOO_SMALL
357  * The size of \p key_buffer is too small.
358  */
360  uint8_t *key_buffer,
361  size_t key_buffer_size,
362  size_t *key_buffer_length);
363 
364 /** Sign a message with a private key. For hash-and-sign algorithms,
365  * this includes the hashing step.
366  *
367  * \note The signature of this function is that of a PSA driver
368  * sign_message entry point. This function behaves as a sign_message
369  * entry point as defined in the PSA driver interface specification for
370  * transparent drivers.
371  *
372  * \note This function will call the driver for psa_sign_hash
373  * and go through driver dispatch again.
374  *
375  * \param[in] attributes The attributes of the key to use for the
376  * operation.
377  * \param[in] key_buffer The buffer containing the key context.
378  * \param[in] key_buffer_size Size of the \p key_buffer buffer in bytes.
379  * \param[in] alg A signature algorithm that is compatible with
380  * the type of the key.
381  * \param[in] input The input message to sign.
382  * \param[in] input_length Size of the \p input buffer in bytes.
383  * \param[out] signature Buffer where the signature is to be written.
384  * \param[in] signature_size Size of the \p signature buffer in bytes.
385  * \param[out] signature_length On success, the number of bytes
386  * that make up the returned signature value.
387  *
388  * \retval #PSA_SUCCESS \emptydescription
389  * \retval #PSA_ERROR_BUFFER_TOO_SMALL
390  * The size of the \p signature buffer is too small. You can
391  * determine a sufficient buffer size by calling
392  * #PSA_SIGN_OUTPUT_SIZE(\c key_type, \c key_bits, \p alg)
393  * where \c key_type and \c key_bits are the type and bit-size
394  * respectively of the key.
395  * \retval #PSA_ERROR_NOT_SUPPORTED \emptydescription
396  * \retval #PSA_ERROR_INVALID_ARGUMENT \emptydescription
397  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription
398  * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription
399  * \retval #PSA_ERROR_INSUFFICIENT_ENTROPY \emptydescription
400  */
403  const uint8_t *key_buffer, size_t key_buffer_size,
404  psa_algorithm_t alg, const uint8_t *input, size_t input_length,
405  uint8_t *signature, size_t signature_size, size_t *signature_length);
406 
407 /** Verify the signature of a message with a public key, using
408  * a hash-and-sign verification algorithm.
409  *
410  * \note The signature of this function is that of a PSA driver
411  * verify_message entry point. This function behaves as a verify_message
412  * entry point as defined in the PSA driver interface specification for
413  * transparent drivers.
414  *
415  * \note This function will call the driver for psa_verify_hash
416  * and go through driver dispatch again.
417  *
418  * \param[in] attributes The attributes of the key to use for the
419  * operation.
420  * \param[in] key_buffer The buffer containing the key context.
421  * \param[in] key_buffer_size Size of the \p key_buffer buffer in bytes.
422  * \param[in] alg A signature algorithm that is compatible with
423  * the type of the key.
424  * \param[in] input The message whose signature is to be verified.
425  * \param[in] input_length Size of the \p input buffer in bytes.
426  * \param[in] signature Buffer containing the signature to verify.
427  * \param[in] signature_length Size of the \p signature buffer in bytes.
428  *
429  * \retval #PSA_SUCCESS
430  * The signature is valid.
431  * \retval #PSA_ERROR_INVALID_SIGNATURE
432  * The calculation was performed successfully, but the passed
433  * signature is not a valid signature.
434  * \retval #PSA_ERROR_NOT_SUPPORTED \emptydescription
435  * \retval #PSA_ERROR_INVALID_ARGUMENT \emptydescription
436  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription
437  */
440  const uint8_t *key_buffer, size_t key_buffer_size,
441  psa_algorithm_t alg, const uint8_t *input, size_t input_length,
442  const uint8_t *signature, size_t signature_length);
443 
444 /** Sign an already-calculated hash with a private key.
445  *
446  * \note The signature of this function is that of a PSA driver
447  * sign_hash entry point. This function behaves as a sign_hash
448  * entry point as defined in the PSA driver interface specification for
449  * transparent drivers.
450  *
451  * \param[in] attributes The attributes of the key to use for the
452  * operation.
453  * \param[in] key_buffer The buffer containing the key context.
454  * \param[in] key_buffer_size Size of the \p key_buffer buffer in bytes.
455  * \param[in] alg A signature algorithm that is compatible with
456  * the type of the key.
457  * \param[in] hash The hash or message to sign.
458  * \param[in] hash_length Size of the \p hash buffer in bytes.
459  * \param[out] signature Buffer where the signature is to be written.
460  * \param[in] signature_size Size of the \p signature buffer in bytes.
461  * \param[out] signature_length On success, the number of bytes
462  * that make up the returned signature value.
463  *
464  * \retval #PSA_SUCCESS \emptydescription
465  * \retval #PSA_ERROR_BUFFER_TOO_SMALL
466  * The size of the \p signature buffer is too small. You can
467  * determine a sufficient buffer size by calling
468  * #PSA_SIGN_OUTPUT_SIZE(\c key_type, \c key_bits, \p alg)
469  * where \c key_type and \c key_bits are the type and bit-size
470  * respectively of the key.
471  * \retval #PSA_ERROR_NOT_SUPPORTED \emptydescription
472  * \retval #PSA_ERROR_INVALID_ARGUMENT \emptydescription
473  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription
474  * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription
475  * \retval #PSA_ERROR_INSUFFICIENT_ENTROPY \emptydescription
476  */
479  const uint8_t *key_buffer, size_t key_buffer_size,
480  psa_algorithm_t alg, const uint8_t *hash, size_t hash_length,
481  uint8_t *signature, size_t signature_size, size_t *signature_length);
482 
483 /**
484  * \brief Verify the signature a hash or short message using a public key.
485  *
486  * \note The signature of this function is that of a PSA driver
487  * verify_hash entry point. This function behaves as a verify_hash
488  * entry point as defined in the PSA driver interface specification for
489  * transparent drivers.
490  *
491  * \param[in] attributes The attributes of the key to use for the
492  * operation.
493  * \param[in] key_buffer The buffer containing the key context.
494  * \param[in] key_buffer_size Size of the \p key_buffer buffer in bytes.
495  * \param[in] alg A signature algorithm that is compatible with
496  * the type of the key.
497  * \param[in] hash The hash or message whose signature is to be
498  * verified.
499  * \param[in] hash_length Size of the \p hash buffer in bytes.
500  * \param[in] signature Buffer containing the signature to verify.
501  * \param[in] signature_length Size of the \p signature buffer in bytes.
502  *
503  * \retval #PSA_SUCCESS
504  * The signature is valid.
505  * \retval #PSA_ERROR_INVALID_SIGNATURE
506  * The calculation was performed successfully, but the passed
507  * signature is not a valid signature.
508  * \retval #PSA_ERROR_NOT_SUPPORTED \emptydescription
509  * \retval #PSA_ERROR_INVALID_ARGUMENT \emptydescription
510  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription
511  */
514  const uint8_t *key_buffer, size_t key_buffer_size,
515  psa_algorithm_t alg, const uint8_t *hash, size_t hash_length,
516  const uint8_t *signature, size_t signature_length);
517 
518 #endif /* PSA_CRYPTO_CORE_H */
static const struct attribute attributes[]
Definition: attributes.c:165
ncbi::TMaskedQueryRegions mask
char value[7]
Definition: config.c:431
Platform Security Architecture cryptography module.
PSA external cryptoprocessor driver module.
uint32_t psa_algorithm_t
Encoding of a cryptographic algorithm.
Definition: crypto_types.h:137
int32_t psa_status_t
Function return status.
Definition: crypto_types.h:62
uint64_t psa_key_slot_number_t
An internal designation of a key slot between the core part of the PSA Crypto implementation and the ...
static int input()
int i
yy_size_t n
const struct ncbi::grid::netcache::search::fields::KEY key
unsigned int a
Definition: ncbi_localip.c:102
#define psa_allocate_buffer_to_slot
#define psa_sign_hash_builtin
#define mbedtls_to_psa_error
#define psa_remove_key_data_from_memory
#define psa_import_key_into_slot
#define psa_copy_key_material_into_slot
#define psa_verify_hash_builtin
#define psa_verify_message_builtin
#define psa_export_public_key_internal
#define psa_wipe_key_slot
#define psa_sign_message_builtin
#define psa_export_key_internal
#define psa_generate_key_internal
static void psa_key_slot_set_flags(psa_key_slot_t *slot, uint16_t mask, uint16_t value)
Set flags in psa_key_slot_t::attr::core::flags.
static int psa_is_key_slot_occupied(const psa_key_slot_t *slot)
Test whether a key slot is occupied.
static int mbedtls_psa_safer_memcmp(const uint8_t *a, const uint8_t *b, size_t n)
Constant-time buffer comparison.
static void psa_key_slot_set_bits_in_flags(psa_key_slot_t *slot, uint16_t mask)
Turn on flags in psa_key_slot_t::attr::core::flags.
static int psa_is_key_slot_locked(const psa_key_slot_t *slot)
Test whether a key slot is locked.
static uint16_t psa_key_slot_get_flags(const psa_key_slot_t *slot, uint16_t mask)
Retrieve flags from psa_key_slot_t::attr::core::flags.
static void psa_key_slot_clear_bits(psa_key_slot_t *slot, uint16_t mask)
Turn off flags in psa_key_slot_t::attr::core::flags.
Configuration options (set of defines)
unsigned short uint16_t
Definition: stdint.h:125
unsigned char uint8_t
Definition: stdint.h:124
Definition: _hash_fun.h:40
psa_key_attributes_flag_t flags
The data structure representing a key slot, containing key material and metadata for one key.
struct psa_key_slot_t::key_data key
psa_core_key_attributes_t attr
Modified on Mon Mar 04 05:12:19 2024 by modify_doxy.py rev. 669887