[thirdparty/openssl.git] / doc / man3 / RAND_DRBG_new.pod

=pod

=head1 NAME

RAND_DRBG_new,
RAND_DRBG_secure_new,
RAND_DRBG_set,
RAND_DRBG_set_defaults,
RAND_DRBG_instantiate,
RAND_DRBG_uninstantiate,
RAND_DRBG_free
- initialize and cleanup a RAND_DRBG instance

=head1 SYNOPSIS

 #include <openssl/rand_drbg.h>


 RAND_DRBG *RAND_DRBG_new(int type,
                          unsigned int flags,
                          RAND_DRBG *parent);

 RAND_DRBG *RAND_DRBG_secure_new(int type,
                                 unsigned int flags,
                                 RAND_DRBG *parent);

 int RAND_DRBG_set(RAND_DRBG *drbg,
                   int type, unsigned int flags);

 int RAND_DRBG_set_defaults(int type, unsigned int flags);

 int RAND_DRBG_instantiate(RAND_DRBG *drbg,
                           const unsigned char *pers, size_t perslen);

 int RAND_DRBG_uninstantiate(RAND_DRBG *drbg);

 void RAND_DRBG_free(RAND_DRBG *drbg);


=head1 DESCRIPTION

RAND_DRBG_new() and RAND_DRBG_secure_new()
create a new DRBG instance of the given B<type>, allocated from the heap resp.
the secure heap
(using OPENSSL_zalloc() resp. OPENSSL_secure_zalloc()).

RAND_DRBG_set() initializes the B<drbg> with the given B<type> and B<flags>.

RAND_DRBG_set_defaults() sets the default B<type> and B<flags> for new DRBG
instances.

The DRBG types are AES-CTR, HMAC and HASH so B<type> can be one of the
following values:

NID_aes_128_ctr, NID_aes_192_ctr, NID_aes_256_ctr, NID_sha1, NID_sha224,
NID_sha256, NID_sha384, NID_sha512, NID_sha512_224, NID_sha512_256,
NID_sha3_224, NID_sha3_256, NID_sha3_384 or NID_sha3_512.

If this method is not called then the default type is given by NID_aes_256_ctr
and the default flags are zero.

Before the DRBG can be used to generate random bits, it is necessary to set
its type and to instantiate it.

The optional B<flags> argument specifies a set of bit flags which can be
joined using the | operator. The supported flags are:

=over 4

=item RAND_DRBG_FLAG_CTR_NO_DF

Disables the use of the derivation function ctr_df. For an explanation,
see [NIST SP 800-90A Rev. 1].

=item RAND_DRBG_FLAG_HMAC

Enables use of HMAC instead of the HASH DRBG.

=item RAND_DRBG_FLAG_MASTER

=item RAND_DRBG_FLAG_PUBLIC

=item RAND_DRBG_FLAG_PRIVATE

These 3 flags can be used to set the individual DRBG types created. Multiple
calls are required to set the types to different values. If none of these 3
flags are used, then the same type and flags are used for all 3 DRBGs in the
B<drbg> chain (<master>, <public> and <private>).

=back

If a B<parent> instance is specified then this will be used instead of
the default entropy source for reseeding the B<drbg>. It is said that the
B<drbg> is I<chained> to its B<parent>.
For more information, see the NOTES section.


RAND_DRBG_instantiate()
seeds the B<drbg> instance using random input from trusted entropy sources.
Optionally, a personalization string B<pers> of length B<perslen> can be
specified.
To omit the personalization string, set B<pers>=NULL and B<perslen>=0;

RAND_DRBG_uninstantiate()
clears the internal state of the B<drbg> and puts it back in the
uninstantiated state.

=head1 RETURN VALUES


RAND_DRBG_new() and RAND_DRBG_secure_new() return a pointer to a DRBG
instance allocated on the heap, resp. secure heap.

RAND_DRBG_set(),
RAND_DRBG_instantiate(), and
RAND_DRBG_uninstantiate()
return 1 on success, and 0 on failure.

RAND_DRBG_free() does not return a value.

=head1 NOTES

The DRBG design supports I<chaining>, which means that a DRBG instance can
use another B<parent> DRBG instance instead of the default entropy source
to obtain fresh random input for reseeding, provided that B<parent> DRBG
instance was properly instantiated, either from a trusted entropy source,
or from yet another parent DRBG instance.
For a detailed description of the reseeding process, see L<RAND_DRBG(7)>.

The default DRBG type and flags are applied only during creation of a DRBG
instance.
To ensure that they are applied to the global and thread-local DRBG instances
(<master>, resp. <public> and <private>), it is necessary to call
RAND_DRBG_set_defaults() before creating any thread and before calling any
cryptographic routines that obtain random data directly or indirectly.

=head1 HISTORY

The RAND_DRBG functions were added in OpenSSL 1.1.1.

=head1 SEE ALSO

L<OPENSSL_zalloc(3)>,
L<OPENSSL_secure_zalloc(3)>,
L<RAND_DRBG_generate(3)>,
L<RAND_DRBG(7)>

=head1 COPYRIGHT

Copyright 2017-2018 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
a73d990e DMSP	1	=pod
	2
	3	=head1 NAME
	4
	5	RAND_DRBG_new,
	6	RAND_DRBG_secure_new,
	7	RAND_DRBG_set,
	8	RAND_DRBG_set_defaults,
	9	RAND_DRBG_instantiate,
	10	RAND_DRBG_uninstantiate,
	11	RAND_DRBG_free
	12	- initialize and cleanup a RAND_DRBG instance
	13
	14	=head1 SYNOPSIS
	15
	16	#include <openssl/rand_drbg.h>
	17
	18
	19	RAND_DRBG *RAND_DRBG_new(int type,
	20	unsigned int flags,
	21	RAND_DRBG *parent);
	22
	23	RAND_DRBG *RAND_DRBG_secure_new(int type,
	24	unsigned int flags,
	25	RAND_DRBG *parent);
	26
	27	int RAND_DRBG_set(RAND_DRBG *drbg,
	28	int type, unsigned int flags);
	29
	30	int RAND_DRBG_set_defaults(int type, unsigned int flags);
	31
	32	int RAND_DRBG_instantiate(RAND_DRBG *drbg,
	33	const unsigned char *pers, size_t perslen);
	34
	35	int RAND_DRBG_uninstantiate(RAND_DRBG *drbg);
	36
	37	void RAND_DRBG_free(RAND_DRBG *drbg);
	38
	39
	40	=head1 DESCRIPTION
	41
	42	RAND_DRBG_new() and RAND_DRBG_secure_new()
	43	create a new DRBG instance of the given B<type>, allocated from the heap resp.
	44	the secure heap
	45	(using OPENSSL_zalloc() resp. OPENSSL_secure_zalloc()).
	46
	47	RAND_DRBG_set() initializes the B<drbg> with the given B<type> and B<flags>.
	48
	49	RAND_DRBG_set_defaults() sets the default B<type> and B<flags> for new DRBG
	50	instances.
	51
8bf36651 SL	52	The DRBG types are AES-CTR, HMAC and HASH so B<type> can be one of the
	53	following values:
	54
	55	NID_aes_128_ctr, NID_aes_192_ctr, NID_aes_256_ctr, NID_sha1, NID_sha224,
	56	NID_sha256, NID_sha384, NID_sha512, NID_sha512_224, NID_sha512_256,
	57	NID_sha3_224, NID_sha3_256, NID_sha3_384 or NID_sha3_512.
	58
f3002a2e SL	59	If this method is not called then the default type is given by NID_aes_256_ctr
f3002a2e SL	60	and the default flags are zero.
8bf36651	61
a73d990e DMSP	62	Before the DRBG can be used to generate random bits, it is necessary to set
	63	its type and to instantiate it.
	64
	65	The optional B<flags> argument specifies a set of bit flags which can be
8bf36651 SL	66	joined using the \| operator. The supported flags are:
	67
	68	=over 4
	69
	70	=item RAND_DRBG_FLAG_CTR_NO_DF
	71
	72	Disables the use of the derivation function ctr_df. For an explanation,
	73	see [NIST SP 800-90A Rev. 1].
	74
	75	=item RAND_DRBG_FLAG_HMAC
	76
	77	Enables use of HMAC instead of the HASH DRBG.
	78
	79	=item RAND_DRBG_FLAG_MASTER
	80
	81	=item RAND_DRBG_FLAG_PUBLIC
	82
	83	=item RAND_DRBG_FLAG_PRIVATE
	84
	85	These 3 flags can be used to set the individual DRBG types created. Multiple
	86	calls are required to set the types to different values. If none of these 3
f3002a2e SL	87	flags are used, then the same type and flags are used for all 3 DRBGs in the
f3002a2e SL	88	B<drbg> chain (<master>, <public> and <private>).
8bf36651 SL	89
8bf36651 SL	90	=back
a73d990e DMSP	91
	92	If a B<parent> instance is specified then this will be used instead of
	93	the default entropy source for reseeding the B<drbg>. It is said that the
	94	B<drbg> is I<chained> to its B<parent>.
	95	For more information, see the NOTES section.
	96
	97
	98	RAND_DRBG_instantiate()
	99	seeds the B<drbg> instance using random input from trusted entropy sources.
	100	Optionally, a personalization string B<pers> of length B<perslen> can be
	101	specified.
	102	To omit the personalization string, set B<pers>=NULL and B<perslen>=0;
	103
	104	RAND_DRBG_uninstantiate()
	105	clears the internal state of the B<drbg> and puts it back in the
	106	uninstantiated state.
	107
	108	=head1 RETURN VALUES
	109
	110
	111	RAND_DRBG_new() and RAND_DRBG_secure_new() return a pointer to a DRBG
	112	instance allocated on the heap, resp. secure heap.
	113
	114	RAND_DRBG_set(),
	115	RAND_DRBG_instantiate(), and
	116	RAND_DRBG_uninstantiate()
	117	return 1 on success, and 0 on failure.
	118
	119	RAND_DRBG_free() does not return a value.
	120
	121	=head1 NOTES
	122
	123	The DRBG design supports I<chaining>, which means that a DRBG instance can
	124	use another B<parent> DRBG instance instead of the default entropy source
	125	to obtain fresh random input for reseeding, provided that B<parent> DRBG
	126	instance was properly instantiated, either from a trusted entropy source,
	127	or from yet another parent DRBG instance.
	128	For a detailed description of the reseeding process, see L<RAND_DRBG(7)>.
	129
	130	The default DRBG type and flags are applied only during creation of a DRBG
	131	instance.
	132	To ensure that they are applied to the global and thread-local DRBG instances
	133	(<master>, resp. <public> and <private>), it is necessary to call
	134	RAND_DRBG_set_defaults() before creating any thread and before calling any
	135	cryptographic routines that obtain random data directly or indirectly.
	136
	137	=head1 HISTORY
	138
	139	The RAND_DRBG functions were added in OpenSSL 1.1.1.
	140
	141	=head1 SEE ALSO
	142
	143	L<OPENSSL_zalloc(3)>,
	144	L<OPENSSL_secure_zalloc(3)>,
	145	L<RAND_DRBG_generate(3)>,
	146	L<RAND_DRBG(7)>
	147
	148	=head1 COPYRIGHT
	149
	150	Copyright 2017-2018 The OpenSSL Project Authors. All Rights Reserved.
	151
4746f25a	152	Licensed under the Apache License 2.0 (the "License"). You may not use
a73d990e DMSP	153	this file except in compliance with the License. You can obtain a copy
	154	in the file LICENSE in the source distribution or at
	155	L<https://www.openssl.org/source/license.html>.
	156
	157	=cut