1 /**
2 * \file common.h
3 *
4 * \brief Utility macros for internal use in the library
5 */
6 /*
7 * Copyright The Mbed TLS Contributors
8 * SPDX-License-Identifier: Apache-2.0
9 *
10 * Licensed under the Apache License, Version 2.0 (the "License"); you may
11 * not use this file except in compliance with the License.
12 * You may obtain a copy of the License at
13 *
14 * http://www.apache.org/licenses/LICENSE-2.0
15 *
16 * Unless required by applicable law or agreed to in writing, software
17 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
18 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
19 * See the License for the specific language governing permissions and
20 * limitations under the License.
21 */
22
23 #ifndef MBEDTLS_LIBRARY_COMMON_H
24 #define MBEDTLS_LIBRARY_COMMON_H
25
26 #include "mbedtls/build_info.h"
27
28 #include <stddef.h>
29 #include <stdint.h>
30
31 /** Helper to define a function as static except when building invasive tests.
32 *
33 * If a function is only used inside its own source file and should be
34 * declared `static` to allow the compiler to optimize for code size,
35 * but that function has unit tests, define it with
36 * ```
37 * MBEDTLS_STATIC_TESTABLE int mbedtls_foo(...) { ... }
38 * ```
39 * and declare it in a header in the `library/` directory with
40 * ```
41 * #if defined(MBEDTLS_TEST_HOOKS)
42 * int mbedtls_foo(...);
43 * #endif
44 * ```
45 */
46 #if defined(MBEDTLS_TEST_HOOKS)
47 #define MBEDTLS_STATIC_TESTABLE
48 #else
49 #define MBEDTLS_STATIC_TESTABLE static
50 #endif
51
52 #if defined(MBEDTLS_TEST_HOOKS)
53 extern void (*mbedtls_test_hook_test_fail)( const char * test, int line, const char * file );
54 #define MBEDTLS_TEST_HOOK_TEST_ASSERT( TEST ) \
55 do { \
56 if( ( ! ( TEST ) ) && ( ( *mbedtls_test_hook_test_fail ) != NULL ) ) \
57 { \
58 ( *mbedtls_test_hook_test_fail )( #TEST, __LINE__, __FILE__ ); \
59 } \
60 } while( 0 )
61 #else
62 #define MBEDTLS_TEST_HOOK_TEST_ASSERT( TEST )
63 #endif /* defined(MBEDTLS_TEST_HOOKS) */
64
65 /** Allow library to access its structs' private members.
66 *
67 * Although structs defined in header files are publicly available,
68 * their members are private and should not be accessed by the user.
69 */
70 #define MBEDTLS_ALLOW_PRIVATE_ACCESS
71
72 /** Return an offset into a buffer.
73 *
74 * This is just the addition of an offset to a pointer, except that this
75 * function also accepts an offset of 0 into a buffer whose pointer is null.
76 * (`p + n` has undefined behavior when `p` is null, even when `n == 0`.
77 * A null pointer is a valid buffer pointer when the size is 0, for example
78 * as the result of `malloc(0)` on some platforms.)
79 *
80 * \param p Pointer to a buffer of at least n bytes.
81 * This may be \p NULL if \p n is zero.
82 * \param n An offset in bytes.
83 * \return Pointer to offset \p n in the buffer \p p.
84 * Note that this is only a valid pointer if the size of the
85 * buffer is at least \p n + 1.
86 */
mbedtls_buffer_offset(unsigned char * p,size_t n)87 static inline unsigned char *mbedtls_buffer_offset(
88 unsigned char *p, size_t n )
89 {
90 return( p == NULL ? NULL : p + n );
91 }
92
93 /** Return an offset into a read-only buffer.
94 *
95 * Similar to mbedtls_buffer_offset(), but for const pointers.
96 *
97 * \param p Pointer to a buffer of at least n bytes.
98 * This may be \p NULL if \p n is zero.
99 * \param n An offset in bytes.
100 * \return Pointer to offset \p n in the buffer \p p.
101 * Note that this is only a valid pointer if the size of the
102 * buffer is at least \p n + 1.
103 */
mbedtls_buffer_offset_const(const unsigned char * p,size_t n)104 static inline const unsigned char *mbedtls_buffer_offset_const(
105 const unsigned char *p, size_t n )
106 {
107 return( p == NULL ? NULL : p + n );
108 }
109
110 /** Byte Reading Macros
111 *
112 * Given a multi-byte integer \p x, MBEDTLS_BYTE_n retrieves the n-th
113 * byte from x, where byte 0 is the least significant byte.
114 */
115 #define MBEDTLS_BYTE_0( x ) ( (uint8_t) ( ( x ) & 0xff ) )
116 #define MBEDTLS_BYTE_1( x ) ( (uint8_t) ( ( ( x ) >> 8 ) & 0xff ) )
117 #define MBEDTLS_BYTE_2( x ) ( (uint8_t) ( ( ( x ) >> 16 ) & 0xff ) )
118 #define MBEDTLS_BYTE_3( x ) ( (uint8_t) ( ( ( x ) >> 24 ) & 0xff ) )
119 #define MBEDTLS_BYTE_4( x ) ( (uint8_t) ( ( ( x ) >> 32 ) & 0xff ) )
120 #define MBEDTLS_BYTE_5( x ) ( (uint8_t) ( ( ( x ) >> 40 ) & 0xff ) )
121 #define MBEDTLS_BYTE_6( x ) ( (uint8_t) ( ( ( x ) >> 48 ) & 0xff ) )
122 #define MBEDTLS_BYTE_7( x ) ( (uint8_t) ( ( ( x ) >> 56 ) & 0xff ) )
123
124 /**
125 * Get the unsigned 32 bits integer corresponding to four bytes in
126 * big-endian order (MSB first).
127 *
128 * \param data Base address of the memory to get the four bytes from.
129 * \param offset Offset from \p data of the first and most significant
130 * byte of the four bytes to build the 32 bits unsigned
131 * integer from.
132 */
133 #ifndef MBEDTLS_GET_UINT32_BE
134 #define MBEDTLS_GET_UINT32_BE( data , offset ) \
135 ( \
136 ( (uint32_t) ( data )[( offset ) ] << 24 ) \
137 | ( (uint32_t) ( data )[( offset ) + 1] << 16 ) \
138 | ( (uint32_t) ( data )[( offset ) + 2] << 8 ) \
139 | ( (uint32_t) ( data )[( offset ) + 3] ) \
140 )
141 #endif
142
143 /**
144 * Put in memory a 32 bits unsigned integer in big-endian order.
145 *
146 * \param n 32 bits unsigned integer to put in memory.
147 * \param data Base address of the memory where to put the 32
148 * bits unsigned integer in.
149 * \param offset Offset from \p data where to put the most significant
150 * byte of the 32 bits unsigned integer \p n.
151 */
152 #ifndef MBEDTLS_PUT_UINT32_BE
153 #define MBEDTLS_PUT_UINT32_BE( n, data, offset ) \
154 { \
155 ( data )[( offset ) ] = MBEDTLS_BYTE_3( n ); \
156 ( data )[( offset ) + 1] = MBEDTLS_BYTE_2( n ); \
157 ( data )[( offset ) + 2] = MBEDTLS_BYTE_1( n ); \
158 ( data )[( offset ) + 3] = MBEDTLS_BYTE_0( n ); \
159 }
160 #endif
161
162 /**
163 * Get the unsigned 32 bits integer corresponding to four bytes in
164 * little-endian order (LSB first).
165 *
166 * \param data Base address of the memory to get the four bytes from.
167 * \param offset Offset from \p data of the first and least significant
168 * byte of the four bytes to build the 32 bits unsigned
169 * integer from.
170 */
171 #ifndef MBEDTLS_GET_UINT32_LE
172 #define MBEDTLS_GET_UINT32_LE( data, offset ) \
173 ( \
174 ( (uint32_t) ( data )[( offset ) ] ) \
175 | ( (uint32_t) ( data )[( offset ) + 1] << 8 ) \
176 | ( (uint32_t) ( data )[( offset ) + 2] << 16 ) \
177 | ( (uint32_t) ( data )[( offset ) + 3] << 24 ) \
178 )
179 #endif
180
181 /**
182 * Put in memory a 32 bits unsigned integer in little-endian order.
183 *
184 * \param n 32 bits unsigned integer to put in memory.
185 * \param data Base address of the memory where to put the 32
186 * bits unsigned integer in.
187 * \param offset Offset from \p data where to put the least significant
188 * byte of the 32 bits unsigned integer \p n.
189 */
190 #ifndef MBEDTLS_PUT_UINT32_LE
191 #define MBEDTLS_PUT_UINT32_LE( n, data, offset ) \
192 { \
193 ( data )[( offset ) ] = MBEDTLS_BYTE_0( n ); \
194 ( data )[( offset ) + 1] = MBEDTLS_BYTE_1( n ); \
195 ( data )[( offset ) + 2] = MBEDTLS_BYTE_2( n ); \
196 ( data )[( offset ) + 3] = MBEDTLS_BYTE_3( n ); \
197 }
198 #endif
199
200 /**
201 * Get the unsigned 16 bits integer corresponding to two bytes in
202 * little-endian order (LSB first).
203 *
204 * \param data Base address of the memory to get the two bytes from.
205 * \param offset Offset from \p data of the first and least significant
206 * byte of the two bytes to build the 16 bits unsigned
207 * integer from.
208 */
209 #ifndef MBEDTLS_GET_UINT16_LE
210 #define MBEDTLS_GET_UINT16_LE( data, offset ) \
211 ( \
212 ( (uint16_t) ( data )[( offset ) ] ) \
213 | ( (uint16_t) ( data )[( offset ) + 1] << 8 ) \
214 )
215 #endif
216
217 /**
218 * Put in memory a 16 bits unsigned integer in little-endian order.
219 *
220 * \param n 16 bits unsigned integer to put in memory.
221 * \param data Base address of the memory where to put the 16
222 * bits unsigned integer in.
223 * \param offset Offset from \p data where to put the least significant
224 * byte of the 16 bits unsigned integer \p n.
225 */
226 #ifndef MBEDTLS_PUT_UINT16_LE
227 #define MBEDTLS_PUT_UINT16_LE( n, data, offset ) \
228 { \
229 ( data )[( offset ) ] = MBEDTLS_BYTE_0( n ); \
230 ( data )[( offset ) + 1] = MBEDTLS_BYTE_1( n ); \
231 }
232 #endif
233
234 /**
235 * Get the unsigned 16 bits integer corresponding to two bytes in
236 * big-endian order (MSB first).
237 *
238 * \param data Base address of the memory to get the two bytes from.
239 * \param offset Offset from \p data of the first and most significant
240 * byte of the two bytes to build the 16 bits unsigned
241 * integer from.
242 */
243 #ifndef MBEDTLS_GET_UINT16_BE
244 #define MBEDTLS_GET_UINT16_BE( data, offset ) \
245 ( \
246 ( (uint16_t) ( data )[( offset ) ] << 8 ) \
247 | ( (uint16_t) ( data )[( offset ) + 1] ) \
248 )
249 #endif
250
251 /**
252 * Put in memory a 16 bits unsigned integer in big-endian order.
253 *
254 * \param n 16 bits unsigned integer to put in memory.
255 * \param data Base address of the memory where to put the 16
256 * bits unsigned integer in.
257 * \param offset Offset from \p data where to put the most significant
258 * byte of the 16 bits unsigned integer \p n.
259 */
260 #ifndef MBEDTLS_PUT_UINT16_BE
261 #define MBEDTLS_PUT_UINT16_BE( n, data, offset ) \
262 { \
263 ( data )[( offset ) ] = MBEDTLS_BYTE_1( n ); \
264 ( data )[( offset ) + 1] = MBEDTLS_BYTE_0( n ); \
265 }
266 #endif
267
268 /**
269 * Get the unsigned 24 bits integer corresponding to three bytes in
270 * big-endian order (MSB first).
271 *
272 * \param data Base address of the memory to get the three bytes from.
273 * \param offset Offset from \p data of the first and most significant
274 * byte of the three bytes to build the 24 bits unsigned
275 * integer from.
276 */
277 #ifndef MBEDTLS_GET_UINT24_BE
278 #define MBEDTLS_GET_UINT24_BE( data , offset ) \
279 ( \
280 ( (uint32_t) ( data )[( offset ) ] << 16 ) \
281 | ( (uint32_t) ( data )[( offset ) + 1] << 8 ) \
282 | ( (uint32_t) ( data )[( offset ) + 2] ) \
283 )
284 #endif
285
286 /**
287 * Put in memory a 24 bits unsigned integer in big-endian order.
288 *
289 * \param n 24 bits unsigned integer to put in memory.
290 * \param data Base address of the memory where to put the 24
291 * bits unsigned integer in.
292 * \param offset Offset from \p data where to put the most significant
293 * byte of the 24 bits unsigned integer \p n.
294 */
295 #ifndef MBEDTLS_PUT_UINT24_BE
296 #define MBEDTLS_PUT_UINT24_BE( n, data, offset ) \
297 { \
298 ( data )[( offset ) ] = MBEDTLS_BYTE_2( n ); \
299 ( data )[( offset ) + 1] = MBEDTLS_BYTE_1( n ); \
300 ( data )[( offset ) + 2] = MBEDTLS_BYTE_0( n ); \
301 }
302 #endif
303
304 /**
305 * Get the unsigned 24 bits integer corresponding to three bytes in
306 * little-endian order (LSB first).
307 *
308 * \param data Base address of the memory to get the three bytes from.
309 * \param offset Offset from \p data of the first and least significant
310 * byte of the three bytes to build the 24 bits unsigned
311 * integer from.
312 */
313 #ifndef MBEDTLS_GET_UINT24_LE
314 #define MBEDTLS_GET_UINT24_LE( data, offset ) \
315 ( \
316 ( (uint32_t) ( data )[( offset ) ] ) \
317 | ( (uint32_t) ( data )[( offset ) + 1] << 8 ) \
318 | ( (uint32_t) ( data )[( offset ) + 2] << 16 ) \
319 )
320 #endif
321
322 /**
323 * Put in memory a 24 bits unsigned integer in little-endian order.
324 *
325 * \param n 24 bits unsigned integer to put in memory.
326 * \param data Base address of the memory where to put the 24
327 * bits unsigned integer in.
328 * \param offset Offset from \p data where to put the least significant
329 * byte of the 24 bits unsigned integer \p n.
330 */
331 #ifndef MBEDTLS_PUT_UINT24_LE
332 #define MBEDTLS_PUT_UINT24_LE( n, data, offset ) \
333 { \
334 ( data )[( offset ) ] = MBEDTLS_BYTE_0( n ); \
335 ( data )[( offset ) + 1] = MBEDTLS_BYTE_1( n ); \
336 ( data )[( offset ) + 2] = MBEDTLS_BYTE_2( n ); \
337 }
338 #endif
339
340 /**
341 * Get the unsigned 64 bits integer corresponding to eight bytes in
342 * big-endian order (MSB first).
343 *
344 * \param data Base address of the memory to get the eight bytes from.
345 * \param offset Offset from \p data of the first and most significant
346 * byte of the eight bytes to build the 64 bits unsigned
347 * integer from.
348 */
349 #ifndef MBEDTLS_GET_UINT64_BE
350 #define MBEDTLS_GET_UINT64_BE( data, offset ) \
351 ( \
352 ( (uint64_t) ( data )[( offset ) ] << 56 ) \
353 | ( (uint64_t) ( data )[( offset ) + 1] << 48 ) \
354 | ( (uint64_t) ( data )[( offset ) + 2] << 40 ) \
355 | ( (uint64_t) ( data )[( offset ) + 3] << 32 ) \
356 | ( (uint64_t) ( data )[( offset ) + 4] << 24 ) \
357 | ( (uint64_t) ( data )[( offset ) + 5] << 16 ) \
358 | ( (uint64_t) ( data )[( offset ) + 6] << 8 ) \
359 | ( (uint64_t) ( data )[( offset ) + 7] ) \
360 )
361 #endif
362
363 /**
364 * Put in memory a 64 bits unsigned integer in big-endian order.
365 *
366 * \param n 64 bits unsigned integer to put in memory.
367 * \param data Base address of the memory where to put the 64
368 * bits unsigned integer in.
369 * \param offset Offset from \p data where to put the most significant
370 * byte of the 64 bits unsigned integer \p n.
371 */
372 #ifndef MBEDTLS_PUT_UINT64_BE
373 #define MBEDTLS_PUT_UINT64_BE( n, data, offset ) \
374 { \
375 ( data )[( offset ) ] = MBEDTLS_BYTE_7( n ); \
376 ( data )[( offset ) + 1] = MBEDTLS_BYTE_6( n ); \
377 ( data )[( offset ) + 2] = MBEDTLS_BYTE_5( n ); \
378 ( data )[( offset ) + 3] = MBEDTLS_BYTE_4( n ); \
379 ( data )[( offset ) + 4] = MBEDTLS_BYTE_3( n ); \
380 ( data )[( offset ) + 5] = MBEDTLS_BYTE_2( n ); \
381 ( data )[( offset ) + 6] = MBEDTLS_BYTE_1( n ); \
382 ( data )[( offset ) + 7] = MBEDTLS_BYTE_0( n ); \
383 }
384 #endif
385
386 /**
387 * Get the unsigned 64 bits integer corresponding to eight bytes in
388 * little-endian order (LSB first).
389 *
390 * \param data Base address of the memory to get the eight bytes from.
391 * \param offset Offset from \p data of the first and least significant
392 * byte of the eight bytes to build the 64 bits unsigned
393 * integer from.
394 */
395 #ifndef MBEDTLS_GET_UINT64_LE
396 #define MBEDTLS_GET_UINT64_LE( data, offset ) \
397 ( \
398 ( (uint64_t) ( data )[( offset ) + 7] << 56 ) \
399 | ( (uint64_t) ( data )[( offset ) + 6] << 48 ) \
400 | ( (uint64_t) ( data )[( offset ) + 5] << 40 ) \
401 | ( (uint64_t) ( data )[( offset ) + 4] << 32 ) \
402 | ( (uint64_t) ( data )[( offset ) + 3] << 24 ) \
403 | ( (uint64_t) ( data )[( offset ) + 2] << 16 ) \
404 | ( (uint64_t) ( data )[( offset ) + 1] << 8 ) \
405 | ( (uint64_t) ( data )[( offset ) ] ) \
406 )
407 #endif
408
409 /**
410 * Put in memory a 64 bits unsigned integer in little-endian order.
411 *
412 * \param n 64 bits unsigned integer to put in memory.
413 * \param data Base address of the memory where to put the 64
414 * bits unsigned integer in.
415 * \param offset Offset from \p data where to put the least significant
416 * byte of the 64 bits unsigned integer \p n.
417 */
418 #ifndef MBEDTLS_PUT_UINT64_LE
419 #define MBEDTLS_PUT_UINT64_LE( n, data, offset ) \
420 { \
421 ( data )[( offset ) ] = MBEDTLS_BYTE_0( n ); \
422 ( data )[( offset ) + 1] = MBEDTLS_BYTE_1( n ); \
423 ( data )[( offset ) + 2] = MBEDTLS_BYTE_2( n ); \
424 ( data )[( offset ) + 3] = MBEDTLS_BYTE_3( n ); \
425 ( data )[( offset ) + 4] = MBEDTLS_BYTE_4( n ); \
426 ( data )[( offset ) + 5] = MBEDTLS_BYTE_5( n ); \
427 ( data )[( offset ) + 6] = MBEDTLS_BYTE_6( n ); \
428 ( data )[( offset ) + 7] = MBEDTLS_BYTE_7( n ); \
429 }
430 #endif
431
432 /* Fix MSVC C99 compatible issue
433 * MSVC support __func__ from visual studio 2015( 1900 )
434 * Use MSVC predefine macro to avoid name check fail.
435 */
436 #if (defined(_MSC_VER) && ( _MSC_VER <= 1900 ))
437 #define /*no-check-names*/ __func__ __FUNCTION__
438 #endif
439
440 #endif /* MBEDTLS_LIBRARY_COMMON_H */
441
