[thirdparty/openssl.git] / doc / man7 / EVP_RAND-CTR-DRBG.pod

=pod

=head1 NAME

EVP_RAND-CTR-DRBG - The CTR DRBG EVP_RAND implementation

=head1 DESCRIPTION

Support for the counter deterministic random bit generator through the
B<EVP_RAND> API.

=head2 Identity

"CTR-DRBG" is the name for this implementation; it can be used with the
EVP_RAND_fetch() function.

=head2 Supported parameters

The supported parameters are:

=over 4

=item "state" (B<OSSL_RAND_PARAM_STATE>) <integer>

=item "strength" (B<OSSL_RAND_PARAM_STRENGTH>) <unsigned integer>

=item "max_request" (B<OSSL_RAND_PARAM_MAX_REQUEST>) <unsigned integer>

=item "reseed_requests" (B<OSSL_DRBG_PARAM_RESEED_REQUESTS>) <unsigned integer>

=item "reseed_time_interval" (B<OSSL_DRBG_PARAM_RESEED_TIME_INTERVAL>) <integer>

=item "min_entropylen" (B<OSSL_DRBG_PARAM_MIN_ENTROPYLEN>) <unsigned integer>

=item "max_entropylen" (B<OSSL_DRBG_PARAM_MAX_ENTROPYLEN>) <unsigned integer>

=item "min_noncelen" (B<OSSL_DRBG_PARAM_MIN_NONCELEN>) <unsigned integer>

=item "max_noncelen" (B<OSSL_DRBG_PARAM_MAX_NONCELEN>) <unsigned integer>

=item "max_perslen" (B<OSSL_DRBG_PARAM_MAX_PERSLEN>) <unsigned integer>

=item "max_adinlen" (B<OSSL_DRBG_PARAM_MAX_ADINLEN>) <unsigned integer>

=item "reseed_counter" (B<OSSL_DRBG_PARAM_RESEED_COUNTER>) <unsigned integer>

=item "properties" (B<OSSL_DRBG_PARAM_PROPERTIES>) <UTF8 string>

=item "cipher" (B<OSSL_DRBG_PARAM_CIPHER>) <UTF8 string>

These parameters work as described in L<EVP_RAND(3)/PARAMETERS>.

=item "use_derivation_function" (B<OSSL_DRBG_PARAM_USE_DF>) <int>

This Boolean indicates if a derivation function should be used or not.
A nonzero value (the default) uses the derivation function.  A zero value
does not.  The FIPS provider always uses the derivation function and attempts
to set this value result in an error.

=back

=head1 NOTES

A context for CTR DRBG can be obtained by calling:

 EVP_RAND *rand = EVP_RAND_fetch(NULL, "CTR-DRBG", NULL);
 EVP_RAND_CTX *rctx = EVP_RAND_CTX_new(rand);

=head1 EXAMPLES

 EVP_RAND *rand;
 EVP_RAND_CTX *rctx;
 unsigned char bytes[100];
 OSSL_PARAM params[2], *p = params;
 unsigned int strength = 128;

 rand = EVP_RAND_fetch(NULL, "CTR-DRBG", NULL);
 rctx = EVP_RAND_CTX_new(rand, NULL);
 EVP_RAND_free(rand);

 *p++ = OSSL_PARAM_construct_utf8_string(OSSL_DRBG_PARAM_CIPHER,
                                         SN_aes_256_ctr, 0);
 *p = OSSL_PARAM_construct_end();
 EVP_RAND_instantiate(rctx, strength, 0, NULL, 0, params);

 EVP_RAND_generate(rctx, bytes, sizeof(bytes), strength, 0, NULL, 0);

 EVP_RAND_CTX_free(rctx);

=head1 CONFORMING TO

NIST SP 800-90A and SP 800-90B

=head1 SEE ALSO

L<EVP_RAND(3)>,
L<EVP_RAND(3)/PARAMETERS>

=head1 COPYRIGHT

Copyright 2020-2021 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the "License").  You may not use
this file except in compliance with the License.  You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.

=cut
Commit	Line	Data
dc4e74ef P	1	=pod
	2
	3	=head1 NAME
	4
	5	EVP_RAND-CTR-DRBG - The CTR DRBG EVP_RAND implementation
	6
	7	=head1 DESCRIPTION
	8
	9	Support for the counter deterministic random bit generator through the
	10	B<EVP_RAND> API.
	11
	12	=head2 Identity
	13
	14	"CTR-DRBG" is the name for this implementation; it can be used with the
	15	EVP_RAND_fetch() function.
	16
	17	=head2 Supported parameters
	18
	19	The supported parameters are:
	20
	21	=over 4
	22
	23	=item "state" (B<OSSL_RAND_PARAM_STATE>) <integer>
	24
	25	=item "strength" (B<OSSL_RAND_PARAM_STRENGTH>) <unsigned integer>
	26
71febb39 P	27	=item "max_request" (B<OSSL_RAND_PARAM_MAX_REQUEST>) <unsigned integer>
71febb39 P	28
dc4e74ef P	29	=item "reseed_requests" (B<OSSL_DRBG_PARAM_RESEED_REQUESTS>) <unsigned integer>
	30
	31	=item "reseed_time_interval" (B<OSSL_DRBG_PARAM_RESEED_TIME_INTERVAL>) <integer>
	32
dc4e74ef P	33	=item "min_entropylen" (B<OSSL_DRBG_PARAM_MIN_ENTROPYLEN>) <unsigned integer>
	34
	35	=item "max_entropylen" (B<OSSL_DRBG_PARAM_MAX_ENTROPYLEN>) <unsigned integer>
	36
	37	=item "min_noncelen" (B<OSSL_DRBG_PARAM_MIN_NONCELEN>) <unsigned integer>
	38
	39	=item "max_noncelen" (B<OSSL_DRBG_PARAM_MAX_NONCELEN>) <unsigned integer>
	40
	41	=item "max_perslen" (B<OSSL_DRBG_PARAM_MAX_PERSLEN>) <unsigned integer>
	42
	43	=item "max_adinlen" (B<OSSL_DRBG_PARAM_MAX_ADINLEN>) <unsigned integer>
	44
b0614f0a	45	=item "reseed_counter" (B<OSSL_DRBG_PARAM_RESEED_COUNTER>) <unsigned integer>
dc4e74ef P	46
	47	=item "properties" (B<OSSL_DRBG_PARAM_PROPERTIES>) <UTF8 string>
	48
	49	=item "cipher" (B<OSSL_DRBG_PARAM_CIPHER>) <UTF8 string>
	50
	51	These parameters work as described in L<EVP_RAND(3)/PARAMETERS>.
	52
	53	=item "use_derivation_function" (B<OSSL_DRBG_PARAM_USE_DF>) <int>
	54
	55	This Boolean indicates if a derivation function should be used or not.
	56	A nonzero value (the default) uses the derivation function. A zero value
	57	does not. The FIPS provider always uses the derivation function and attempts
	58	to set this value result in an error.
	59
	60	=back
	61
	62	=head1 NOTES
	63
	64	A context for CTR DRBG can be obtained by calling:
	65
	66	EVP_RAND *rand = EVP_RAND_fetch(NULL, "CTR-DRBG", NULL);
	67	EVP_RAND_CTX *rctx = EVP_RAND_CTX_new(rand);
	68
	69	=head1 EXAMPLES
	70
	71	EVP_RAND *rand;
	72	EVP_RAND_CTX *rctx;
	73	unsigned char bytes[100];
	74	OSSL_PARAM params[2], *p = params;
	75	unsigned int strength = 128;
	76
	77	rand = EVP_RAND_fetch(NULL, "CTR-DRBG", NULL);
	78	rctx = EVP_RAND_CTX_new(rand, NULL);
	79	EVP_RAND_free(rand);
	80
	81	*p++ = OSSL_PARAM_construct_utf8_string(OSSL_DRBG_PARAM_CIPHER,
	82	SN_aes_256_ctr, 0);
	83	*p = OSSL_PARAM_construct_end();
f8a5822c	84	EVP_RAND_instantiate(rctx, strength, 0, NULL, 0, params);
dc4e74ef P	85
	86	EVP_RAND_generate(rctx, bytes, sizeof(bytes), strength, 0, NULL, 0);
	87
	88	EVP_RAND_CTX_free(rctx);
	89
	90	=head1 CONFORMING TO
	91
	92	NIST SP 800-90A and SP 800-90B
	93
	94	=head1 SEE ALSO
	95
	96	L<EVP_RAND(3)>,
	97	L<EVP_RAND(3)/PARAMETERS>
	98
	99	=head1 COPYRIGHT
	100
8020d79b	101	Copyright 2020-2021 The OpenSSL Project Authors. All Rights Reserved.
dc4e74ef P	102
	103	Licensed under the Apache License 2.0 (the "License"). You may not use
	104	this file except in compliance with the License. You can obtain a copy
	105	in the file LICENSE in the source distribution or at
	106	L<https://www.openssl.org/source/license.html>.
	107
	108	=cut