-
Notifications
You must be signed in to change notification settings - Fork 21
/
Copy pathcrypto_extra.h
1901 lines (1780 loc) · 80.6 KB
/
crypto_extra.h
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
/**
* \file psa/crypto_extra.h
*
* \brief PSA cryptography module: Mbed TLS vendor extensions
*
* \note This file may not be included directly. Applications must
* include psa/crypto.h.
*
* This file is reserved for vendor-specific definitions.
*/
/*
* Copyright The Mbed TLS Contributors
* SPDX-License-Identifier: Apache-2.0 OR GPL-2.0-or-later
*/
#ifndef PSA_CRYPTO_EXTRA_H
#define PSA_CRYPTO_EXTRA_H
#include "mbedtls/private_access.h"
#include "crypto_types.h"
#include "crypto_compat.h"
#ifdef __cplusplus
extern "C" {
#endif
/* UID for secure storage seed */
#define PSA_CRYPTO_ITS_RANDOM_SEED_UID 0xFFFFFF52
/* See mbedtls_config.h for definition */
#if !defined(MBEDTLS_PSA_KEY_SLOT_COUNT)
#define MBEDTLS_PSA_KEY_SLOT_COUNT 32
#endif
/* If the size of static key slots is not explicitly defined by the user, then
* set it to the maximum between PSA_EXPORT_KEY_PAIR_OR_PUBLIC_MAX_SIZE and
* PSA_CIPHER_MAX_KEY_LENGTH.
* See mbedtls_config.h for the definition. */
#if !defined(MBEDTLS_PSA_STATIC_KEY_SLOT_BUFFER_SIZE)
#define MBEDTLS_PSA_STATIC_KEY_SLOT_BUFFER_SIZE \
((PSA_EXPORT_KEY_PAIR_OR_PUBLIC_MAX_SIZE > PSA_CIPHER_MAX_KEY_LENGTH) ? \
PSA_EXPORT_KEY_PAIR_OR_PUBLIC_MAX_SIZE : PSA_CIPHER_MAX_KEY_LENGTH)
#endif /* !MBEDTLS_PSA_STATIC_KEY_SLOT_BUFFER_SIZE*/
/** \addtogroup attributes
* @{
*/
/** \brief Declare the enrollment algorithm for a key.
*
* An operation on a key may indifferently use the algorithm set with
* psa_set_key_algorithm() or with this function.
*
* \param[out] attributes The attribute structure to write to.
* \param alg2 A second algorithm that the key may be used
* for, in addition to the algorithm set with
* psa_set_key_algorithm().
*
* \warning Setting an enrollment algorithm is not recommended, because
* using the same key with different algorithms can allow some
* attacks based on arithmetic relations between different
* computations made with the same key, or can escalate harmless
* side channels into exploitable ones. Use this function only
* if it is necessary to support a protocol for which it has been
* verified that the usage of the key with multiple algorithms
* is safe.
*/
static inline void psa_set_key_enrollment_algorithm(
psa_key_attributes_t *attributes,
psa_algorithm_t alg2)
{
attributes->MBEDTLS_PRIVATE(policy).MBEDTLS_PRIVATE(alg2) = alg2;
}
/** Retrieve the enrollment algorithm policy from key attributes.
*
* \param[in] attributes The key attribute structure to query.
*
* \return The enrollment algorithm stored in the attribute structure.
*/
static inline psa_algorithm_t psa_get_key_enrollment_algorithm(
const psa_key_attributes_t *attributes)
{
return attributes->MBEDTLS_PRIVATE(policy).MBEDTLS_PRIVATE(alg2);
}
#if defined(MBEDTLS_PSA_CRYPTO_SE_C)
/** Retrieve the slot number where a key is stored.
*
* A slot number is only defined for keys that are stored in a secure
* element.
*
* This information is only useful if the secure element is not entirely
* managed through the PSA Cryptography API. It is up to the secure
* element driver to decide how PSA slot numbers map to any other interface
* that the secure element may have.
*
* \param[in] attributes The key attribute structure to query.
* \param[out] slot_number On success, the slot number containing the key.
*
* \retval #PSA_SUCCESS
* The key is located in a secure element, and \p *slot_number
* indicates the slot number that contains it.
* \retval #PSA_ERROR_NOT_PERMITTED
* The caller is not permitted to query the slot number.
* Mbed TLS currently does not return this error.
* \retval #PSA_ERROR_INVALID_ARGUMENT
* The key is not located in a secure element.
*/
psa_status_t psa_get_key_slot_number(
const psa_key_attributes_t *attributes,
psa_key_slot_number_t *slot_number);
/** Choose the slot number where a key is stored.
*
* This function declares a slot number in the specified attribute
* structure.
*
* A slot number is only meaningful for keys that are stored in a secure
* element. It is up to the secure element driver to decide how PSA slot
* numbers map to any other interface that the secure element may have.
*
* \note Setting a slot number in key attributes for a key creation can
* cause the following errors when creating the key:
* - #PSA_ERROR_NOT_SUPPORTED if the selected secure element does
* not support choosing a specific slot number.
* - #PSA_ERROR_NOT_PERMITTED if the caller is not permitted to
* choose slot numbers in general or to choose this specific slot.
* - #PSA_ERROR_INVALID_ARGUMENT if the chosen slot number is not
* valid in general or not valid for this specific key.
* - #PSA_ERROR_ALREADY_EXISTS if there is already a key in the
* selected slot.
*
* \param[out] attributes The attribute structure to write to.
* \param slot_number The slot number to set.
*/
static inline void psa_set_key_slot_number(
psa_key_attributes_t *attributes,
psa_key_slot_number_t slot_number)
{
attributes->MBEDTLS_PRIVATE(has_slot_number) = 1;
attributes->MBEDTLS_PRIVATE(slot_number) = slot_number;
}
/** Remove the slot number attribute from a key attribute structure.
*
* This function undoes the action of psa_set_key_slot_number().
*
* \param[out] attributes The attribute structure to write to.
*/
static inline void psa_clear_key_slot_number(
psa_key_attributes_t *attributes)
{
attributes->MBEDTLS_PRIVATE(has_slot_number) = 0;
}
/** Register a key that is already present in a secure element.
*
* The key must be located in a secure element designated by the
* lifetime field in \p attributes, in the slot set with
* psa_set_key_slot_number() in the attribute structure.
* This function makes the key available through the key identifier
* specified in \p attributes.
*
* \param[in] attributes The attributes of the existing key.
* - The lifetime must be a persistent lifetime
* in a secure element. Volatile lifetimes are
* not currently supported.
* - The key identifier must be in the valid
* range for persistent keys.
* - The key type and size must be specified and
* must be consistent with the key material
* in the secure element.
*
* \retval #PSA_SUCCESS
* The key was successfully registered.
* Note that depending on the design of the driver, this may or may
* not guarantee that a key actually exists in the designated slot
* and is compatible with the specified attributes.
* \retval #PSA_ERROR_ALREADY_EXISTS
* There is already a key with the identifier specified in
* \p attributes.
* \retval #PSA_ERROR_NOT_SUPPORTED
* The secure element driver for the specified lifetime does not
* support registering a key.
* \retval #PSA_ERROR_INVALID_ARGUMENT
* The identifier in \p attributes is invalid, namely the identifier is
* not in the user range, or
* \p attributes specifies a lifetime which is not located
* in a secure element, or no slot number is specified in \p attributes,
* or the specified slot number is not valid.
* \retval #PSA_ERROR_NOT_PERMITTED
* The caller is not authorized to register the specified key slot.
* \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription
* \retval #PSA_ERROR_INSUFFICIENT_STORAGE \emptydescription
* \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription
* \retval #PSA_ERROR_DATA_INVALID \emptydescription
* \retval #PSA_ERROR_DATA_CORRUPT \emptydescription
* \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription
* \retval #PSA_ERROR_BAD_STATE
* The library has not been previously initialized by psa_crypto_init().
* It is implementation-dependent whether a failure to initialize
* results in this error code.
*/
psa_status_t mbedtls_psa_register_se_key(
const psa_key_attributes_t *attributes);
#endif /* MBEDTLS_PSA_CRYPTO_SE_C */
/**@}*/
/**
* \brief Library deinitialization.
*
* This function clears all data associated with the PSA layer,
* including the whole key store.
* This function is not thread safe, it wipes every key slot regardless of
* state and reader count. It should only be called when no slot is in use.
*
* This is an Mbed TLS extension.
*/
void mbedtls_psa_crypto_free(void);
/** \brief Statistics about
* resource consumption related to the PSA keystore.
*
* \note The content of this structure is not part of the stable API and ABI
* of Mbed TLS and may change arbitrarily from version to version.
*/
typedef struct mbedtls_psa_stats_s {
/** Number of slots containing key material for a volatile key. */
size_t MBEDTLS_PRIVATE(volatile_slots);
/** Number of slots containing key material for a key which is in
* internal persistent storage. */
size_t MBEDTLS_PRIVATE(persistent_slots);
/** Number of slots containing a reference to a key in a
* secure element. */
size_t MBEDTLS_PRIVATE(external_slots);
/** Number of slots which are occupied, but do not contain
* key material yet. */
size_t MBEDTLS_PRIVATE(half_filled_slots);
/** Number of slots that contain cache data. */
size_t MBEDTLS_PRIVATE(cache_slots);
/** Number of slots that are not used for anything. */
size_t MBEDTLS_PRIVATE(empty_slots);
/** Number of slots that are locked. */
size_t MBEDTLS_PRIVATE(locked_slots);
/** Largest key id value among open keys in internal persistent storage. */
psa_key_id_t MBEDTLS_PRIVATE(max_open_internal_key_id);
/** Largest key id value among open keys in secure elements. */
psa_key_id_t MBEDTLS_PRIVATE(max_open_external_key_id);
} mbedtls_psa_stats_t;
/** \brief Get statistics about
* resource consumption related to the PSA keystore.
*
* \note When Mbed TLS is built as part of a service, with isolation
* between the application and the keystore, the service may or
* may not expose this function.
*/
void mbedtls_psa_get_stats(mbedtls_psa_stats_t *stats);
/**
* \brief Inject an initial entropy seed for the random generator into
* secure storage.
*
* This function injects data to be used as a seed for the random generator
* used by the PSA Crypto implementation. On devices that lack a trusted
* entropy source (preferably a hardware random number generator),
* the Mbed PSA Crypto implementation uses this value to seed its
* random generator.
*
* On devices without a trusted entropy source, this function must be
* called exactly once in the lifetime of the device. On devices with
* a trusted entropy source, calling this function is optional.
* In all cases, this function may only be called before calling any
* other function in the PSA Crypto API, including psa_crypto_init().
*
* When this function returns successfully, it populates a file in
* persistent storage. Once the file has been created, this function
* can no longer succeed.
*
* If any error occurs, this function does not change the system state.
* You can call this function again after correcting the reason for the
* error if possible.
*
* \warning This function **can** fail! Callers MUST check the return status.
*
* \warning If you use this function, you should use it as part of a
* factory provisioning process. The value of the injected seed
* is critical to the security of the device. It must be
* *secret*, *unpredictable* and (statistically) *unique per device*.
* You should be generate it randomly using a cryptographically
* secure random generator seeded from trusted entropy sources.
* You should transmit it securely to the device and ensure
* that its value is not leaked or stored anywhere beyond the
* needs of transmitting it from the point of generation to
* the call of this function, and erase all copies of the value
* once this function returns.
*
* This is an Mbed TLS extension.
*
* \note This function is only available on the following platforms:
* * If the compile-time option MBEDTLS_PSA_INJECT_ENTROPY is enabled.
* Note that you must provide compatible implementations of
* mbedtls_nv_seed_read and mbedtls_nv_seed_write.
* * In a client-server integration of PSA Cryptography, on the client side,
* if the server supports this feature.
* \param[in] seed Buffer containing the seed value to inject.
* \param[in] seed_size Size of the \p seed buffer.
* The size of the seed in bytes must be greater
* or equal to both #MBEDTLS_ENTROPY_BLOCK_SIZE
* and the value of \c MBEDTLS_ENTROPY_MIN_PLATFORM
* in `library/entropy_poll.h` in the Mbed TLS source
* code.
* It must be less or equal to
* #MBEDTLS_ENTROPY_MAX_SEED_SIZE.
*
* \retval #PSA_SUCCESS
* The seed value was injected successfully. The random generator
* of the PSA Crypto implementation is now ready for use.
* You may now call psa_crypto_init() and use the PSA Crypto
* implementation.
* \retval #PSA_ERROR_INVALID_ARGUMENT
* \p seed_size is out of range.
* \retval #PSA_ERROR_STORAGE_FAILURE
* There was a failure reading or writing from storage.
* \retval #PSA_ERROR_NOT_PERMITTED
* The library has already been initialized. It is no longer
* possible to call this function.
*/
psa_status_t mbedtls_psa_inject_entropy(const uint8_t *seed,
size_t seed_size);
/** \addtogroup crypto_types
* @{
*/
/** DSA public key.
*
* The import and export format is the
* representation of the public key `y = g^x mod p` as a big-endian byte
* string. The length of the byte string is the length of the base prime `p`
* in bytes.
*/
#define PSA_KEY_TYPE_DSA_PUBLIC_KEY ((psa_key_type_t) 0x4002)
/** DSA key pair (private and public key).
*
* The import and export format is the
* representation of the private key `x` as a big-endian byte string. The
* length of the byte string is the private key size in bytes (leading zeroes
* are not stripped).
*
* Deterministic DSA key derivation with psa_generate_derived_key follows
* FIPS 186-4 §B.1.2: interpret the byte string as integer
* in big-endian order. Discard it if it is not in the range
* [0, *N* - 2] where *N* is the boundary of the private key domain
* (the prime *p* for Diffie-Hellman, the subprime *q* for DSA,
* or the order of the curve's base point for ECC).
* Add 1 to the resulting integer and use this as the private key *x*.
*
*/
#define PSA_KEY_TYPE_DSA_KEY_PAIR ((psa_key_type_t) 0x7002)
/** Whether a key type is a DSA key (pair or public-only). */
#define PSA_KEY_TYPE_IS_DSA(type) \
(PSA_KEY_TYPE_PUBLIC_KEY_OF_KEY_PAIR(type) == PSA_KEY_TYPE_DSA_PUBLIC_KEY)
#define PSA_ALG_DSA_BASE ((psa_algorithm_t) 0x06000400)
/** DSA signature with hashing.
*
* This is the signature scheme defined by FIPS 186-4,
* with a random per-message secret number (*k*).
*
* \param hash_alg A hash algorithm (\c PSA_ALG_XXX value such that
* #PSA_ALG_IS_HASH(\p hash_alg) is true).
* This includes #PSA_ALG_ANY_HASH
* when specifying the algorithm in a usage policy.
*
* \return The corresponding DSA signature algorithm.
* \return Unspecified if \p hash_alg is not a supported
* hash algorithm.
*/
#define PSA_ALG_DSA(hash_alg) \
(PSA_ALG_DSA_BASE | ((hash_alg) & PSA_ALG_HASH_MASK))
#define PSA_ALG_DETERMINISTIC_DSA_BASE ((psa_algorithm_t) 0x06000500)
#define PSA_ALG_DSA_DETERMINISTIC_FLAG PSA_ALG_ECDSA_DETERMINISTIC_FLAG
/** Deterministic DSA signature with hashing.
*
* This is the deterministic variant defined by RFC 6979 of
* the signature scheme defined by FIPS 186-4.
*
* \param hash_alg A hash algorithm (\c PSA_ALG_XXX value such that
* #PSA_ALG_IS_HASH(\p hash_alg) is true).
* This includes #PSA_ALG_ANY_HASH
* when specifying the algorithm in a usage policy.
*
* \return The corresponding DSA signature algorithm.
* \return Unspecified if \p hash_alg is not a supported
* hash algorithm.
*/
#define PSA_ALG_DETERMINISTIC_DSA(hash_alg) \
(PSA_ALG_DETERMINISTIC_DSA_BASE | ((hash_alg) & PSA_ALG_HASH_MASK))
#define PSA_ALG_IS_DSA(alg) \
(((alg) & ~PSA_ALG_HASH_MASK & ~PSA_ALG_DSA_DETERMINISTIC_FLAG) == \
PSA_ALG_DSA_BASE)
#define PSA_ALG_DSA_IS_DETERMINISTIC(alg) \
(((alg) & PSA_ALG_DSA_DETERMINISTIC_FLAG) != 0)
#define PSA_ALG_IS_DETERMINISTIC_DSA(alg) \
(PSA_ALG_IS_DSA(alg) && PSA_ALG_DSA_IS_DETERMINISTIC(alg))
#define PSA_ALG_IS_RANDOMIZED_DSA(alg) \
(PSA_ALG_IS_DSA(alg) && !PSA_ALG_DSA_IS_DETERMINISTIC(alg))
/* We need to expand the sample definition of this macro from
* the API definition. */
#undef PSA_ALG_IS_VENDOR_HASH_AND_SIGN
#define PSA_ALG_IS_VENDOR_HASH_AND_SIGN(alg) \
PSA_ALG_IS_DSA(alg)
/**@}*/
/** \addtogroup attributes
* @{
*/
/** PAKE operation stages. */
#define PSA_PAKE_OPERATION_STAGE_SETUP 0
#define PSA_PAKE_OPERATION_STAGE_COLLECT_INPUTS 1
#define PSA_PAKE_OPERATION_STAGE_COMPUTATION 2
/**@}*/
/** \defgroup psa_external_rng External random generator
* @{
*/
#if defined(MBEDTLS_PSA_CRYPTO_EXTERNAL_RNG)
/** External random generator function, implemented by the platform.
*
* When the compile-time option #MBEDTLS_PSA_CRYPTO_EXTERNAL_RNG is enabled,
* this function replaces Mbed TLS's entropy and DRBG modules for all
* random generation triggered via PSA crypto interfaces.
*
* \note This random generator must deliver random numbers with cryptographic
* quality and high performance. It must supply unpredictable numbers
* with a uniform distribution. The implementation of this function
* is responsible for ensuring that the random generator is seeded
* with sufficient entropy. If you have a hardware TRNG which is slow
* or delivers non-uniform output, declare it as an entropy source
* with mbedtls_entropy_add_source() instead of enabling this option.
*
* \param[in,out] context Pointer to the random generator context.
* This is all-bits-zero on the first call
* and preserved between successive calls.
* \param[out] output Output buffer. On success, this buffer
* contains random data with a uniform
* distribution.
* \param output_size The size of the \p output buffer in bytes.
* \param[out] output_length On success, set this value to \p output_size.
*
* \retval #PSA_SUCCESS
* Success. The output buffer contains \p output_size bytes of
* cryptographic-quality random data, and \c *output_length is
* set to \p output_size.
* \retval #PSA_ERROR_INSUFFICIENT_ENTROPY
* The random generator requires extra entropy and there is no
* way to obtain entropy under current environment conditions.
* This error should not happen under normal circumstances since
* this function is responsible for obtaining as much entropy as
* it needs. However implementations of this function may return
* #PSA_ERROR_INSUFFICIENT_ENTROPY if there is no way to obtain
* entropy without blocking indefinitely.
* \retval #PSA_ERROR_HARDWARE_FAILURE
* A failure of the random generator hardware that isn't covered
* by #PSA_ERROR_INSUFFICIENT_ENTROPY.
*/
psa_status_t mbedtls_psa_external_get_random(
mbedtls_psa_external_random_context_t *context,
uint8_t *output, size_t output_size, size_t *output_length);
#endif /* MBEDTLS_PSA_CRYPTO_EXTERNAL_RNG */
/**@}*/
/** \defgroup psa_builtin_keys Built-in keys
* @{
*/
/** The minimum value for a key identifier that is built into the
* implementation.
*
* The range of key identifiers from #MBEDTLS_PSA_KEY_ID_BUILTIN_MIN
* to #MBEDTLS_PSA_KEY_ID_BUILTIN_MAX within the range from
* #PSA_KEY_ID_VENDOR_MIN and #PSA_KEY_ID_VENDOR_MAX and must not intersect
* with any other set of implementation-chosen key identifiers.
*
* This value is part of the library's API since changing it would invalidate
* the values of built-in key identifiers in applications.
*/
#define MBEDTLS_PSA_KEY_ID_BUILTIN_MIN ((psa_key_id_t) 0x7fff0000)
/** The maximum value for a key identifier that is built into the
* implementation.
*
* See #MBEDTLS_PSA_KEY_ID_BUILTIN_MIN for more information.
*/
#define MBEDTLS_PSA_KEY_ID_BUILTIN_MAX ((psa_key_id_t) 0x7fffefff)
/** A slot number identifying a key in a driver.
*
* Values of this type are used to identify built-in keys.
*/
typedef uint64_t psa_drv_slot_number_t;
#if defined(MBEDTLS_PSA_CRYPTO_BUILTIN_KEYS)
/** Test whether a key identifier belongs to the builtin key range.
*
* \param key_id Key identifier to test.
*
* \retval 1
* The key identifier is a builtin key identifier.
* \retval 0
* The key identifier is not a builtin key identifier.
*/
static inline int psa_key_id_is_builtin(psa_key_id_t key_id)
{
return (key_id >= MBEDTLS_PSA_KEY_ID_BUILTIN_MIN) &&
(key_id <= MBEDTLS_PSA_KEY_ID_BUILTIN_MAX);
}
/** Platform function to obtain the location and slot number of a built-in key.
*
* An application-specific implementation of this function must be provided if
* #MBEDTLS_PSA_CRYPTO_BUILTIN_KEYS is enabled. This would typically be provided
* as part of a platform's system image.
*
* #MBEDTLS_SVC_KEY_ID_GET_KEY_ID(\p key_id) needs to be in the range from
* #MBEDTLS_PSA_KEY_ID_BUILTIN_MIN to #MBEDTLS_PSA_KEY_ID_BUILTIN_MAX.
*
* In a multi-application configuration
* (\c MBEDTLS_PSA_CRYPTO_KEY_ID_ENCODES_OWNER is defined),
* this function should check that #MBEDTLS_SVC_KEY_ID_GET_OWNER_ID(\p key_id)
* is allowed to use the given key.
*
* \param key_id The key ID for which to retrieve the
* location and slot attributes.
* \param[out] lifetime On success, the lifetime associated with the key
* corresponding to \p key_id. Lifetime is a
* combination of which driver contains the key,
* and with what persistence level the key is
* intended to be used. If the platform
* implementation does not contain specific
* information about the intended key persistence
* level, the persistence level may be reported as
* #PSA_KEY_PERSISTENCE_DEFAULT.
* \param[out] slot_number On success, the slot number known to the driver
* registered at the lifetime location reported
* through \p lifetime which corresponds to the
* requested built-in key.
*
* \retval #PSA_SUCCESS
* The requested key identifier designates a built-in key.
* In a multi-application configuration, the requested owner
* is allowed to access it.
* \retval #PSA_ERROR_DOES_NOT_EXIST
* The requested key identifier is not a built-in key which is known
* to this function. If a key exists in the key storage with this
* identifier, the data from the storage will be used.
* \return (any other error)
* Any other error is propagated to the function that requested the key.
* Common errors include:
* - #PSA_ERROR_NOT_PERMITTED: the key exists but the requested owner
* is not allowed to access it.
*/
psa_status_t mbedtls_psa_platform_get_builtin_key(
mbedtls_svc_key_id_t key_id,
psa_key_lifetime_t *lifetime,
psa_drv_slot_number_t *slot_number);
#endif /* MBEDTLS_PSA_CRYPTO_BUILTIN_KEYS */
/** @} */
/** \addtogroup crypto_types
* @{
*/
#define PSA_ALG_CATEGORY_PAKE ((psa_algorithm_t) 0x0a000000)
/** Whether the specified algorithm is a password-authenticated key exchange.
*
* \param alg An algorithm identifier (value of type #psa_algorithm_t).
*
* \return 1 if \p alg is a password-authenticated key exchange (PAKE)
* algorithm, 0 otherwise.
* This macro may return either 0 or 1 if \p alg is not a supported
* algorithm identifier.
*/
#define PSA_ALG_IS_PAKE(alg) \
(((alg) & PSA_ALG_CATEGORY_MASK) == PSA_ALG_CATEGORY_PAKE)
/** The Password-authenticated key exchange by juggling (J-PAKE) algorithm.
*
* This is J-PAKE as defined by RFC 8236, instantiated with the following
* parameters:
*
* - The group can be either an elliptic curve or defined over a finite field.
* - Schnorr NIZK proof as defined by RFC 8235 and using the same group as the
* J-PAKE algorithm.
* - A cryptographic hash function.
*
* To select these parameters and set up the cipher suite, call these functions
* in any order:
*
* \code
* psa_pake_cs_set_algorithm(cipher_suite, PSA_ALG_JPAKE);
* psa_pake_cs_set_primitive(cipher_suite,
* PSA_PAKE_PRIMITIVE(type, family, bits));
* psa_pake_cs_set_hash(cipher_suite, hash);
* \endcode
*
* For more information on how to set a specific curve or field, refer to the
* documentation of the individual \c PSA_PAKE_PRIMITIVE_TYPE_XXX constants.
*
* After initializing a J-PAKE operation, call
*
* \code
* psa_pake_setup(operation, cipher_suite);
* psa_pake_set_user(operation, ...);
* psa_pake_set_peer(operation, ...);
* psa_pake_set_password_key(operation, ...);
* \endcode
*
* The password is provided as a key. This can be the password text itself,
* in an agreed character encoding, or some value derived from the password
* as required by a higher level protocol.
*
* (The implementation converts the key material to a number as described in
* Section 2.3.8 of _SEC 1: Elliptic Curve Cryptography_
* (https://www.secg.org/sec1-v2.pdf), before reducing it modulo \c q. Here
* \c q is order of the group defined by the primitive set in the cipher suite.
* The \c psa_pake_set_password_key() function returns an error if the result
* of the reduction is 0.)
*
* The key exchange flow for J-PAKE is as follows:
* -# To get the first round data that needs to be sent to the peer, call
* \code
* // Get g1
* psa_pake_output(operation, #PSA_PAKE_STEP_KEY_SHARE, ...);
* // Get the ZKP public key for x1
* psa_pake_output(operation, #PSA_PAKE_STEP_ZK_PUBLIC, ...);
* // Get the ZKP proof for x1
* psa_pake_output(operation, #PSA_PAKE_STEP_ZK_PROOF, ...);
* // Get g2
* psa_pake_output(operation, #PSA_PAKE_STEP_KEY_SHARE, ...);
* // Get the ZKP public key for x2
* psa_pake_output(operation, #PSA_PAKE_STEP_ZK_PUBLIC, ...);
* // Get the ZKP proof for x2
* psa_pake_output(operation, #PSA_PAKE_STEP_ZK_PROOF, ...);
* \endcode
* -# To provide the first round data received from the peer to the operation,
* call
* \code
* // Set g3
* psa_pake_input(operation, #PSA_PAKE_STEP_KEY_SHARE, ...);
* // Set the ZKP public key for x3
* psa_pake_input(operation, #PSA_PAKE_STEP_ZK_PUBLIC, ...);
* // Set the ZKP proof for x3
* psa_pake_input(operation, #PSA_PAKE_STEP_ZK_PROOF, ...);
* // Set g4
* psa_pake_input(operation, #PSA_PAKE_STEP_KEY_SHARE, ...);
* // Set the ZKP public key for x4
* psa_pake_input(operation, #PSA_PAKE_STEP_ZK_PUBLIC, ...);
* // Set the ZKP proof for x4
* psa_pake_input(operation, #PSA_PAKE_STEP_ZK_PROOF, ...);
* \endcode
* -# To get the second round data that needs to be sent to the peer, call
* \code
* // Get A
* psa_pake_output(operation, #PSA_PAKE_STEP_KEY_SHARE, ...);
* // Get ZKP public key for x2*s
* psa_pake_output(operation, #PSA_PAKE_STEP_ZK_PUBLIC, ...);
* // Get ZKP proof for x2*s
* psa_pake_output(operation, #PSA_PAKE_STEP_ZK_PROOF, ...);
* \endcode
* -# To provide the second round data received from the peer to the operation,
* call
* \code
* // Set B
* psa_pake_input(operation, #PSA_PAKE_STEP_KEY_SHARE, ...);
* // Set ZKP public key for x4*s
* psa_pake_input(operation, #PSA_PAKE_STEP_ZK_PUBLIC, ...);
* // Set ZKP proof for x4*s
* psa_pake_input(operation, #PSA_PAKE_STEP_ZK_PROOF, ...);
* \endcode
* -# To access the shared secret call
* \code
* // Get Ka=Kb=K
* psa_pake_get_implicit_key()
* \endcode
*
* For more information consult the documentation of the individual
* \c PSA_PAKE_STEP_XXX constants.
*
* At this point there is a cryptographic guarantee that only the authenticated
* party who used the same password is able to compute the key. But there is no
* guarantee that the peer is the party it claims to be and was able to do so.
*
* That is, the authentication is only implicit (the peer is not authenticated
* at this point, and no action should be taken that assume that they are - like
* for example accessing restricted files).
*
* To make the authentication explicit there are various methods, see Section 5
* of RFC 8236 for two examples.
*
*/
#define PSA_ALG_JPAKE ((psa_algorithm_t) 0x0a000100)
/** @} */
/** \defgroup pake Password-authenticated key exchange (PAKE)
*
* This is a proposed PAKE interface for the PSA Crypto API. It is not part of
* the official PSA Crypto API yet.
*
* \note The content of this section is not part of the stable API and ABI
* of Mbed TLS and may change arbitrarily from version to version.
* Same holds for the corresponding macros #PSA_ALG_CATEGORY_PAKE and
* #PSA_ALG_JPAKE.
* @{
*/
/** \brief Encoding of the application role of PAKE
*
* Encodes the application's role in the algorithm is being executed. For more
* information see the documentation of individual \c PSA_PAKE_ROLE_XXX
* constants.
*/
typedef uint8_t psa_pake_role_t;
/** Encoding of input and output indicators for PAKE.
*
* Some PAKE algorithms need to exchange more data than just a single key share.
* This type is for encoding additional input and output data for such
* algorithms.
*/
typedef uint8_t psa_pake_step_t;
/** Encoding of the type of the PAKE's primitive.
*
* Values defined by this standard will never be in the range 0x80-0xff.
* Vendors who define additional types must use an encoding in this range.
*
* For more information see the documentation of individual
* \c PSA_PAKE_PRIMITIVE_TYPE_XXX constants.
*/
typedef uint8_t psa_pake_primitive_type_t;
/** \brief Encoding of the family of the primitive associated with the PAKE.
*
* For more information see the documentation of individual
* \c PSA_PAKE_PRIMITIVE_TYPE_XXX constants.
*/
typedef uint8_t psa_pake_family_t;
/** \brief Encoding of the primitive associated with the PAKE.
*
* For more information see the documentation of the #PSA_PAKE_PRIMITIVE macro.
*/
typedef uint32_t psa_pake_primitive_t;
/** A value to indicate no role in a PAKE algorithm.
* This value can be used in a call to psa_pake_set_role() for symmetric PAKE
* algorithms which do not assign roles.
*/
#define PSA_PAKE_ROLE_NONE ((psa_pake_role_t) 0x00)
/** The first peer in a balanced PAKE.
*
* Although balanced PAKE algorithms are symmetric, some of them needs an
* ordering of peers for the transcript calculations. If the algorithm does not
* need this, both #PSA_PAKE_ROLE_FIRST and #PSA_PAKE_ROLE_SECOND are
* accepted.
*/
#define PSA_PAKE_ROLE_FIRST ((psa_pake_role_t) 0x01)
/** The second peer in a balanced PAKE.
*
* Although balanced PAKE algorithms are symmetric, some of them needs an
* ordering of peers for the transcript calculations. If the algorithm does not
* need this, either #PSA_PAKE_ROLE_FIRST or #PSA_PAKE_ROLE_SECOND are
* accepted.
*/
#define PSA_PAKE_ROLE_SECOND ((psa_pake_role_t) 0x02)
/** The client in an augmented PAKE.
*
* Augmented PAKE algorithms need to differentiate between client and server.
*/
#define PSA_PAKE_ROLE_CLIENT ((psa_pake_role_t) 0x11)
/** The server in an augmented PAKE.
*
* Augmented PAKE algorithms need to differentiate between client and server.
*/
#define PSA_PAKE_ROLE_SERVER ((psa_pake_role_t) 0x12)
/** The PAKE primitive type indicating the use of elliptic curves.
*
* The values of the \c family and \c bits fields of the cipher suite identify a
* specific elliptic curve, using the same mapping that is used for ECC
* (::psa_ecc_family_t) keys.
*
* (Here \c family means the value returned by psa_pake_cs_get_family() and
* \c bits means the value returned by psa_pake_cs_get_bits().)
*
* Input and output during the operation can involve group elements and scalar
* values:
* -# The format for group elements is the same as for public keys on the
* specific curve would be. For more information, consult the documentation of
* psa_export_public_key().
* -# The format for scalars is the same as for private keys on the specific
* curve would be. For more information, consult the documentation of
* psa_export_key().
*/
#define PSA_PAKE_PRIMITIVE_TYPE_ECC ((psa_pake_primitive_type_t) 0x01)
/** The PAKE primitive type indicating the use of Diffie-Hellman groups.
*
* The values of the \c family and \c bits fields of the cipher suite identify
* a specific Diffie-Hellman group, using the same mapping that is used for
* Diffie-Hellman (::psa_dh_family_t) keys.
*
* (Here \c family means the value returned by psa_pake_cs_get_family() and
* \c bits means the value returned by psa_pake_cs_get_bits().)
*
* Input and output during the operation can involve group elements and scalar
* values:
* -# The format for group elements is the same as for public keys on the
* specific group would be. For more information, consult the documentation of
* psa_export_public_key().
* -# The format for scalars is the same as for private keys on the specific
* group would be. For more information, consult the documentation of
* psa_export_key().
*/
#define PSA_PAKE_PRIMITIVE_TYPE_DH ((psa_pake_primitive_type_t) 0x02)
/** Construct a PAKE primitive from type, family and bit-size.
*
* \param pake_type The type of the primitive
* (value of type ::psa_pake_primitive_type_t).
* \param pake_family The family of the primitive
* (the type and interpretation of this parameter depends
* on \p pake_type, for more information consult the
* documentation of individual ::psa_pake_primitive_type_t
* constants).
* \param pake_bits The bit-size of the primitive
* (Value of type \c size_t. The interpretation
* of this parameter depends on \p pake_family, for more
* information consult the documentation of individual
* ::psa_pake_primitive_type_t constants).
*
* \return The constructed primitive value of type ::psa_pake_primitive_t.
* Return 0 if the requested primitive can't be encoded as
* ::psa_pake_primitive_t.
*/
#define PSA_PAKE_PRIMITIVE(pake_type, pake_family, pake_bits) \
((pake_bits & 0xFFFF) != pake_bits) ? 0 : \
((psa_pake_primitive_t) (((pake_type) << 24 | \
(pake_family) << 16) | (pake_bits)))
/** The key share being sent to or received from the peer.
*
* The format for both input and output at this step is the same as for public
* keys on the group determined by the primitive (::psa_pake_primitive_t) would
* be.
*
* For more information on the format, consult the documentation of
* psa_export_public_key().
*
* For information regarding how the group is determined, consult the
* documentation #PSA_PAKE_PRIMITIVE.
*/
#define PSA_PAKE_STEP_KEY_SHARE ((psa_pake_step_t) 0x01)
/** A Schnorr NIZKP public key.
*
* This is the ephemeral public key in the Schnorr Non-Interactive
* Zero-Knowledge Proof (the value denoted by the letter 'V' in RFC 8235).
*
* The format for both input and output at this step is the same as for public
* keys on the group determined by the primitive (::psa_pake_primitive_t) would
* be.
*
* For more information on the format, consult the documentation of
* psa_export_public_key().
*
* For information regarding how the group is determined, consult the
* documentation #PSA_PAKE_PRIMITIVE.
*/
#define PSA_PAKE_STEP_ZK_PUBLIC ((psa_pake_step_t) 0x02)
/** A Schnorr NIZKP proof.
*
* This is the proof in the Schnorr Non-Interactive Zero-Knowledge Proof (the
* value denoted by the letter 'r' in RFC 8235).
*
* Both for input and output, the value at this step is an integer less than
* the order of the group selected in the cipher suite. The format depends on
* the group as well:
*
* - For Montgomery curves, the encoding is little endian.
* - For everything else the encoding is big endian (see Section 2.3.8 of
* _SEC 1: Elliptic Curve Cryptography_ at https://www.secg.org/sec1-v2.pdf).
*
* In both cases leading zeroes are allowed as long as the length in bytes does
* not exceed the byte length of the group order.
*
* For information regarding how the group is determined, consult the
* documentation #PSA_PAKE_PRIMITIVE.
*/
#define PSA_PAKE_STEP_ZK_PROOF ((psa_pake_step_t) 0x03)
/** The type of the data structure for PAKE cipher suites.
*
* This is an implementation-defined \c struct. Applications should not
* make any assumptions about the content of this structure.
* Implementation details can change in future versions without notice.
*/
typedef struct psa_pake_cipher_suite_s psa_pake_cipher_suite_t;
/** Return an initial value for a PAKE cipher suite object.
*/
static psa_pake_cipher_suite_t psa_pake_cipher_suite_init(void);
/** Retrieve the PAKE algorithm from a PAKE cipher suite.
*
* \param[in] cipher_suite The cipher suite structure to query.
*
* \return The PAKE algorithm stored in the cipher suite structure.
*/
static psa_algorithm_t psa_pake_cs_get_algorithm(
const psa_pake_cipher_suite_t *cipher_suite);
/** Declare the PAKE algorithm for the cipher suite.
*
* This function overwrites any PAKE algorithm
* previously set in \p cipher_suite.
*
* \param[out] cipher_suite The cipher suite structure to write to.
* \param algorithm The PAKE algorithm to write.
* (`PSA_ALG_XXX` values of type ::psa_algorithm_t
* such that #PSA_ALG_IS_PAKE(\c alg) is true.)
* If this is 0, the PAKE algorithm in
* \p cipher_suite becomes unspecified.
*/
static void psa_pake_cs_set_algorithm(psa_pake_cipher_suite_t *cipher_suite,
psa_algorithm_t algorithm);
/** Retrieve the primitive from a PAKE cipher suite.
*
* \param[in] cipher_suite The cipher suite structure to query.
*
* \return The primitive stored in the cipher suite structure.
*/
static psa_pake_primitive_t psa_pake_cs_get_primitive(
const psa_pake_cipher_suite_t *cipher_suite);
/** Declare the primitive for a PAKE cipher suite.
*
* This function overwrites any primitive previously set in \p cipher_suite.
*
* \param[out] cipher_suite The cipher suite structure to write to.
* \param primitive The primitive to write. If this is 0, the
* primitive type in \p cipher_suite becomes
* unspecified.
*/
static void psa_pake_cs_set_primitive(psa_pake_cipher_suite_t *cipher_suite,
psa_pake_primitive_t primitive);
/** Retrieve the PAKE family from a PAKE cipher suite.
*
* \param[in] cipher_suite The cipher suite structure to query.
*
* \return The PAKE family stored in the cipher suite structure.
*/
static psa_pake_family_t psa_pake_cs_get_family(
const psa_pake_cipher_suite_t *cipher_suite);
/** Retrieve the PAKE primitive bit-size from a PAKE cipher suite.
*
* \param[in] cipher_suite The cipher suite structure to query.
*
* \return The PAKE primitive bit-size stored in the cipher suite structure.
*/
static uint16_t psa_pake_cs_get_bits(
const psa_pake_cipher_suite_t *cipher_suite);