199 lines
7.8 KiB
HTML
Executable File
199 lines
7.8 KiB
HTML
Executable File
<?xml version="1.0" ?>
|
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
|
|
<html xmlns="http://www.w3.org/1999/xhtml">
|
|
<head>
|
|
<title>RAND_DRBG_new</title>
|
|
<meta http-equiv="content-type" content="text/html; charset=utf-8" />
|
|
<link rev="made" href="mailto:root@localhost" />
|
|
</head>
|
|
|
|
<body style="background-color: white">
|
|
|
|
|
|
<!-- INDEX BEGIN -->
|
|
<div name="index">
|
|
<p><a name="__index__"></a></p>
|
|
|
|
<ul>
|
|
|
|
<li><a href="#name">NAME</a></li>
|
|
<li><a href="#synopsis">SYNOPSIS</a></li>
|
|
<li><a href="#description">DESCRIPTION</a></li>
|
|
<li><a href="#return_values">RETURN VALUES</a></li>
|
|
<li><a href="#notes">NOTES</a></li>
|
|
<li><a href="#see_also">SEE ALSO</a></li>
|
|
<li><a href="#history">HISTORY</a></li>
|
|
<li><a href="#copyright">COPYRIGHT</a></li>
|
|
</ul>
|
|
|
|
<hr name="index" />
|
|
</div>
|
|
<!-- INDEX END -->
|
|
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="name">NAME</a></h1>
|
|
<p>RAND_DRBG_new_ex,
|
|
RAND_DRBG_new,
|
|
RAND_DRBG_secure_new_ex,
|
|
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</p>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="synopsis">SYNOPSIS</a></h1>
|
|
<pre>
|
|
#include <openssl/rand_drbg.h></pre>
|
|
<pre>
|
|
RAND_DRBG *RAND_DRBG_new_ex(OPENSSL_CTX *ctx,
|
|
int type,
|
|
unsigned int flags,
|
|
RAND_DRBG *parent);</pre>
|
|
<pre>
|
|
RAND_DRBG *RAND_DRBG_new(int type,
|
|
unsigned int flags,
|
|
RAND_DRBG *parent);</pre>
|
|
<pre>
|
|
RAND_DRBG *RAND_DRBG_secure_new_ex(OPENSSL_CTX *ctx,
|
|
int type,
|
|
unsigned int flags,
|
|
RAND_DRBG *parent);</pre>
|
|
<pre>
|
|
RAND_DRBG *RAND_DRBG_secure_new(int type,
|
|
unsigned int flags,
|
|
RAND_DRBG *parent);</pre>
|
|
<pre>
|
|
int RAND_DRBG_set(RAND_DRBG *drbg,
|
|
int type, unsigned int flags);</pre>
|
|
<pre>
|
|
int RAND_DRBG_set_defaults(int type, unsigned int flags);</pre>
|
|
<pre>
|
|
int RAND_DRBG_instantiate(RAND_DRBG *drbg,
|
|
const unsigned char *pers, size_t perslen);</pre>
|
|
<pre>
|
|
int RAND_DRBG_uninstantiate(RAND_DRBG *drbg);</pre>
|
|
<pre>
|
|
void RAND_DRBG_free(RAND_DRBG *drbg);</pre>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="description">DESCRIPTION</a></h1>
|
|
<p><code>RAND_DRBG_new_ex()</code> and <code>RAND_DRBG_secure_new_ex()</code>
|
|
create a new DRBG instance of the given <strong>type</strong>, allocated from the heap resp.
|
|
the secure heap, for the given OPENSSL_CTX <ctx>
|
|
(using <code>OPENSSL_zalloc()</code> resp. OPENSSL_secure_zalloc()). The <ctx> parameter can
|
|
be NULL in which case the default OPENSSL_CTX is used. <code>RAND_DRBG_new()</code> and
|
|
<code>RAND_DRBG_secure_new()</code> are the same as <code>RAND_DRBG_new_ex()</code> and
|
|
<code>RAND_DRBG_secure_new_ex()</code> except that the default OPENSSL_CTX is always used.</p>
|
|
<p><code>RAND_DRBG_set()</code> initializes the <strong>drbg</strong> with the given <strong>type</strong> and <strong>flags</strong>.</p>
|
|
<p><code>RAND_DRBG_set_defaults()</code> sets the default <strong>type</strong> and <strong>flags</strong> for new DRBG
|
|
instances.</p>
|
|
<p>The DRBG types are AES-CTR, HMAC and HASH so <strong>type</strong> can be one of the
|
|
following values:</p>
|
|
<p>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.</p>
|
|
<p>If this method is not called then the default type is given by NID_aes_256_ctr
|
|
and the default flags are zero.</p>
|
|
<p>Before the DRBG can be used to generate random bits, it is necessary to set
|
|
its type and to instantiate it.</p>
|
|
<p>The optional <strong>flags</strong> argument specifies a set of bit flags which can be
|
|
joined using the | operator. The supported flags are:</p>
|
|
<dl>
|
|
<dt><strong><a name="rand_drbg_flag_ctr_no_df" class="item">RAND_DRBG_FLAG_CTR_NO_DF</a></strong></dt>
|
|
|
|
<dd>
|
|
<p>Disables the use of the derivation function ctr_df. For an explanation,
|
|
see [NIST SP 800-90A Rev. 1].</p>
|
|
</dd>
|
|
<dt><strong><a name="rand_drbg_flag_hmac" class="item">RAND_DRBG_FLAG_HMAC</a></strong></dt>
|
|
|
|
<dd>
|
|
<p>Enables use of HMAC instead of the HASH DRBG.</p>
|
|
</dd>
|
|
<dt><strong><a name="rand_drbg_flag_master" class="item">RAND_DRBG_FLAG_MASTER</a></strong></dt>
|
|
|
|
<dt><strong><a name="rand_drbg_flag_public" class="item">RAND_DRBG_FLAG_PUBLIC</a></strong></dt>
|
|
|
|
<dt><strong><a name="rand_drbg_flag_private" class="item">RAND_DRBG_FLAG_PRIVATE</a></strong></dt>
|
|
|
|
<dd>
|
|
<p>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
|
|
<strong>drbg</strong> chain (<master>, <public> and <private>).</p>
|
|
</dd>
|
|
</dl>
|
|
<p>If a <strong>parent</strong> instance is specified then this will be used instead of
|
|
the default entropy source for reseeding the <strong>drbg</strong>. It is said that the
|
|
<strong>drbg</strong> is <em>chained</em> to its <strong>parent</strong>.
|
|
For more information, see the NOTES section.</p>
|
|
<p><code>RAND_DRBG_instantiate()</code>
|
|
seeds the <strong>drbg</strong> instance using random input from trusted entropy sources.
|
|
Optionally, a personalization string <strong>pers</strong> of length <strong>perslen</strong> can be
|
|
specified.
|
|
To omit the personalization string, set <strong>pers</strong>=NULL and <strong>perslen</strong>=0;</p>
|
|
<p><code>RAND_DRBG_uninstantiate()</code>
|
|
clears the internal state of the <strong>drbg</strong> and puts it back in the
|
|
uninstantiated state.</p>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="return_values">RETURN VALUES</a></h1>
|
|
<p><code>RAND_DRBG_new_ex()</code>, <code>RAND_DRBG_new()</code>, <code>RAND_DRBG_secure_new_ex()</code> and
|
|
<code>RAND_DRBG_secure_new()</code> return a pointer to a DRBG instance allocated on the
|
|
heap, resp. secure heap.</p>
|
|
<p><code>RAND_DRBG_set()</code>,
|
|
<code>RAND_DRBG_instantiate()</code>, and
|
|
<code>RAND_DRBG_uninstantiate()</code>
|
|
return 1 on success, and 0 on failure.</p>
|
|
<p><code>RAND_DRBG_free()</code> does not return a value.</p>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="notes">NOTES</a></h1>
|
|
<p>The DRBG design supports <em>chaining</em>, which means that a DRBG instance can
|
|
use another <strong>parent</strong> DRBG instance instead of the default entropy source
|
|
to obtain fresh random input for reseeding, provided that <strong>parent</strong> 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 <em>RAND_DRBG(7)</em>.</p>
|
|
<p>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
|
|
<code>RAND_DRBG_set_defaults()</code> before creating any thread and before calling any
|
|
cryptographic routines that obtain random data directly or indirectly.</p>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="see_also">SEE ALSO</a></h1>
|
|
<p><em>OPENSSL_zalloc(3)</em>,
|
|
<em>OPENSSL_secure_zalloc(3)</em>,
|
|
<em>RAND_DRBG_generate(3)</em>,
|
|
<em>RAND_DRBG(7)</em></p>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="history">HISTORY</a></h1>
|
|
<p>The RAND_DRBG functions were added in OpenSSL 1.1.1.</p>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="copyright">COPYRIGHT</a></h1>
|
|
<p>Copyright 2017-2019 The OpenSSL Project Authors. All Rights Reserved.</p>
|
|
<p>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
|
|
<a href="https://www.openssl.org/source/license.html">https://www.openssl.org/source/license.html</a>.</p>
|
|
|
|
</body>
|
|
|
|
</html>
|