$NetBSD: RAND_DRBG_new.3,v 1.3 2020/12/10 00:33:12 christos Exp $

Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35)

Standard preamble:
========================================================================
..

..

.. Set up some character translations and predefined strings. \*(-- will
give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
double quote, and \*(R" will give a right double quote. \*(C+ will
give a nicer C++. Capital omega is used to do unbreakable dashes and
therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
nothing in troff, for use with C<>.
.tr \(*W- . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\}
Escape single quotes in literal strings from groff's Unicode transform.

If the F register is >0, we'll generate index entries on stderr for
titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
entries marked with X<> in POD. Of course, you'll have to process the
output yourself in some meaningful fashion.

Avoid warning from groff about undefined register 'F'.
.. .nr rF 0 . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF
Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
Fear. Run. Save yourself. No user-serviceable parts.
. \" fudge factors for nroff and troff . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] .\} . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents . \" corrections for vroff . \" for low resolution devices (crt and lpr) \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} ========================================================================

Title "RAND_DRBG_new 3" For nroff, turn off justification. Always turn off hyphenation; it makes
way too many mistakes in technical documents.
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 libcrypto, -lcrypto Header "SYNOPSIS" .Vb 1 #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); .Ve Header "DESCRIPTION" \fBRAND_DRBG_new() and RAND_DRBG_secure_new() create a new \s-1DRBG\s0 instance of the given type, allocated from the heap resp. the secure heap (using OPENSSL_zalloc() resp. OPENSSL_secure_zalloc()).

\fBRAND_DRBG_set() initializes the drbg with the given type and flags.

\fBRAND_DRBG_set_defaults() sets the default type and flags for new \s-1DRBG\s0 instances.

Currently, all \s-1DRBG\s0 types are based on AES-CTR, so type can be one of the following values: NID_aes_128_ctr, NID_aes_192_ctr, NID_aes_256_ctr. Before the \s-1DRBG\s0 can be used to generate random bits, it is necessary to set its type and to instantiate it.

The optional flags argument specifies a set of bit flags which can be joined using the | operator. Currently, the only flag is \s-1RAND_DRBG_FLAG_CTR_NO_DF,\s0 which disables the use of the derivation function ctr_df. For an explanation, see [\s-1NIST SP 800-90A\s0 Rev. 1].

If a parent instance is specified then this will be used instead of the default entropy source for reseeding the drbg. It is said that the \fBdrbg is chained to its parent. For more information, see the \s-1NOTES\s0 section.

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

\fBRAND_DRBG_uninstantiate() clears the internal state of the drbg and puts it back in the uninstantiated state.

Header "RETURN VALUES" \fBRAND_DRBG_new() and RAND_DRBG_secure_new() return a pointer to a \s-1DRBG\s0 instance allocated on the heap, resp. secure heap.

\fBRAND_DRBG_set(), \fBRAND_DRBG_instantiate(), and \fBRAND_DRBG_uninstantiate() return 1 on success, and 0 on failure.

\fBRAND_DRBG_free() does not return a value.

Header "NOTES" The \s-1DRBG\s0 design supports chaining, which means that a \s-1DRBG\s0 instance can use another parent \s-1DRBG\s0 instance instead of the default entropy source to obtain fresh random input for reseeding, provided that parent \s-1DRBG\s0 instance was properly instantiated, either from a trusted entropy source, or from yet another parent \s-1DRBG\s0 instance. For a detailed description of the reseeding process, see \s-1RAND_DRBG\s0\|(7).

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

Header "SEE ALSO" \fBOPENSSL_zalloc\|(3), \fBOPENSSL_secure_zalloc\|(3), \fBRAND_DRBG_generate\|(3), \s-1RAND_DRBG\s0\|(7) Header "HISTORY" The \s-1RAND_DRBG\s0 functions were added in OpenSSL 1.1.1. Header "COPYRIGHT" Copyright 2017-2020 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the OpenSSL license (the \*(L"License\*(R"). You may not use this file except in compliance with the License. You can obtain a copy in the file \s-1LICENSE\s0 in the source distribution or at <https://www.openssl.org/source/license.html>.