The RAND_DRBG API did not fit well into the new provider concept as implemented by EVP_RAND and EVP_RAND_CTX. The main reason is that the RAND_DRBG API is a mixture of 'front end' and 'back end' API calls and some of its API calls are rather low-level. This holds in particular for the callback mechanism (RAND_DRBG_set_callbacks()) and the RAND_DRBG type changing mechanism (RAND_DRBG_set()). Adding a compatibility layer to continue supporting the RAND_DRBG API as a legacy API for a regular deprecation period turned out to come at the price of complicating the new provider API unnecessarily. Since the RAND_DRBG API exists only since version 1.1.1, it was decided by the OMC to drop it entirely. Other related changes: Use RNG instead of DRBG in EVP_RAND documentation. The documentation was using DRBG in places where it should have been RNG or CSRNG. Move the RAND_DRBG(7) documentation to EVP_RAND(7). Reviewed-by: Matthias St. Pierre <Matthias.St.Pierre@ncp-e.com> (Merged from https://github.com/openssl/openssl/pull/12509)master
Pauli
3 years ago
parent
4df0d37ff6
commit
7d615e2178
File diff suppressed because it is too large
Load Diff
@ -0,0 +1,69 @@
|
||||
/*
|
||||
* Copyright 2011-2020 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
|
||||
* https://www.openssl.org/source/license.html
|
||||
*/
|
||||
|
||||
#include <openssl/evp.h>
|
||||
#include <openssl/rand.h>
|
||||
#include "rand_local.h"
|
||||
|
||||
/* Implements the default OpenSSL RAND_add() method */
|
||||
static int drbg_add(const void *buf, int num, double randomness)
|
||||
{
|
||||
EVP_RAND_CTX *drbg = RAND_get0_primary(NULL);
|
||||
|
||||
if (drbg == NULL || num <= 0)
|
||||
return 0;
|
||||
|
||||
return EVP_RAND_reseed(drbg, 0, NULL, 0, buf, num);
|
||||
}
|
||||
|
||||
/* Implements the default OpenSSL RAND_seed() method */
|
||||
static int drbg_seed(const void *buf, int num)
|
||||
{
|
||||
return drbg_add(buf, num, num);
|
||||
}
|
||||
|
||||
/* Implements the default OpenSSL RAND_status() method */
|
||||
static int drbg_status(void)
|
||||
{
|
||||
EVP_RAND_CTX *drbg = RAND_get0_primary(NULL);
|
||||
|
||||
if (drbg == NULL)
|
||||
return 0;
|
||||
|
||||
return EVP_RAND_state(drbg) == EVP_RAND_STATE_READY ? 1 : 0;
|
||||
}
|
||||
|
||||
/* Implements the default OpenSSL RAND_bytes() method */
|
||||
static int drbg_bytes(unsigned char *out, int count)
|
||||
{
|
||||
EVP_RAND_CTX *drbg = RAND_get0_public(NULL);
|
||||
|
||||
if (drbg == NULL)
|
||||
return 0;
|
||||
|
||||
return EVP_RAND_generate(drbg, out, count, 0, 0, NULL, 0);
|
||||
}
|
||||
|
||||
RAND_METHOD rand_meth = {
|
||||
drbg_seed,
|
||||
drbg_bytes,
|
||||
NULL,
|
||||
drbg_add,
|
||||
drbg_bytes,
|
||||
drbg_status
|
||||
};
|
||||
|
||||
RAND_METHOD *RAND_OpenSSL(void)
|
||||
{
|
||||
#ifndef FIPS_MODULE
|
||||
return &rand_meth;
|
||||
#else
|
||||
return NULL;
|
||||
#endif
|
||||
}
|
||||
@ -1,90 +0,0 @@
|
||||
=pod
|
||||
|
||||
=head1 NAME
|
||||
|
||||
RAND_DRBG_generate,
|
||||
RAND_DRBG_bytes
|
||||
- generate random bytes using the given drbg instance
|
||||
|
||||
=head1 SYNOPSIS
|
||||
|
||||
#include <openssl/rand_drbg.h>
|
||||
|
||||
int RAND_DRBG_generate(RAND_DRBG *drbg,
|
||||
unsigned char *out, size_t outlen,
|
||||
int prediction_resistance,
|
||||
const unsigned char *adin, size_t adinlen);
|
||||
|
||||
int RAND_DRBG_bytes(RAND_DRBG *drbg,
|
||||
unsigned char *out, size_t outlen);
|
||||
|
||||
|
||||
=head1 DESCRIPTION
|
||||
|
||||
RAND_DRBG_generate() generates B<outlen> random bytes using the given
|
||||
DRBG instance B<drbg> and stores them in the buffer at B<out>.
|
||||
|
||||
Before generating the output, the DRBG instance checks whether the maximum
|
||||
number of generate requests (I<reseed interval>) or the maximum timespan
|
||||
(I<reseed time interval>) since its last seeding have been reached.
|
||||
If this is the case, the DRBG reseeds automatically.
|
||||
Additionally, an immediate reseeding can be requested by setting the
|
||||
B<prediction_resistance> flag to 1.
|
||||
Requesting prediction resistance is a relative expensive operation.
|
||||
See NOTES section for more details.
|
||||
|
||||
The caller can optionally provide additional data to be used for reseeding
|
||||
by passing a pointer B<adin> to a buffer of length B<adinlen>.
|
||||
This additional data is mixed into the internal state of the random
|
||||
generator but does not contribute to the entropy count.
|
||||
The additional data can be omitted by setting B<adin> to NULL and
|
||||
B<adinlen> to 0;
|
||||
|
||||
RAND_DRBG_bytes() generates B<outlen> random bytes using the given
|
||||
DRBG instance B<drbg> and stores them in the buffer at B<out>.
|
||||
This function is a wrapper around the RAND_DRBG_generate() call,
|
||||
which collects some additional data from low entropy sources
|
||||
(e.g., a high resolution timer) and calls
|
||||
RAND_DRBG_generate(drbg, out, outlen, 0, adin, adinlen).
|
||||
|
||||
|
||||
=head1 RETURN VALUES
|
||||
|
||||
RAND_DRBG_generate() and RAND_DRBG_bytes() return 1 on success,
|
||||
and 0 on failure.
|
||||
|
||||
=head1 NOTES
|
||||
|
||||
The I<reseed interval> and I<reseed time interval> of the B<drbg> are set to
|
||||
reasonable default values, which in general do not have to be adjusted.
|
||||
If necessary, they can be changed using L<RAND_DRBG_set_reseed_interval(3)>
|
||||
and L<RAND_DRBG_set_reseed_time_interval(3)>, respectively.
|
||||
|
||||
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.
|
||||
|
||||
=head1 SEE ALSO
|
||||
|
||||
L<RAND_bytes(3)>,
|
||||
L<RAND_DRBG_set_reseed_interval(3)>,
|
||||
L<RAND_DRBG_set_reseed_time_interval(3)>,
|
||||
L<RAND_DRBG(7)>
|
||||
|
||||
=head1 HISTORY
|
||||
|
||||
The RAND_DRBG functions were added in OpenSSL 1.1.1.
|
||||
|
||||
Prediction resistance is supported from OpenSSL 3.0.
|
||||
|
||||
=head1 COPYRIGHT
|
||||
|
||||
Copyright 2017-2019 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
|
||||
@ -1,97 +0,0 @@
|
||||
=pod
|
||||
|
||||
=head1 NAME
|
||||
|
||||
OPENSSL_CTX_get0_primary_drbg,
|
||||
OPENSSL_CTX_get0_public_drbg,
|
||||
OPENSSL_CTX_get0_private_drbg,
|
||||
RAND_DRBG_get0_master,
|
||||
RAND_DRBG_get0_public,
|
||||
RAND_DRBG_get0_private
|
||||
- get access to the global RAND_DRBG instances
|
||||
|
||||
=head1 SYNOPSIS
|
||||
|
||||
#include <openssl/rand_drbg.h>
|
||||
|
||||
RAND_DRBG *OPENSSL_CTX_get0_primary_drbg(OPENSSL_CTX *ctx);
|
||||
RAND_DRBG *OPENSSL_CTX_get0_public_drbg(OPENSSL_CTX *ctx);
|
||||
RAND_DRBG *OPENSSL_CTX_get0_private_drbg(OPENSSL_CTX *ctx);
|
||||
RAND_DRBG *RAND_DRBG_get0_master(void);
|
||||
RAND_DRBG *RAND_DRBG_get0_public(void);
|
||||
RAND_DRBG *RAND_DRBG_get0_private(void);
|
||||
|
||||
|
||||
=head1 DESCRIPTION
|
||||
|
||||
The default RAND API implementation (RAND_OpenSSL()) utilizes three
|
||||
shared DRBG instances which are accessed via the RAND API:
|
||||
|
||||
The I<public> and I<private> DRBG are thread-local instances, which are used
|
||||
by RAND_bytes() and RAND_priv_bytes(), respectively.
|
||||
The I<master> DRBG is a global instance, which is not intended to be used
|
||||
directly, but is used internally to reseed the other two instances.
|
||||
|
||||
These functions here provide access to the shared DRBG instances.
|
||||
|
||||
=head1 RETURN VALUES
|
||||
|
||||
OPENSSL_CTX_get0_primary_drbg() returns a pointer to the I<master> DRBG instance
|
||||
for the given OPENSSL_CTX B<ctx>.
|
||||
|
||||
OPENSSL_CTX_get0_public_drbg() returns a pointer to the I<public> DRBG instance
|
||||
for the given OPENSSL_CTX B<ctx>.
|
||||
|
||||
OPENSSL_CTX_get0_private_drbg() returns a pointer to the I<private> DRBG instance
|
||||
for the given OPENSSL_CTX B<ctx>.
|
||||
|
||||
In all the above cases the B<ctx> parameter can
|
||||
be NULL in which case the default OPENSSL_CTX is used. RAND_DRBG_get0_master(),
|
||||
RAND_DRBG_get0_public() and RAND_DRBG_get0_private() are the same as
|
||||
OPENSSL_CTX_get0_primary_drbg(), OPENSSL_CTX_get0_public_drbg() and
|
||||
OPENSSL_CTX_get0_private_drbg() respectively except that the default OPENSSL_CTX
|
||||
is always used.
|
||||
|
||||
=head1 NOTES
|
||||
|
||||
It is not thread-safe to access the I<master> DRBG instance.
|
||||
The I<public> and I<private> DRBG instance can be accessed safely, because
|
||||
they are thread-local. Note however, that changes to these two instances
|
||||
apply only to the current thread.
|
||||
|
||||
For that reason it is recommended not to change the settings of these
|
||||
three instances directly.
|
||||
Instead, an application should change the default settings for new DRBG instances
|
||||
at initialization time, before creating additional threads.
|
||||
|
||||
During initialization, it is possible to change the reseed interval
|
||||
and reseed time interval.
|
||||
It is also possible to exchange the reseeding callbacks entirely.
|
||||
|
||||
=head1 SEE ALSO
|
||||
|
||||
L<RAND_DRBG_set_callbacks(3)>,
|
||||
L<RAND_DRBG_set_reseed_defaults(3)>,
|
||||
L<RAND_DRBG_set_reseed_interval(3)>,
|
||||
L<RAND_DRBG_set_reseed_time_interval(3)>,
|
||||
L<RAND_DRBG_set_callbacks(3)>,
|
||||
L<RAND_DRBG_generate(3)>,
|
||||
L<RAND_DRBG(7)>
|
||||
|
||||
=head1 HISTORY
|
||||
|
||||
The OPENSSL_CTX_get0_primary_drbg(), OPENSSL_CTX_get0_public_drbg() and
|
||||
OPENSSL_CTX_get0_private_drbg() functions were added in OpenSSL 3.0.
|
||||
|
||||
All other RAND_DRBG functions were added in OpenSSL 1.1.1.
|
||||
|
||||
=head1 COPYRIGHT
|
||||
|
||||
Copyright 2017-2020 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
|
||||
@ -1,170 +0,0 @@
|
||||
=pod
|
||||
|
||||
=head1 NAME
|
||||
|
||||
RAND_DRBG_new_ex,
|
||||
RAND_DRBG_new,
|
||||
RAND_DRBG_set,
|
||||
RAND_DRBG_set_defaults,
|
||||
RAND_DRBG_instantiate,
|
||||
RAND_DRBG_uninstantiate,
|
||||
RAND_DRBG_free,
|
||||
RAND_DRBG_verify_zeroization
|
||||
- initialize and cleanup a RAND_DRBG instance
|
||||
|
||||
=head1 SYNOPSIS
|
||||
|
||||
#include <openssl/rand_drbg.h>
|
||||
|
||||
RAND_DRBG *RAND_DRBG_new_ex(OPENSSL_CTX *ctx,
|
||||
int type,
|
||||
unsigned int flags,
|
||||
RAND_DRBG *parent);
|
||||
|
||||
RAND_DRBG *RAND_DRBG_new(int type,
|
||||
unsigned int flags,
|
||||
RAND_DRBG *parent);
|
||||
|
||||
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);
|
||||
int RAND_DRBG_verify_zeroization(RAND_DRBG *drbg);
|
||||
|
||||
Deprecated since OpenSSL 3.0, can be hidden entirely by defining
|
||||
B<OPENSSL_API_COMPAT> with a suitable version value, see
|
||||
L<openssl_user_macros(7)>:
|
||||
|
||||
int RAND_DRBG_set(RAND_DRBG *drbg,
|
||||
int type, unsigned int flags);
|
||||
|
||||
=head1 DESCRIPTION
|
||||
|
||||
RAND_DRBG_new_ex() creates a new DRBG instance of the given B<type> for the
|
||||
given OPENSSL_CTX <ctx>.
|
||||
The <ctx> parameter can be NULL in which case the default OPENSSL_CTX is used.
|
||||
RAND_DRBG_new() is the same as RAND_DRBG_new_ex() except that the default
|
||||
OPENSSL_CTX is always used.
|
||||
|
||||
RAND_DRBG_set() initializes the B<drbg> with the given B<type> and B<flags>.
|
||||
This function is deprecated. Applications should instead use
|
||||
RAND_DRBG_new_ex() to create a new DRBG.
|
||||
|
||||
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_PRIMARY
|
||||
|
||||
=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.
|
||||
|
||||
RAND_DRBG_verify_zeroization() confirms if the internal DRBG state is
|
||||
currently zeroed.
|
||||
|
||||
=head1 RETURN VALUES
|
||||
|
||||
|
||||
RAND_DRBG_new_ex() and RAND_DRBG_new() return a pointer to a DRBG instance
|
||||
allocated on the heap.
|
||||
|
||||
RAND_DRBG_set(),
|
||||
RAND_DRBG_instantiate(), and
|
||||
RAND_DRBG_uninstantiate()
|
||||
return 1 on success, and 0 on failure.
|
||||
|
||||
RAND_DRBG_verify_zeroization() returns 1 if the DRBG state is current zeroed,
|
||||
and 0 if not.
|
||||
|
||||
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 SEE ALSO
|
||||
|
||||
L<RAND_DRBG_generate(3)>,
|
||||
L<RAND_DRBG(7)>
|
||||
|
||||
=head1 HISTORY
|
||||
|
||||
The RAND_DRBG_set() function was deprecated in OpenSSL 3.0.
|
||||
|
||||
The RAND_DRBG functions were added in OpenSSL 1.1.1.
|
||||
|
||||
=head1 COPYRIGHT
|
||||
|
||||
Copyright 2017-2020 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
|
||||
@ -1,118 +0,0 @@
|
||||
=pod
|
||||
|
||||
=head1 NAME
|
||||
|
||||
RAND_DRBG_reseed,
|
||||
RAND_DRBG_set_reseed_interval,
|
||||
RAND_DRBG_set_reseed_time_interval,
|
||||
RAND_DRBG_set_reseed_defaults
|
||||
- reseed a RAND_DRBG instance
|
||||
|
||||
=head1 SYNOPSIS
|
||||
|
||||
#include <openssl/rand_drbg.h>
|
||||
|
||||
int RAND_DRBG_reseed(RAND_DRBG *drbg,
|
||||
const unsigned char *adin, size_t adinlen,
|
||||
int prediction_resistance);
|
||||
|
||||
int RAND_DRBG_set_reseed_interval(RAND_DRBG *drbg,
|
||||
unsigned int interval);
|
||||
|
||||
int RAND_DRBG_set_reseed_time_interval(RAND_DRBG *drbg,
|
||||
time_t interval);
|
||||
|
||||
int RAND_DRBG_set_reseed_defaults(
|
||||
unsigned int primary_reseed_interval,
|
||||
unsigned int secondary_reseed_interval,
|
||||
time_t primary_reseed_time_interval,
|
||||
time_t secondary_reseed_time_interval
|
||||
);
|
||||
|
||||
|
||||
=head1 DESCRIPTION
|
||||
|
||||
RAND_DRBG_reseed()
|
||||
reseeds the given B<drbg>, obtaining entropy input from its entropy source
|
||||
and mixing in the specified additional data provided in the buffer B<adin>
|
||||
of length B<adinlen>.
|
||||
The additional data can be omitted by setting B<adin> to NULL and B<adinlen>
|
||||
to 0.
|
||||
An immediate reseeding can be requested by setting the
|
||||
B<prediction_resistance> flag to 1.
|
||||
Requesting prediction resistance is a relative expensive operation.
|
||||
See NOTES section for more details.
|
||||
|
||||
RAND_DRBG_set_reseed_interval()
|
||||
sets the reseed interval of the B<drbg>, which is the maximum allowed number
|
||||
of generate requests between consecutive reseedings.
|
||||
If B<interval> > 0, then the B<drbg> will reseed automatically whenever the
|
||||
number of generate requests since its last seeding exceeds the given reseed
|
||||
interval.
|
||||
If B<interval> == 0, then this feature is disabled.
|
||||
|
||||
|
||||
RAND_DRBG_set_reseed_time_interval()
|
||||
sets the reseed time interval of the B<drbg>, which is the maximum allowed
|
||||
number of seconds between consecutive reseedings.
|
||||
If B<interval> > 0, then the B<drbg> will reseed automatically whenever the
|
||||
elapsed time since its last reseeding exceeds the given reseed time interval.
|
||||
If B<interval> == 0, then this feature is disabled.
|
||||
|
||||
RAND_DRBG_set_reseed_defaults() sets the default values for the reseed interval
|
||||
(B<primary_reseed_interval> and B<secondary_reseed_interval>)
|
||||
and the reseed time interval
|
||||
(B<primary_reseed_time_interval> and B<secondary_reseed_tme_interval>)
|
||||
of DRBG instances.
|
||||
The default values are set independently for primary DRBG instances (which don't
|
||||
have a parent) and secondary DRBG instances (which are chained to a parent
|
||||
DRBG).
|
||||
|
||||
=head1 RETURN VALUES
|
||||
|
||||
RAND_DRBG_reseed(),
|
||||
RAND_DRBG_set_reseed_interval(), and
|
||||
RAND_DRBG_set_reseed_time_interval(),
|
||||
return 1 on success, 0 on failure.
|
||||
|
||||
=head1 NOTES
|
||||
|
||||
The default OpenSSL random generator is already set up for automatic reseeding,
|
||||
so in general it is not necessary to reseed it explicitly, or to modify
|
||||
its reseeding thresholds.
|
||||
|
||||
Normally, the entropy input for seeding a DRBG is either obtained from a
|
||||
trusted os entropy source or from a parent DRBG instance, which was seeded
|
||||
(directly or indirectly) from a trusted os entropy source.
|
||||
In exceptional cases it is possible to replace the reseeding mechanism entirely
|
||||
by providing application defined callbacks using RAND_DRBG_set_callbacks().
|
||||
|
||||
The reseeding default values are applied only during creation of a DRBG instance.
|
||||
To ensure that they are applied to the global and thread-local DRBG instances
|
||||
(<primary>, resp. <public> and <private>), it is necessary to call
|
||||
RAND_DRBG_set_reseed_defaults() before creating any thread and before calling
|
||||
any cryptographic routines that obtain random data directly or indirectly.
|
||||
|
||||
=head1 SEE ALSO
|
||||
|
||||
L<RAND_DRBG_generate(3)>,
|
||||
L<RAND_DRBG_bytes(3)>,
|
||||
L<RAND_DRBG_set_callbacks(3)>.
|
||||
L<RAND_DRBG(7)>
|
||||
|
||||
=head1 HISTORY
|
||||
|
||||
The RAND_DRBG functions were added in OpenSSL 1.1.1.
|
||||
|
||||
Prediction resistance is supported from OpenSSL 3.0.
|
||||
|
||||
=head1 COPYRIGHT
|
||||
|
||||
Copyright 2017-2020 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
|
||||
@ -1,171 +0,0 @@
|
||||
=pod
|
||||
|
||||
=head1 NAME
|
||||
|
||||
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
|
||||
|
||||
=head1 SYNOPSIS
|
||||
|
||||
#include <openssl/rand_drbg.h>
|
||||
|
||||
|
||||
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);
|
||||
|
||||
int RAND_DRBG_set_callback_data(RAND_DRBG *drbg, void *ctx);
|
||||
|
||||
void *RAND_DRBG_get_callback_data(RAND_DRBG *drbg);
|
||||
|
||||
=head2 Callback Functions
|
||||
|
||||
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);
|
||||
|
||||
typedef void (*RAND_DRBG_cleanup_entropy_fn)(
|
||||
RAND_DRBG *drbg,
|
||||
unsigned char *out, size_t outlen);
|
||||
|
||||
typedef size_t (*RAND_DRBG_get_nonce_fn)(
|
||||
RAND_DRBG *drbg,
|
||||
unsigned char **pout,
|
||||
int entropy,
|
||||
size_t min_len, size_t max_len);
|
||||
|
||||
typedef void (*RAND_DRBG_cleanup_nonce_fn)(
|
||||
RAND_DRBG *drbg,
|
||||
unsigned char *out, size_t outlen);
|
||||
|
||||
|
||||
|
||||
=head1 DESCRIPTION
|
||||
|
||||
RAND_DRBG_set_callbacks() sets the callbacks for obtaining fresh entropy and
|
||||
the nonce when reseeding the given B<drbg>.
|
||||
The callback functions are implemented and provided by the caller.
|
||||
Their parameter lists need to match the function prototypes above.
|
||||
|
||||
RAND_DRBG_set_callback_data() can be used to store a pointer to some context
|
||||
specific data, which can subsequently be retrieved by the entropy and nonce
|
||||
callbacks using RAND_DRBG_get_callback_data().
|
||||
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 callback data see the NOTES section.
|
||||
|
||||
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
|
||||
RAND_DRBG_uninstantiate() first.
|
||||
|
||||
The B<get_entropy>() callback is called by the B<drbg> when it requests fresh
|
||||
random input.
|
||||
It is expected that the callback allocates and fills a random buffer of size
|
||||
B<min_len> <= size <= B<max_len> (in bytes) which contains at least B<entropy>
|
||||
bits of randomness.
|
||||
The B<prediction_resistance> flag indicates whether the reseeding was
|
||||
triggered by a prediction resistance request.
|
||||
|
||||
The buffer's address is to be returned in *B<pout> and the number of collected
|
||||
randomness bytes as return value.
|
||||
|
||||
If the callback fails to acquire at least B<entropy> bits of randomness,
|
||||
it must indicate an error by returning a buffer length of 0.
|
||||
|
||||
If B<prediction_resistance> 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.
|
||||
|
||||
The B<cleanup_entropy>() callback is called from the B<drbg> to clear and
|
||||
free the buffer allocated previously by get_entropy().
|
||||
The values B<out> and B<outlen> are the random buffer's address and length,
|
||||
as returned by the get_entropy() callback.
|
||||
|
||||
The B<get_nonce>() and B<cleanup_nonce>() 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 get_entropy() and cleanup_entropy(),
|
||||
except for the missing prediction_resistance flag.
|
||||
|
||||
If the derivation function is disabled, then no nonce is used for instantiation,
|
||||
and the B<get_nonce>() and B<cleanup_nonce>() callbacks can be omitted by
|
||||
setting them to NULL.
|
||||
|
||||
|
||||
=head1 RETURN VALUES
|
||||
|
||||
RAND_DRBG_set_callbacks() returns 1 on success, and 0 on failure.
|
||||
|
||||
RAND_DRBG_set_callback_data() returns 1 on success, and 0 on failure.
|
||||
|
||||
RAND_DRBG_get_callback_data() returns the pointer to the callback data,
|
||||
which is NULL if none has been set previously.
|
||||
|
||||
=head1 NOTES
|
||||
|
||||
It is important that B<cleanup_entropy>() and B<cleanup_nonce>() clear the buffer
|
||||
contents safely before freeing it, in order not to leave sensitive information
|
||||
about the DRBG's state in memory.
|
||||
|
||||
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.
|
||||
|
||||
The derivation function is disabled by calling the RAND_DRBG_new_ex()
|
||||
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", that is, it contains 8 bits of entropy per byte. In a FIPS context,
|
||||
the derivation function can never be omitted.
|
||||
|
||||
Even if a nonce is required, the B<get_nonce>() and B<cleanup_nonce>()
|
||||
callbacks can be omitted by setting them to NULL.
|
||||
In this case the DRBG will automatically request an extra amount of entropy
|
||||
(using the B<get_entropy>() and B<cleanup_entropy>() callbacks) which it will
|
||||
utilize for the nonce, following the recommendations of [NIST SP 800-90A Rev. 1],
|
||||
section 8.6.7.
|
||||
|
||||
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 RFC6979, which require passing a specified entropy and nonce
|
||||
for instantiating the DRBG.
|
||||
|
||||
=head1 SEE ALSO
|
||||
|
||||
L<RAND_DRBG_new(3)>,
|
||||
L<RAND_DRBG_reseed(3)>,
|
||||
L<RAND_DRBG(7)>
|
||||
|
||||
=head1 HISTORY
|
||||
|
||||
The RAND_DRBG functions were added in OpenSSL 1.1.1.
|
||||
|
||||
=head1 COPYRIGHT
|
||||
|
||||
Copyright 2017-2020 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
|
||||