common.h File Reference

Utility macros for internal use in the library. More...

#include "mbedtls/build_info.h"
#include "alignment.h"
#include <assert.h>
#include <stddef.h>
#include <stdint.h>

Include dependency graph for common.h:

Go to the source code of this file.

Go to the SVN repository for this file.

Macros
#define	MBEDTLS_STATIC_TESTABLE   static
	Helper to define a function as static except when building invasive tests. More...
#define	MBEDTLS_TEST_HOOK_TEST_ASSERT(TEST)
#define	ARRAY_LENGTH_UNSAFE(array)    (sizeof(array) / sizeof(*(array)))
#define	ARRAY_LENGTH(array)   ARRAY_LENGTH_UNSAFE(array)
	Return the number of elements of a static or stack array. More...
#define	MBEDTLS_ALLOW_PRIVATE_ACCESS
	Allow library to access its structs' private members. More...
#define	asm   __asm__
#define	MBEDTLS_STATIC_ASSERT(expr, msg)
#define	MBEDTLS_HAS_BUILTIN(x)   0
#define	MBEDTLS_LIKELY(x)   x
#define	MBEDTLS_UNLIKELY(x)   x
#define	MBEDTLS_ASSUME(x)   do { } while (0)
#define	MBEDTLS_OPTIMIZE_FOR_PERFORMANCE
#define	MBEDTLS_MAYBE_UNUSED

Functions
void	mbedtls_zeroize_and_free (void *buf, size_t len)
	Securely zeroize a buffer then free it. More...
static unsigned char *	mbedtls_buffer_offset (unsigned char *p, size_t n)
	Return an offset into a buffer. More...
static const unsigned char *	mbedtls_buffer_offset_const (const unsigned char *p, size_t n)
	Return an offset into a read-only buffer. More...
static void	mbedtls_xor (unsigned char *r, const unsigned char *a, const unsigned char *b, size_t n)
	Perform a fast block XOR operation, such that r[i] = a[i] ^ b[i] where 0 <= i < n. More...
static void	mbedtls_xor_no_simd (unsigned char *r, const unsigned char *a, const unsigned char *b, size_t n)
	Perform a fast block XOR operation, such that r[i] = a[i] ^ b[i] where 0 <= i < n. More...

Detailed Description

Utility macros for internal use in the library.

Definition in file common.h.

Macro Definition Documentation

ARRAY_LENGTH

#define ARRAY_LENGTH

(

array

)

ARRAY_LENGTH_UNSAFE(array)

Return the number of elements of a static or stack array.

Parameters

array

A value of array (not pointer) type.

Returns

The number of elements of the array.

Definition at line 100 of file common.h.

ARRAY_LENGTH_UNSAFE

#define ARRAY_LENGTH_UNSAFE

(

array

)

(sizeof(array) / sizeof(*(array)))

Definition at line 73 of file common.h.

asm

#define asm   __asm__

Definition at line 321 of file common.h.

MBEDTLS_ALLOW_PRIVATE_ACCESS

#define MBEDTLS_ALLOW_PRIVATE_ACCESS

Allow library to access its structs' private members.

Although structs defined in header files are publicly available, their members are private and should not be accessed by the user.

Definition at line 107 of file common.h.

MBEDTLS_ASSUME

#define MBEDTLS_ASSUME

(

x

)

do { } while (0)

Definition at line 395 of file common.h.

MBEDTLS_HAS_BUILTIN

#define MBEDTLS_HAS_BUILTIN

(

x

)

0

Definition at line 371 of file common.h.

MBEDTLS_LIKELY

#define MBEDTLS_LIKELY

(

x

)

x

Definition at line 379 of file common.h.

MBEDTLS_MAYBE_UNUSED

#define MBEDTLS_MAYBE_UNUSED

Definition at line 432 of file common.h.

MBEDTLS_OPTIMIZE_FOR_PERFORMANCE

#define MBEDTLS_OPTIMIZE_FOR_PERFORMANCE

Definition at line 405 of file common.h.

MBEDTLS_STATIC_ASSERT

#define MBEDTLS_STATIC_ASSERT	(		expr,
			msg
	)

Definition at line 365 of file common.h.

MBEDTLS_STATIC_TESTABLE

#define MBEDTLS_STATIC_TESTABLE   static

Helper to define a function as static except when building invasive tests.

If a function is only used inside its own source file and should be declared `static` to allow the compiler to optimize for code size, but that function has unit tests, define it with ``` MBEDTLS_STATIC_TESTABLE int mbedtls_foo(...) { ... } ``` and declare it in a header in the `library/` directory with ``` if defined(MBEDTLS_TEST_HOOKS) int mbedtls_foo(...); #endif ```

Definition at line 48 of file common.h.

MBEDTLS_TEST_HOOK_TEST_ASSERT

#define MBEDTLS_TEST_HOOK_TEST_ASSERT

(

TEST

)

Definition at line 61 of file common.h.

MBEDTLS_UNLIKELY

#define MBEDTLS_UNLIKELY

(

x

)

x

Definition at line 380 of file common.h.

Function Documentation

mbedtls_buffer_offset()

static unsigned char* mbedtls_buffer_offset ( unsigned char *  p, size_t  n  )

inlinestatic

Return an offset into a buffer.

This is just the addition of an offset to a pointer, except that this function also accepts an offset of 0 into a buffer whose pointer is null. (`p + n` has undefined behavior when `p` is null, even when `n == 0`. A null pointer is a valid buffer pointer when the size is 0, for example as the result of `malloc(0)` on some platforms.)

Parameters

p	Pointer to a buffer of at least n bytes. This may be NULL if n is zero.
n	An offset in bytes.

Returns

Pointer to offset n in the buffer p. Note that this is only a valid pointer if the size of the buffer is at least n + 1.

Definition at line 138 of file common.h.

References n, and NULL.

mbedtls_buffer_offset_const()

static const unsigned char* mbedtls_buffer_offset_const ( const unsigned char *  p, size_t  n  )

inlinestatic

Return an offset into a read-only buffer.

Similar to mbedtls_buffer_offset(), but for const pointers.

Parameters

p	Pointer to a buffer of at least n bytes. This may be NULL if n is zero.
n	An offset in bytes.

Returns

Pointer to offset n in the buffer p. Note that this is only a valid pointer if the size of the buffer is at least n + 1.

Definition at line 155 of file common.h.

References n, and NULL.

mbedtls_xor()

static void mbedtls_xor ( unsigned char *  r, const unsigned char *  a, const unsigned char *  b, size_t  n  )

inlinestatic

Perform a fast block XOR operation, such that r[i] = a[i] ^ b[i] where 0 <= i < n.

Parameters

r	Pointer to result (buffer of at least n bytes). r may be equal to either a or b, but behaviour when it overlaps in other ways is undefined.
a	Pointer to input (buffer of at least n bytes)
b	Pointer to input (buffer of at least n bytes)
n	Number of bytes to process.

Note

Depending on the situation, it may be faster to use either mbedtls_xor() or mbedtls_xor_no_simd() (these are functionally equivalent). If the result is used immediately after the xor operation in non-SIMD code (e.g, in AES-CBC), there may be additional latency to transfer the data from SIMD to scalar registers, and in this case, mbedtls_xor_no_simd() may be faster. In other cases where the result is not used immediately (e.g., in AES-CTR), mbedtls_xor() may be faster. For targets without SIMD support, they will behave the same.

Definition at line 186 of file common.h.

References a, b, i, mbedtls_get_unaligned_uint32(), mbedtls_get_unaligned_uint64(), mbedtls_put_unaligned_uint32(), mbedtls_put_unaligned_uint64(), n, r(), and v2.

mbedtls_xor_no_simd()

static void mbedtls_xor_no_simd ( unsigned char *  r, const unsigned char *  a, const unsigned char *  b, size_t  n  )

inlinestatic

Perform a fast block XOR operation, such that r[i] = a[i] ^ b[i] where 0 <= i < n.

In some situations, this can perform better than mbedtls_xor() (e.g., it's about 5% better in AES-CBC).

Parameters

r	Pointer to result (buffer of at least n bytes). r may be equal to either a or b, but behaviour when it overlaps in other ways is undefined.
a	Pointer to input (buffer of at least n bytes)
b	Pointer to input (buffer of at least n bytes)
n	Number of bytes to process.

Note

Depending on the situation, it may be faster to use either mbedtls_xor() or mbedtls_xor_no_simd() (these are functionally equivalent). If the result is used immediately after the xor operation in non-SIMD code (e.g, in AES-CBC), there may be additional latency to transfer the data from SIMD to scalar registers, and in this case, mbedtls_xor_no_simd() may be faster. In other cases where the result is not used immediately (e.g., in AES-CTR), mbedtls_xor() may be faster. For targets without SIMD support, they will behave the same.

Definition at line 268 of file common.h.

References a, b, i, mbedtls_get_unaligned_uint32(), mbedtls_get_unaligned_uint64(), mbedtls_put_unaligned_uint32(), mbedtls_put_unaligned_uint64(), n, and r().

mbedtls_zeroize_and_free()

void mbedtls_zeroize_and_free	(	void *	buf,
		size_t	len
	)

Securely zeroize a buffer then free it.

Similar to making consecutive calls to mbedtls_platform_zeroize() and mbedtls_free(), but has code size savings, and potential for optimisation in the future.

Guaranteed to be a no-op if buf is NULL and len is 0.

Parameters

buf	Buffer to be zeroized then freed.
len	Length of the buffer in bytes

Definition at line 139 of file platform_util.c.

References buf, len, mbedtls_free, mbedtls_platform_zeroize(), and NULL.