Detailed Description

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

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)

Definition in file ctr_drbg.h.

#include "aes.h"

Include dependency graph for ctr_drbg.h:

Go to the source code of this file.

Data Structures
struct	mbedtls_ctr_drbg_context
	CTR_DRBG context structure. More...

Macros
#define	MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED -0x0034
	The entropy source failed. More...

#define	MBEDTLS_ERR_CTR_DRBG_REQUEST_TOO_BIG -0x0036
	Too many random requested in single call. More...

#define	MBEDTLS_ERR_CTR_DRBG_INPUT_TOO_BIG -0x0038
	Input too large (Entropy + additional). More...

#define	MBEDTLS_ERR_CTR_DRBG_FILE_IO_ERROR -0x003A
	Read/write error in file. More...

#define	MBEDTLS_CTR_DRBG_BLOCKSIZE 16
	Block size used by the cipher. More...

#define	MBEDTLS_CTR_DRBG_KEYSIZE 32
	Key size used by the cipher. More...

#define	MBEDTLS_CTR_DRBG_KEYBITS ( MBEDTLS_CTR_DRBG_KEYSIZE * 8 )

#define	MBEDTLS_CTR_DRBG_SEEDLEN ( MBEDTLS_CTR_DRBG_KEYSIZE + MBEDTLS_CTR_DRBG_BLOCKSIZE )
	The seed length (counter + AES key) More...

#define	MBEDTLS_CTR_DRBG_PR_OFF 0
	No prediction resistance. More...

#define	MBEDTLS_CTR_DRBG_PR_ON 1
	Prediction resistance enabled. More...

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 32
	Amount of entropy used per seed by default (48 with SHA-512, 32 with SHA-256) More...

#define	MBEDTLS_CTR_DRBG_RESEED_INTERVAL 10000
	Interval before reseed is performed by default. More...

#define	MBEDTLS_CTR_DRBG_MAX_INPUT 256
	Maximum number of additional input bytes. More...

#define	MBEDTLS_CTR_DRBG_MAX_REQUEST 1024
	Maximum number of requested bytes per call. More...

#define	MBEDTLS_CTR_DRBG_MAX_SEED_INPUT 384
	Maximum size of (re)seed buffer. More...

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_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)

Macro Definition Documentation

#define MBEDTLS_CTR_DRBG_BLOCKSIZE 16

Block size used by the cipher.

Definition at line 37 of file ctr_drbg.h.

#define MBEDTLS_CTR_DRBG_ENTROPY_LEN 32

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

Definition at line 55 of file ctr_drbg.h.

#define MBEDTLS_CTR_DRBG_KEYBITS ( MBEDTLS_CTR_DRBG_KEYSIZE * 8 )

Definition at line 39 of file ctr_drbg.h.

#define MBEDTLS_CTR_DRBG_KEYSIZE 32

Key size used by the cipher.

Definition at line 38 of file ctr_drbg.h.

#define MBEDTLS_CTR_DRBG_MAX_INPUT 256

Maximum number of additional input bytes.

Definition at line 64 of file ctr_drbg.h.

#define MBEDTLS_CTR_DRBG_MAX_REQUEST 1024

Maximum number of requested bytes per call.

Definition at line 68 of file ctr_drbg.h.

#define MBEDTLS_CTR_DRBG_MAX_SEED_INPUT 384

Maximum size of (re)seed buffer.

Definition at line 72 of file ctr_drbg.h.

#define MBEDTLS_CTR_DRBG_PR_OFF 0

No prediction resistance.

Definition at line 77 of file ctr_drbg.h.

#define MBEDTLS_CTR_DRBG_PR_ON 1

Prediction resistance enabled.

Definition at line 78 of file ctr_drbg.h.

#define MBEDTLS_CTR_DRBG_RESEED_INTERVAL 10000

Interval before reseed is performed by default.

Definition at line 60 of file ctr_drbg.h.

#define MBEDTLS_CTR_DRBG_SEEDLEN ( MBEDTLS_CTR_DRBG_KEYSIZE + MBEDTLS_CTR_DRBG_BLOCKSIZE )

The seed length (counter + AES key)

Definition at line 40 of file ctr_drbg.h.

#define MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED -0x0034

The entropy source failed.

Definition at line 32 of file ctr_drbg.h.

#define MBEDTLS_ERR_CTR_DRBG_FILE_IO_ERROR -0x003A

Read/write error in file.

Definition at line 35 of file ctr_drbg.h.

#define MBEDTLS_ERR_CTR_DRBG_INPUT_TOO_BIG -0x0038

Input too large (Entropy + additional).

Definition at line 34 of file ctr_drbg.h.

#define MBEDTLS_ERR_CTR_DRBG_REQUEST_TOO_BIG -0x0036

Too many random requested in single call.

Definition at line 33 of file ctr_drbg.h.

Function Documentation

void mbedtls_ctr_drbg_free ( mbedtls_ctr_drbg_context * ctx )

Clear CTR_CRBG context data.

Parameters

ctx	CTR_DRBG context to clear

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

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

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

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

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

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
	)

int mbedtls_ctr_drbg_self_test ( int verbose )

Checkup routine.

Returns: 0 if successful, or 1 if the test failed

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

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

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

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.

Detailed Description

Data Structures

Macros

Functions

Macro Definition Documentation

Function Documentation