1/**
2 * Constant-time functions
3 *
4 * Copyright The Mbed TLS Contributors
5 * SPDX-License-Identifier: Apache-2.0
6 *
7 * Licensed under the Apache License, Version 2.0 (the "License"); you may
8 * not use this file except in compliance with the License.
9 * You may obtain a copy of the License at
10 *
11 * http://www.apache.org/licenses/LICENSE-2.0
12 *
13 * Unless required by applicable law or agreed to in writing, software
14 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
15 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
16 * See the License for the specific language governing permissions and
17 * limitations under the License.
18 */
19
20#ifndef MBEDTLS_CONSTANT_TIME_INTERNAL_H
21#define MBEDTLS_CONSTANT_TIME_INTERNAL_H
22
23#include "common.h"
24
25#if defined(MBEDTLS_BIGNUM_C)
26#include "mbedtls/bignum.h"
27#endif
28
29#if defined(MBEDTLS_SSL_TLS_C)
30#include "mbedtls/ssl_internal.h"
31#endif
32
33#include <stddef.h>
34
35/** Turn a value into a mask:
36 * - if \p value == 0, return the all-bits 0 mask, aka 0
37 * - otherwise, return the all-bits 1 mask, aka (unsigned) -1
38 *
39 * This function can be used to write constant-time code by replacing branches
40 * with bit operations using masks.
41 *
42 * \param value The value to analyze.
43 *
44 * \return Zero if \p value is zero, otherwise all-bits-one.
45 */
46unsigned mbedtls_ct_uint_mask(unsigned value);
47
48#if defined(MBEDTLS_SSL_SOME_MODES_USE_MAC)
49
50/** Turn a value into a mask:
51 * - if \p value == 0, return the all-bits 0 mask, aka 0
52 * - otherwise, return the all-bits 1 mask, aka (size_t) -1
53 *
54 * This function can be used to write constant-time code by replacing branches
55 * with bit operations using masks.
56 *
57 * \param value The value to analyze.
58 *
59 * \return Zero if \p value is zero, otherwise all-bits-one.
60 */
61size_t mbedtls_ct_size_mask(size_t value);
62
63#endif /* MBEDTLS_SSL_SOME_MODES_USE_MAC */
64
65#if defined(MBEDTLS_BIGNUM_C)
66
67/** Turn a value into a mask:
68 * - if \p value == 0, return the all-bits 0 mask, aka 0
69 * - otherwise, return the all-bits 1 mask, aka (mbedtls_mpi_uint) -1
70 *
71 * This function can be used to write constant-time code by replacing branches
72 * with bit operations using masks.
73 *
74 * \param value The value to analyze.
75 *
76 * \return Zero if \p value is zero, otherwise all-bits-one.
77 */
78mbedtls_mpi_uint mbedtls_ct_mpi_uint_mask(mbedtls_mpi_uint value);
79
80#endif /* MBEDTLS_BIGNUM_C */
81
82#if defined(MBEDTLS_SSL_SOME_SUITES_USE_TLS_CBC)
83
84/** Constant-flow mask generation for "greater or equal" comparison:
85 * - if \p x >= \p y, return all-bits 1, that is (size_t) -1
86 * - otherwise, return all bits 0, that is 0
87 *
88 * This function can be used to write constant-time code by replacing branches
89 * with bit operations using masks.
90 *
91 * \param x The first value to analyze.
92 * \param y The second value to analyze.
93 *
94 * \return All-bits-one if \p x is greater or equal than \p y,
95 * otherwise zero.
96 */
97size_t mbedtls_ct_size_mask_ge(size_t x,
98 size_t y);
99
100#endif /* MBEDTLS_SSL_SOME_SUITES_USE_TLS_CBC */
101
102/** Constant-flow boolean "equal" comparison:
103 * return x == y
104 *
105 * This is equivalent to \p x == \p y, but is likely to be compiled
106 * to code using bitwise operation rather than a branch.
107 *
108 * \param x The first value to analyze.
109 * \param y The second value to analyze.
110 *
111 * \return 1 if \p x equals to \p y, otherwise 0.
112 */
113unsigned mbedtls_ct_size_bool_eq(size_t x,
114 size_t y);
115
116#if defined(MBEDTLS_BIGNUM_C)
117
118/** Decide if an integer is less than the other, without branches.
119 *
120 * This is equivalent to \p x < \p y, but is likely to be compiled
121 * to code using bitwise operation rather than a branch.
122 *
123 * \param x The first value to analyze.
124 * \param y The second value to analyze.
125 *
126 * \return 1 if \p x is less than \p y, otherwise 0.
127 */
128unsigned mbedtls_ct_mpi_uint_lt(const mbedtls_mpi_uint x,
129 const mbedtls_mpi_uint y);
130
131#endif /* MBEDTLS_BIGNUM_C */
132
133/** Choose between two integer values without branches.
134 *
135 * This is equivalent to `condition ? if1 : if0`, but is likely to be compiled
136 * to code using bitwise operation rather than a branch.
137 *
138 * \param condition Condition to test.
139 * \param if1 Value to use if \p condition is nonzero.
140 * \param if0 Value to use if \p condition is zero.
141 *
142 * \return \c if1 if \p condition is nonzero, otherwise \c if0.
143 */
144unsigned mbedtls_ct_uint_if(unsigned condition,
145 unsigned if1,
146 unsigned if0);
147
148#if defined(MBEDTLS_BIGNUM_C)
149
150/** Conditionally assign a value without branches.
151 *
152 * This is equivalent to `if ( condition ) dest = src`, but is likely
153 * to be compiled to code using bitwise operation rather than a branch.
154 *
155 * \param n \p dest and \p src must be arrays of limbs of size n.
156 * \param dest The MPI to conditionally assign to. This must point
157 * to an initialized MPI.
158 * \param src The MPI to be assigned from. This must point to an
159 * initialized MPI.
160 * \param condition Condition to test, must be 0 or 1.
161 */
162void mbedtls_ct_mpi_uint_cond_assign(size_t n,
163 mbedtls_mpi_uint *dest,
164 const mbedtls_mpi_uint *src,
165 unsigned char condition);
166
167#endif /* MBEDTLS_BIGNUM_C */
168
169#if defined(MBEDTLS_BASE64_C)
170
171/** Given a value in the range 0..63, return the corresponding Base64 digit.
172 *
173 * The implementation assumes that letters are consecutive (e.g. ASCII
174 * but not EBCDIC).
175 *
176 * \param value A value in the range 0..63.
177 *
178 * \return A base64 digit converted from \p value.
179 */
180unsigned char mbedtls_ct_base64_enc_char(unsigned char value);
181
182/** Given a Base64 digit, return its value.
183 *
184 * If c is not a Base64 digit ('A'..'Z', 'a'..'z', '0'..'9', '+' or '/'),
185 * return -1.
186 *
187 * The implementation assumes that letters are consecutive (e.g. ASCII
188 * but not EBCDIC).
189 *
190 * \param c A base64 digit.
191 *
192 * \return The value of the base64 digit \p c.
193 */
194signed char mbedtls_ct_base64_dec_value(unsigned char c);
195
196#endif /* MBEDTLS_BASE64_C */
197
198#if defined(MBEDTLS_SSL_SOME_MODES_USE_MAC)
199
200/** Conditional memcpy without branches.
201 *
202 * This is equivalent to `if ( c1 == c2 ) memcpy(dest, src, len)`, but is likely
203 * to be compiled to code using bitwise operation rather than a branch.
204 *
205 * \param dest The pointer to conditionally copy to.
206 * \param src The pointer to copy from. Shouldn't overlap with \p dest.
207 * \param len The number of bytes to copy.
208 * \param c1 The first value to analyze in the condition.
209 * \param c2 The second value to analyze in the condition.
210 */
211void mbedtls_ct_memcpy_if_eq(unsigned char *dest,
212 const unsigned char *src,
213 size_t len,
214 size_t c1, size_t c2);
215
216/** Copy data from a secret position with constant flow.
217 *
218 * This function copies \p len bytes from \p src_base + \p offset_secret to \p
219 * dst, with a code flow and memory access pattern that does not depend on \p
220 * offset_secret, but only on \p offset_min, \p offset_max and \p len.
221 * Functionally equivalent to `memcpy(dst, src + offset_secret, len)`.
222 *
223 * \note This function reads from \p dest, but the value that
224 * is read does not influence the result and this
225 * function's behavior is well-defined regardless of the
226 * contents of the buffers. This may result in false
227 * positives from static or dynamic analyzers, especially
228 * if \p dest is not initialized.
229 *
230 * \param dest The destination buffer. This must point to a writable
231 * buffer of at least \p len bytes.
232 * \param src The base of the source buffer. This must point to a
233 * readable buffer of at least \p offset_max + \p len
234 * bytes. Shouldn't overlap with \p dest.
235 * \param offset The offset in the source buffer from which to copy.
236 * This must be no less than \p offset_min and no greater
237 * than \p offset_max.
238 * \param offset_min The minimal value of \p offset.
239 * \param offset_max The maximal value of \p offset.
240 * \param len The number of bytes to copy.
241 */
242void mbedtls_ct_memcpy_offset(unsigned char *dest,
243 const unsigned char *src,
244 size_t offset,
245 size_t offset_min,
246 size_t offset_max,
247 size_t len);
248
249/** Compute the HMAC of variable-length data with constant flow.
250 *
251 * This function computes the HMAC of the concatenation of \p add_data and \p
252 * data, and does with a code flow and memory access pattern that does not
253 * depend on \p data_len_secret, but only on \p min_data_len and \p
254 * max_data_len. In particular, this function always reads exactly \p
255 * max_data_len bytes from \p data.
256 *
257 * \param ctx The HMAC context. It must have keys configured
258 * with mbedtls_md_hmac_starts() and use one of the
259 * following hashes: SHA-384, SHA-256, SHA-1 or MD-5.
260 * It is reset using mbedtls_md_hmac_reset() after
261 * the computation is complete to prepare for the
262 * next computation.
263 * \param add_data The first part of the message whose HMAC is being
264 * calculated. This must point to a readable buffer
265 * of \p add_data_len bytes.
266 * \param add_data_len The length of \p add_data in bytes.
267 * \param data The buffer containing the second part of the
268 * message. This must point to a readable buffer
269 * of \p max_data_len bytes.
270 * \param data_len_secret The length of the data to process in \p data.
271 * This must be no less than \p min_data_len and no
272 * greater than \p max_data_len.
273 * \param min_data_len The minimal length of the second part of the
274 * message, read from \p data.
275 * \param max_data_len The maximal length of the second part of the
276 * message, read from \p data.
277 * \param output The HMAC will be written here. This must point to
278 * a writable buffer of sufficient size to hold the
279 * HMAC value.
280 *
281 * \retval 0 on success.
282 * \retval #MBEDTLS_ERR_PLATFORM_HW_ACCEL_FAILED
283 * The hardware accelerator failed.
284 */
285int mbedtls_ct_hmac(mbedtls_md_context_t *ctx,
286 const unsigned char *add_data,
287 size_t add_data_len,
288 const unsigned char *data,
289 size_t data_len_secret,
290 size_t min_data_len,
291 size_t max_data_len,
292 unsigned char *output);
293
294#endif /* MBEDTLS_SSL_SOME_MODES_USE_MAC */
295
296#if defined(MBEDTLS_PKCS1_V15) && defined(MBEDTLS_RSA_C) && !defined(MBEDTLS_RSA_ALT)
297
298/** This function performs the unpadding part of a PKCS#1 v1.5 decryption
299 * operation (EME-PKCS1-v1_5 decoding).
300 *
301 * \note The return value from this function is a sensitive value
302 * (this is unusual). #MBEDTLS_ERR_RSA_OUTPUT_TOO_LARGE shouldn't happen
303 * in a well-written application, but 0 vs #MBEDTLS_ERR_RSA_INVALID_PADDING
304 * is often a situation that an attacker can provoke and leaking which
305 * one is the result is precisely the information the attacker wants.
306 *
307 * \param mode The mode of operation. This must be either
308 * #MBEDTLS_RSA_PRIVATE or #MBEDTLS_RSA_PUBLIC (deprecated).
309 * \param input The input buffer which is the payload inside PKCS#1v1.5
310 * encryption padding, called the "encoded message EM"
311 * by the terminology.
312 * \param ilen The length of the payload in the \p input buffer.
313 * \param output The buffer for the payload, called "message M" by the
314 * PKCS#1 terminology. This must be a writable buffer of
315 * length \p output_max_len bytes.
316 * \param olen The address at which to store the length of
317 * the payload. This must not be \c NULL.
318 * \param output_max_len The length in bytes of the output buffer \p output.
319 *
320 * \return \c 0 on success.
321 * \return #MBEDTLS_ERR_RSA_OUTPUT_TOO_LARGE
322 * The output buffer is too small for the unpadded payload.
323 * \return #MBEDTLS_ERR_RSA_INVALID_PADDING
324 * The input doesn't contain properly formatted padding.
325 */
326int mbedtls_ct_rsaes_pkcs1_v15_unpadding(int mode,
327 unsigned char *input,
328 size_t ilen,
329 unsigned char *output,
330 size_t output_max_len,
331 size_t *olen);
332
333#endif /* MBEDTLS_PKCS1_V15 && MBEDTLS_RSA_C && ! MBEDTLS_RSA_ALT */
334
335#endif /* MBEDTLS_CONSTANT_TIME_INTERNAL_H */
336