ctr_drbg.h File Reference

CTR_DRBG based on AES-256 (NIST SP 800-90) More...

#include "aes.h"

Include dependency graph for ctr_drbg.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes
struct	mbedtls_ctr_drbg_context
	CTR_DRBG context structure. More...

Macros
#define	MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED   -0x0034
#define	MBEDTLS_ERR_CTR_DRBG_REQUEST_TOO_BIG   -0x0036
#define	MBEDTLS_ERR_CTR_DRBG_INPUT_TOO_BIG   -0x0038
#define	MBEDTLS_ERR_CTR_DRBG_FILE_IO_ERROR   -0x003A
#define	MBEDTLS_CTR_DRBG_BLOCKSIZE   16
#define	MBEDTLS_CTR_DRBG_KEYSIZE   32
#define	MBEDTLS_CTR_DRBG_KEYBITS   ( MBEDTLS_CTR_DRBG_KEYSIZE * 8 )
#define	MBEDTLS_CTR_DRBG_SEEDLEN   ( MBEDTLS_CTR_DRBG_KEYSIZE + MBEDTLS_CTR_DRBG_BLOCKSIZE )
#define	MBEDTLS_CTR_DRBG_PR_OFF   0
#define	MBEDTLS_CTR_DRBG_PR_ON   1
SECTION: Module settings
The configuration options you can set for this module are in this section. Either change them in config.h or define them on the compiler command line.
#define	MBEDTLS_CTR_DRBG_ENTROPY_LEN   48
#define	MBEDTLS_CTR_DRBG_RESEED_INTERVAL   10000
#define	MBEDTLS_CTR_DRBG_MAX_INPUT   256
#define	MBEDTLS_CTR_DRBG_MAX_REQUEST   1024
#define	MBEDTLS_CTR_DRBG_MAX_SEED_INPUT   384

Functions
void	mbedtls_ctr_drbg_init (mbedtls_ctr_drbg_context *ctx)
	CTR_DRBG context initialization Makes the context ready for mbedtls_ctr_drbg_seed() or mbedtls_ctr_drbg_free(). More...
int	mbedtls_ctr_drbg_seed (mbedtls_ctr_drbg_context *ctx, int(*f_entropy)(void *, unsigned char *, size_t), void *p_entropy, const unsigned char *custom, size_t len)
	CTR_DRBG initial seeding Seed and setup entropy source for future reseeds. More...
void	mbedtls_ctr_drbg_free (mbedtls_ctr_drbg_context *ctx)
	Clear CTR_CRBG context data. More...
void	mbedtls_ctr_drbg_set_prediction_resistance (mbedtls_ctr_drbg_context *ctx, int resistance)
	Enable / disable prediction resistance (Default: Off) More...
void	mbedtls_ctr_drbg_set_entropy_len (mbedtls_ctr_drbg_context *ctx, size_t len)
	Set the amount of entropy grabbed on each (re)seed (Default: MBEDTLS_CTR_DRBG_ENTROPY_LEN) More...
void	mbedtls_ctr_drbg_set_reseed_interval (mbedtls_ctr_drbg_context *ctx, int interval)
	Set the reseed interval (Default: MBEDTLS_CTR_DRBG_RESEED_INTERVAL) More...
int	mbedtls_ctr_drbg_reseed (mbedtls_ctr_drbg_context *ctx, const unsigned char *additional, size_t len)
	CTR_DRBG reseeding (extracts data from entropy source) More...
void	mbedtls_ctr_drbg_update (mbedtls_ctr_drbg_context *ctx, const unsigned char *additional, size_t add_len)
	CTR_DRBG update state. More...
int	mbedtls_ctr_drbg_random_with_add (void *p_rng, unsigned char *output, size_t output_len, const unsigned char *additional, size_t add_len)
	CTR_DRBG generate random with additional update input. More...
int	mbedtls_ctr_drbg_random (void *p_rng, unsigned char *output, size_t output_len)
	CTR_DRBG generate random. More...
int	mbedtls_ctr_drbg_write_seed_file (mbedtls_ctr_drbg_context *ctx, const char *path)
	Write a seed file. More...
int	mbedtls_ctr_drbg_update_seed_file (mbedtls_ctr_drbg_context *ctx, const char *path)
	Read and update a seed file. Seed is added to this instance. More...
int	mbedtls_ctr_drbg_self_test (int verbose)
	Checkup routine. More...
int	mbedtls_ctr_drbg_seed_entropy_len (mbedtls_ctr_drbg_context *, int(*)(void *, unsigned char *, size_t), void *, const unsigned char *, size_t, size_t)

Detailed Description

CTR_DRBG based on AES-256 (NIST SP 800-90)

Copyright (C) 2006-2015, ARM Limited, All Rights Reserved SPDX-License-Identifier: Apache-2.0

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

This file is part of mbed TLS (https://tls.mbed.org)

Macro Definition Documentation

MBEDTLS_CTR_DRBG_BLOCKSIZE

#define MBEDTLS_CTR_DRBG_BLOCKSIZE   16

Block size used by the cipher

MBEDTLS_CTR_DRBG_ENTROPY_LEN

#define MBEDTLS_CTR_DRBG_ENTROPY_LEN   48

Amount of entropy used per seed by default (48 with SHA-512, 32 with SHA-256)

MBEDTLS_CTR_DRBG_KEYBITS

#define MBEDTLS_CTR_DRBG_KEYBITS   ( MBEDTLS_CTR_DRBG_KEYSIZE * 8 )

MBEDTLS_CTR_DRBG_KEYSIZE

#define MBEDTLS_CTR_DRBG_KEYSIZE   32

Key size used by the cipher

MBEDTLS_CTR_DRBG_MAX_INPUT

#define MBEDTLS_CTR_DRBG_MAX_INPUT   256

Maximum number of additional input bytes

MBEDTLS_CTR_DRBG_MAX_REQUEST

#define MBEDTLS_CTR_DRBG_MAX_REQUEST   1024

Maximum number of requested bytes per call

MBEDTLS_CTR_DRBG_MAX_SEED_INPUT

#define MBEDTLS_CTR_DRBG_MAX_SEED_INPUT   384

Maximum size of (re)seed buffer

MBEDTLS_CTR_DRBG_PR_OFF

#define MBEDTLS_CTR_DRBG_PR_OFF   0

No prediction resistance

MBEDTLS_CTR_DRBG_PR_ON

#define MBEDTLS_CTR_DRBG_PR_ON   1

Prediction resistance enabled

MBEDTLS_CTR_DRBG_RESEED_INTERVAL

#define MBEDTLS_CTR_DRBG_RESEED_INTERVAL   10000

Interval before reseed is performed by default

MBEDTLS_CTR_DRBG_SEEDLEN

#define MBEDTLS_CTR_DRBG_SEEDLEN   ( MBEDTLS_CTR_DRBG_KEYSIZE + MBEDTLS_CTR_DRBG_BLOCKSIZE )

The seed length (counter + AES key)

MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED

#define MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED   -0x0034

The entropy source failed.

MBEDTLS_ERR_CTR_DRBG_FILE_IO_ERROR

#define MBEDTLS_ERR_CTR_DRBG_FILE_IO_ERROR   -0x003A

Read/write error in file.

MBEDTLS_ERR_CTR_DRBG_INPUT_TOO_BIG

#define MBEDTLS_ERR_CTR_DRBG_INPUT_TOO_BIG   -0x0038

Input too large (Entropy + additional).

MBEDTLS_ERR_CTR_DRBG_REQUEST_TOO_BIG

#define MBEDTLS_ERR_CTR_DRBG_REQUEST_TOO_BIG   -0x0036

Too many random requested in single call.

Function Documentation

mbedtls_ctr_drbg_free()

void mbedtls_ctr_drbg_free

(

mbedtls_ctr_drbg_context *

ctx

)

Clear CTR_CRBG context data.

Parameters

ctx	CTR_DRBG context to clear

Here is the call graph for this function:

Here is the caller graph for this function:

mbedtls_ctr_drbg_init()

void mbedtls_ctr_drbg_init

(

mbedtls_ctr_drbg_context *

ctx

)

CTR_DRBG context initialization Makes the context ready for mbedtls_ctr_drbg_seed() or mbedtls_ctr_drbg_free().

Parameters

ctx	CTR_DRBG context to be initialized

Here is the call graph for this function:

Here is the caller graph for this function:

mbedtls_ctr_drbg_random()

int mbedtls_ctr_drbg_random	(	void *	p_rng,
		unsigned char *	output,
		size_t	output_len
	)

CTR_DRBG generate random.

Note: Automatically reseeds if reseed_counter is reached.

Parameters

p_rng	CTR_DRBG context
output	Buffer to fill
output_len	Length of the buffer

Returns

0 if successful, or MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED, or MBEDTLS_ERR_CTR_DRBG_REQUEST_TOO_BIG

Here is the call graph for this function:

Here is the caller graph for this function:

mbedtls_ctr_drbg_random_with_add()

int mbedtls_ctr_drbg_random_with_add	(	void *	p_rng,
		unsigned char *	output,
		size_t	output_len,
		const unsigned char *	additional,
		size_t	add_len
	)

CTR_DRBG generate random with additional update input.

Note: Automatically reseeds if reseed_counter is reached.

Parameters

p_rng	CTR_DRBG context
output	Buffer to fill
output_len	Length of the buffer
additional	Additional data to update with (Can be NULL)
add_len	Length of additional data

Returns

0 if successful, or MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED, or MBEDTLS_ERR_CTR_DRBG_REQUEST_TOO_BIG

Here is the call graph for this function:

Here is the caller graph for this function:

mbedtls_ctr_drbg_reseed()

int mbedtls_ctr_drbg_reseed	(	mbedtls_ctr_drbg_context *	ctx,
		const unsigned char *	additional,
		size_t	len
	)

CTR_DRBG reseeding (extracts data from entropy source)

Parameters

ctx	CTR_DRBG context
additional	Additional data to add to state (Can be NULL)
len	Length of additional data

Returns

0 if successful, or MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED

Here is the call graph for this function:

Here is the caller graph for this function:

mbedtls_ctr_drbg_seed()

int mbedtls_ctr_drbg_seed	(	mbedtls_ctr_drbg_context *	ctx,
		int(*)(void *, unsigned char *, size_t)	f_entropy,
		void *	p_entropy,
		const unsigned char *	custom,
		size_t	len
	)

CTR_DRBG initial seeding Seed and setup entropy source for future reseeds.

Note: Personalization data can be provided in addition to the more generic entropy source to make this instantiation as unique as possible.

Parameters

ctx	CTR_DRBG context to be seeded
f_entropy	Entropy callback (p_entropy, buffer to fill, buffer length)
p_entropy	Entropy context
custom	Personalization data (Device specific identifiers) (Can be NULL)
len	Length of personalization data

Returns

0 if successful, or MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED

Here is the call graph for this function:

Here is the caller graph for this function:

mbedtls_ctr_drbg_seed_entropy_len()

int mbedtls_ctr_drbg_seed_entropy_len	(	mbedtls_ctr_drbg_context *	,
		int(*)(void *, unsigned char *, size_t)	,
		void *	,
		const unsigned char *	,
		size_t	,
		size_t
	)

Here is the call graph for this function:

Here is the caller graph for this function:

mbedtls_ctr_drbg_self_test()

int mbedtls_ctr_drbg_self_test

(

int

verbose

)

Checkup routine.

Returns

0 if successful, or 1 if the test failed

Here is the call graph for this function:

mbedtls_ctr_drbg_set_entropy_len()

void mbedtls_ctr_drbg_set_entropy_len	(	mbedtls_ctr_drbg_context *	ctx,
		size_t	len
	)

Set the amount of entropy grabbed on each (re)seed (Default: MBEDTLS_CTR_DRBG_ENTROPY_LEN)

Parameters

ctx	CTR_DRBG context
len	Amount of entropy to grab

mbedtls_ctr_drbg_set_prediction_resistance()

void mbedtls_ctr_drbg_set_prediction_resistance	(	mbedtls_ctr_drbg_context *	ctx,
		int	resistance
	)

Enable / disable prediction resistance (Default: Off)

Note: If enabled, entropy is used for ctx->entropy_len before each call! Only use this if you have ample supply of good entropy!

Parameters

ctx	CTR_DRBG context
resistance	MBEDTLS_CTR_DRBG_PR_ON or MBEDTLS_CTR_DRBG_PR_OFF

Here is the caller graph for this function:

mbedtls_ctr_drbg_set_reseed_interval()

void mbedtls_ctr_drbg_set_reseed_interval	(	mbedtls_ctr_drbg_context *	ctx,
		int	interval
	)

Set the reseed interval (Default: MBEDTLS_CTR_DRBG_RESEED_INTERVAL)

Parameters

ctx	CTR_DRBG context
interval	Reseed interval

mbedtls_ctr_drbg_update()

void mbedtls_ctr_drbg_update	(	mbedtls_ctr_drbg_context *	ctx,
		const unsigned char *	additional,
		size_t	add_len
	)

CTR_DRBG update state.

Parameters

ctx	CTR_DRBG context
additional	Additional data to update state with
add_len	Length of additional data

Note

If add_len is greater than MBEDTLS_CTR_DRBG_MAX_SEED_INPUT, only the first MBEDTLS_CTR_DRBG_MAX_SEED_INPUT bytes are used, the remaining ones are silently discarded.

Here is the call graph for this function:

Here is the caller graph for this function:

mbedtls_ctr_drbg_update_seed_file()

int mbedtls_ctr_drbg_update_seed_file	(	mbedtls_ctr_drbg_context *	ctx,
		const char *	path
	)

Read and update a seed file. Seed is added to this instance.

Parameters

ctx	CTR_DRBG context
path	Name of the file

Returns

0 if successful, MBEDTLS_ERR_CTR_DRBG_FILE_IO_ERROR on file error, MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED or MBEDTLS_ERR_CTR_DRBG_INPUT_TOO_BIG

Here is the call graph for this function:

mbedtls_ctr_drbg_write_seed_file()

int mbedtls_ctr_drbg_write_seed_file	(	mbedtls_ctr_drbg_context *	ctx,
		const char *	path
	)

Write a seed file.

Parameters

ctx	CTR_DRBG context
path	Name of the file

Returns

0 if successful, MBEDTLS_ERR_CTR_DRBG_FILE_IO_ERROR on file error, or MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED

Here is the call graph for this function:

Here is the caller graph for this function: