1 /** \file psa_crypto_random_impl.h
2 *
3 * \brief PSA crypto random generator implementation abstraction.
4 *
5 * The definitions here need to be consistent with the declarations
6 * in include/psa_util_internal.h. This file contains some redundant
7 * declarations to increase the chance that a compiler will detect
8 * inconsistencies if one file is changed without updating the other,
9 * but not all potential inconsistencies can be enforced, so make sure
10 * to check the public declarations and contracts in
11 * include/psa_util_internal.h if you modify this file.
12 */
13 /*
14 * Copyright The Mbed TLS Contributors
15 * SPDX-License-Identifier: Apache-2.0 OR GPL-2.0-or-later
16 */
17
18 #ifndef PSA_CRYPTO_RANDOM_IMPL_H
19 #define PSA_CRYPTO_RANDOM_IMPL_H
20
21 #include "psa_util_internal.h"
22
23 #if defined(MBEDTLS_PSA_CRYPTO_EXTERNAL_RNG)
24
25 #include <string.h>
26 #include <mbedtls/entropy.h> // only for error codes
27 #include <psa/crypto.h>
28
29 typedef mbedtls_psa_external_random_context_t mbedtls_psa_random_context_t;
30
31 /* Trivial wrapper around psa_generate_random(). */
32 int mbedtls_psa_get_random(void *p_rng,
33 unsigned char *output,
34 size_t output_size);
35
36 /* The PSA RNG API doesn't need any externally maintained state. */
37 #define MBEDTLS_PSA_RANDOM_STATE NULL
38
39 #else /* MBEDTLS_PSA_CRYPTO_EXTERNAL_RNG */
40
41 /* Choose a DRBG based on configuration and availability */
42 #if defined(MBEDTLS_PSA_HMAC_DRBG_MD_TYPE)
43
44 #include "mbedtls/hmac_drbg.h"
45
46 #elif defined(MBEDTLS_CTR_DRBG_C)
47
48 #include "mbedtls/ctr_drbg.h"
49
50 #elif defined(MBEDTLS_HMAC_DRBG_C)
51
52 #include "mbedtls/hmac_drbg.h"
53 #if defined(MBEDTLS_MD_CAN_SHA512) && defined(MBEDTLS_MD_CAN_SHA256)
54 #include <limits.h>
55 #if SIZE_MAX > 0xffffffff
56 /* Looks like a 64-bit system, so prefer SHA-512. */
57 #define MBEDTLS_PSA_HMAC_DRBG_MD_TYPE MBEDTLS_MD_SHA512
58 #else
59 /* Looks like a 32-bit system, so prefer SHA-256. */
60 #define MBEDTLS_PSA_HMAC_DRBG_MD_TYPE MBEDTLS_MD_SHA256
61 #endif
62 #elif defined(MBEDTLS_MD_CAN_SHA512)
63 #define MBEDTLS_PSA_HMAC_DRBG_MD_TYPE MBEDTLS_MD_SHA512
64 #elif defined(MBEDTLS_MD_CAN_SHA256)
65 #define MBEDTLS_PSA_HMAC_DRBG_MD_TYPE MBEDTLS_MD_SHA256
66 #else
67 #error "No hash algorithm available for HMAC_DBRG."
68 #endif
69
70 #else
71 #error "No DRBG module available for the psa_crypto module."
72 #endif
73
74 #include "mbedtls/entropy.h"
75
76 /** Initialize the PSA DRBG.
77 *
78 * \param p_rng Pointer to the Mbed TLS DRBG state.
79 */
mbedtls_psa_drbg_init(mbedtls_psa_drbg_context_t * p_rng)80 static inline void mbedtls_psa_drbg_init(mbedtls_psa_drbg_context_t *p_rng)
81 {
82 #if defined(MBEDTLS_CTR_DRBG_C)
83 mbedtls_ctr_drbg_init(p_rng);
84 #elif defined(MBEDTLS_HMAC_DRBG_C)
85 mbedtls_hmac_drbg_init(p_rng);
86 #endif
87 }
88
89 /** Deinitialize the PSA DRBG.
90 *
91 * \param p_rng Pointer to the Mbed TLS DRBG state.
92 */
mbedtls_psa_drbg_free(mbedtls_psa_drbg_context_t * p_rng)93 static inline void mbedtls_psa_drbg_free(mbedtls_psa_drbg_context_t *p_rng)
94 {
95 #if defined(MBEDTLS_CTR_DRBG_C)
96 mbedtls_ctr_drbg_free(p_rng);
97 #elif defined(MBEDTLS_HMAC_DRBG_C)
98 mbedtls_hmac_drbg_free(p_rng);
99 #endif
100 }
101
102 /** The type of the PSA random generator context.
103 *
104 * The random generator context is composed of an entropy context and
105 * a DRBG context.
106 */
107 typedef struct {
108 void (* entropy_init)(mbedtls_entropy_context *ctx);
109 void (* entropy_free)(mbedtls_entropy_context *ctx);
110 mbedtls_entropy_context entropy;
111 mbedtls_psa_drbg_context_t drbg;
112 } mbedtls_psa_random_context_t;
113
114 /* Defined in include/psa_util_internal.h so that it's visible to
115 * application code. The declaration here is redundant, but included
116 * as a safety net to make it more likely that a future change that
117 * accidentally causes the implementation to diverge from the interface
118 * will be noticed. */
119 /* Do not include the declaration under MSVC because it doesn't accept it
120 * ("error C2370: 'mbedtls_psa_get_random' : redefinition; different storage class").
121 * Observed with Visual Studio 2013. A known bug apparently:
122 * https://stackoverflow.com/questions/8146541/duplicate-external-static-declarations-not-allowed-in-visual-studio
123 */
124 #if !defined(_MSC_VER)
125 static mbedtls_f_rng_t *const mbedtls_psa_get_random;
126 #endif
127
128 /** The maximum number of bytes that mbedtls_psa_get_random() is expected to
129 * return.
130 */
131 #if defined(MBEDTLS_CTR_DRBG_C)
132 #define MBEDTLS_PSA_RANDOM_MAX_REQUEST MBEDTLS_CTR_DRBG_MAX_REQUEST
133 #elif defined(MBEDTLS_HMAC_DRBG_C)
134 #define MBEDTLS_PSA_RANDOM_MAX_REQUEST MBEDTLS_HMAC_DRBG_MAX_REQUEST
135 #endif
136
137 /** A pointer to the PSA DRBG state.
138 *
139 * This variable is only intended to be used through the macro
140 * #MBEDTLS_PSA_RANDOM_STATE.
141 */
142 /* psa_crypto.c sets this variable to a pointer to the DRBG state in the
143 * global PSA crypto state. */
144 /* The type `mbedtls_psa_drbg_context_t` is defined in
145 * include/psa_util_internal.h so that `mbedtls_psa_random_state` can be
146 * declared there and be visible to application code. */
147 extern mbedtls_psa_drbg_context_t *const mbedtls_psa_random_state;
148
149 /** A pointer to the PSA DRBG state.
150 *
151 * This macro expands to an expression that is suitable as the \c p_rng
152 * parameter to pass to mbedtls_psa_get_random().
153 *
154 * This macro exists in all configurations where the psa_crypto module is
155 * enabled. Its expansion depends on the configuration.
156 */
157 #define MBEDTLS_PSA_RANDOM_STATE mbedtls_psa_random_state
158
159 /** Seed the PSA DRBG.
160 *
161 * \param entropy An entropy context to read the seed from.
162 * \param custom The personalization string.
163 * This can be \c NULL, in which case the personalization
164 * string is empty regardless of the value of \p len.
165 * \param len The length of the personalization string.
166 *
167 * \return \c 0 on success.
168 * \return An Mbed TLS error code (\c MBEDTLS_ERR_xxx) on failure.
169 */
mbedtls_psa_drbg_seed(mbedtls_entropy_context * entropy,const unsigned char * custom,size_t len)170 static inline int mbedtls_psa_drbg_seed(
171 mbedtls_entropy_context *entropy,
172 const unsigned char *custom, size_t len)
173 {
174 #if defined(MBEDTLS_CTR_DRBG_C)
175 return mbedtls_ctr_drbg_seed(MBEDTLS_PSA_RANDOM_STATE,
176 mbedtls_entropy_func,
177 entropy,
178 custom, len);
179 #elif defined(MBEDTLS_HMAC_DRBG_C)
180 const mbedtls_md_info_t *md_info =
181 mbedtls_md_info_from_type(MBEDTLS_PSA_HMAC_DRBG_MD_TYPE);
182 return mbedtls_hmac_drbg_seed(MBEDTLS_PSA_RANDOM_STATE,
183 md_info,
184 mbedtls_entropy_func,
185 entropy,
186 custom, len);
187 #endif
188 }
189
190 #endif /* MBEDTLS_PSA_CRYPTO_EXTERNAL_RNG */
191
192 #endif /* PSA_CRYPTO_RANDOM_IMPL_H */
193
