199 lines
8.6 KiB
HTML
Executable File
199 lines
8.6 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_set_callbacks</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>
|
|
<ul>
|
|
|
|
<li><a href="#callback_functions">Callback Functions</a></li>
|
|
</ul>
|
|
|
|
<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_set_callbacks,
|
|
RAND_DRBG_set_callback_data,
|
|
RAND_DRBG_get_callback_data,
|
|
RAND_DRBG_get_entropy_fn,
|
|
RAND_DRBG_cleanup_entropy_fn,
|
|
RAND_DRBG_get_nonce_fn,
|
|
RAND_DRBG_cleanup_nonce_fn
|
|
- set callbacks for reseeding</p>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="synopsis">SYNOPSIS</a></h1>
|
|
<pre>
|
|
#include <openssl/rand_drbg.h></pre>
|
|
<pre>
|
|
int RAND_DRBG_set_callbacks(RAND_DRBG *drbg,
|
|
RAND_DRBG_get_entropy_fn get_entropy,
|
|
RAND_DRBG_cleanup_entropy_fn cleanup_entropy,
|
|
RAND_DRBG_get_nonce_fn get_nonce,
|
|
RAND_DRBG_cleanup_nonce_fn cleanup_nonce);</pre>
|
|
<pre>
|
|
int RAND_DRBG_set_callback_data(RAND_DRBG *drbg, void *ctx);</pre>
|
|
<pre>
|
|
void *RAND_DRBG_get_callback_data(RAND_DRBG *drbg);</pre>
|
|
<p>
|
|
</p>
|
|
<h2><a name="callback_functions">Callback Functions</a></h2>
|
|
<pre>
|
|
typedef size_t (*RAND_DRBG_get_entropy_fn)(
|
|
RAND_DRBG *drbg,
|
|
unsigned char **pout,
|
|
int entropy,
|
|
size_t min_len, size_t max_len,
|
|
int prediction_resistance);</pre>
|
|
<pre>
|
|
typedef void (*RAND_DRBG_cleanup_entropy_fn)(
|
|
RAND_DRBG *drbg,
|
|
unsigned char *out, size_t outlen);</pre>
|
|
<pre>
|
|
typedef size_t (*RAND_DRBG_get_nonce_fn)(
|
|
RAND_DRBG *drbg,
|
|
unsigned char **pout,
|
|
int entropy,
|
|
size_t min_len, size_t max_len);</pre>
|
|
<pre>
|
|
typedef void (*RAND_DRBG_cleanup_nonce_fn)(
|
|
RAND_DRBG *drbg,
|
|
unsigned char *out, size_t outlen);</pre>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="description">DESCRIPTION</a></h1>
|
|
<p><code>RAND_DRBG_set_callbacks()</code> sets the callbacks for obtaining fresh entropy and
|
|
the nonce when reseeding the given <strong>drbg</strong>.
|
|
The callback functions are implemented and provided by the caller.
|
|
Their parameter lists need to match the function prototypes above.</p>
|
|
<p><code>RAND_DRBG_set_callback_data()</code> can be used to store a pointer to some context
|
|
specific data, which can subsequently be retrieved by the entropy and nonce
|
|
callbacks using <code>RAND_DRBG_get_callback_data()</code>.
|
|
The ownership of the context data remains with the caller, i.e., it is the
|
|
caller's responsibility to keep it available as long as it is needed by the
|
|
callbacks and free it after use.
|
|
For more information about the the callback data see the NOTES section.</p>
|
|
<p>Setting the callbacks or the callback data is allowed only if the DRBG has
|
|
not been initialized yet.
|
|
Otherwise, the operation will fail.
|
|
To change the settings for one of the three shared DRBGs it is necessary to call
|
|
<code>RAND_DRBG_uninstantiate()</code> first.</p>
|
|
<p>The <strong>get_entropy</strong>() callback is called by the <strong>drbg</strong> when it requests fresh
|
|
random input.
|
|
It is expected that the callback allocates and fills a random buffer of size
|
|
<strong>min_len</strong> <= size <= <strong>max_len</strong> (in bytes) which contains at least <strong>entropy</strong>
|
|
bits of randomness.
|
|
The <strong>prediction_resistance</strong> flag indicates whether the reseeding was
|
|
triggered by a prediction resistance request.</p>
|
|
<p>The buffer's address is to be returned in *<strong>pout</strong> and the number of collected
|
|
randomness bytes as return value.</p>
|
|
<p>If the callback fails to acquire at least <strong>entropy</strong> bits of randomness,
|
|
it must indicate an error by returning a buffer length of 0.</p>
|
|
<p>If <strong>prediction_resistance</strong> was requested and the random source of the DRBG
|
|
does not satisfy the conditions requested by [NIST SP 800-90C], then
|
|
it must also indicate an error by returning a buffer length of 0.
|
|
See NOTES section for more details.</p>
|
|
<p>The <strong>cleanup_entropy</strong>() callback is called from the <strong>drbg</strong> to to clear and
|
|
free the buffer allocated previously by <code>get_entropy()</code>.
|
|
The values <strong>out</strong> and <strong>outlen</strong> are the random buffer's address and length,
|
|
as returned by the <code>get_entropy()</code> callback.</p>
|
|
<p>The <strong>get_nonce</strong>() and <strong>cleanup_nonce</strong>() callbacks are used to obtain a nonce
|
|
and free it again. A nonce is only required for instantiation (not for reseeding)
|
|
and only in the case where the DRBG uses a derivation function.
|
|
The callbacks are analogous to <code>get_entropy()</code> and <code>cleanup_entropy()</code>,
|
|
except for the missing prediction_resistance flag.</p>
|
|
<p>If the derivation function is disabled, then no nonce is used for instantiation,
|
|
and the <strong>get_nonce</strong>() and <strong>cleanup_nonce</strong>() callbacks can be omitted by
|
|
setting them to NULL.</p>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="return_values">RETURN VALUES</a></h1>
|
|
<p><code>RAND_DRBG_set_callbacks()</code> returns 1 on success, and 0 on failure.</p>
|
|
<p><code>RAND_DRBG_set_callback_data()</code> returns 1 on success, and 0 on failure.</p>
|
|
<p><code>RAND_DRBG_get_callback_data()</code> returns the pointer to the callback data,
|
|
which is NULL if none has been set previously.</p>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="notes">NOTES</a></h1>
|
|
<p>It is important that <strong>cleanup_entropy</strong>() and <strong>cleanup_nonce</strong>() clear the buffer
|
|
contents safely before freeing it, in order not to leave sensitive information
|
|
about the DRBG's state in memory.</p>
|
|
<p>A request for prediction resistance can only be satisfied by pulling fresh
|
|
entropy from a live entropy source (section 5.5.2 of [NIST SP 800-90C]).
|
|
It is up to the user to ensure that a live entropy source is configured
|
|
and is being used.</p>
|
|
<p>The derivation function is disabled during initialization by calling the
|
|
<code>RAND_DRBG_set()</code> function with the RAND_DRBG_FLAG_CTR_NO_DF flag.
|
|
For more information on the derivation function and when it can be omitted,
|
|
see [NIST SP 800-90A Rev. 1]. Roughly speaking it can be omitted if the random
|
|
source has "full entropy", i.e., contains 8 bits of entropy per byte.</p>
|
|
<p>Even if a nonce is required, the <strong>get_nonce</strong>() and <strong>cleanup_nonce</strong>()
|
|
callbacks can be omitted by setting them to NULL.
|
|
In this case the DRBG will automatically request an extra amount of entropy
|
|
(using the <strong>get_entropy</strong>() and <strong>cleanup_entropy</strong>() callbacks) which it will
|
|
utilize for the nonce, following the recommendations of [NIST SP 800-90A Rev. 1],
|
|
section 8.6.7.</p>
|
|
<p>The callback data is a rather specialized feature, because in general the
|
|
random sources don't (and in fact, they must not) depend on any state provided
|
|
by the DRBG.
|
|
There are however exceptional cases where this feature is useful, most notably
|
|
for implementing known answer tests (KATs) or deterministic signatures like
|
|
those specified in <a href="http://www.ietf.org/rfc/rfc6979.txt" class="rfc">RFC6979</a>, which require passing a specified entropy and nonce
|
|
for instantiating the DRBG.</p>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="see_also">SEE ALSO</a></h1>
|
|
<p><em>RAND_DRBG_new(3)</em>,
|
|
<em>RAND_DRBG_reseed(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>
|