mirror of https://github.com/openssl/openssl
evp_rand: documentation
EVP_RAND, the RNGs and provider-rand. Reviewed-by: Matthias St. Pierre <Matthias.St.Pierre@ncp-e.com> (Merged from https://github.com/openssl/openssl/pull/11682)
This commit is contained in:
Pauli
parent
6154f9a7ca
commit
dc4e74ef6c
|
|
@ -1,7 +1,7 @@
|
|||
LIBS=../../libcrypto
|
||||
|
||||
$COMMON=drbg_lib.c rand_lib.c
|
||||
$CRYPTO=randfile.c rand_err.c
|
||||
$CRYPTO=randfile.c rand_err.c rand_deprecated.c
|
||||
|
||||
IF[{- !$disabled{'egd'} -}]
|
||||
$CRYPTO=$CRYPTO rand_egd.c
|
||||
|
|
|
|||
|
|
@ -0,0 +1,35 @@
|
|||
/*
|
||||
* Copyright 1995-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 <e_os.h>
|
||||
#include <openssl/macros.h>
|
||||
#include <openssl/rand.h>
|
||||
|
||||
#if defined(OPENSSL_SYS_WINDOWS) || defined(OPENSSL_SYS_WIN32)
|
||||
# include <windows.h>
|
||||
# if OPENSSL_API_COMPAT < 0x10100000L
|
||||
|
||||
# define DEPRECATED_RAND_FUNCTIONS_DEFINED
|
||||
|
||||
int RAND_event(UINT iMsg, WPARAM wParam, LPARAM lParam)
|
||||
{
|
||||
RAND_poll();
|
||||
return RAND_status();
|
||||
}
|
||||
|
||||
void RAND_screen(void)
|
||||
{
|
||||
RAND_poll();
|
||||
}
|
||||
# endif
|
||||
#endif
|
||||
|
||||
#ifndef DEPRECATED_RAND_FUNCTIONS_DEFINED
|
||||
NON_EMPTY_TRANSLATION_UNIT
|
||||
#endif
|
||||
|
|
@ -16,6 +16,7 @@ B<openssl list>
|
|||
[B<-digest-algorithms>]
|
||||
[B<-kdf-algorithms>]
|
||||
[B<-mac-algorithms>]
|
||||
[B<-random-generators>]
|
||||
[B<-cipher-commands>]
|
||||
[B<-cipher-algorithms>]
|
||||
[B<-public-key-algorithms>]
|
||||
|
|
@ -73,6 +74,16 @@ displayed.
|
|||
In verbose mode, the algorithms provided by a provider will get additional
|
||||
information on what parameters each implementation supports.
|
||||
|
||||
=item B<-random-generators>
|
||||
|
||||
Display a list of random number generators.
|
||||
|
||||
See L</Display of algorithm names> for a description of how names are
|
||||
displayed.
|
||||
|
||||
In verbose mode, the algorithms provided by a provider will get additional
|
||||
information on what parameters each implementation supports.
|
||||
|
||||
=item B<-public-key-algorithms>
|
||||
|
||||
Display a list of public key algorithms, with each algorithm as
|
||||
|
|
|
|||
|
|
@ -0,0 +1,379 @@
|
|||
=pod
|
||||
|
||||
=head1 NAME
|
||||
|
||||
EVP_RAND, EVP_RAND_fetch, EVP_RAND_free, EVP_RAND_up_ref, EVP_RAND_CTX,
|
||||
EVP_RAND_CTX_new, EVP_RAND_CTX_free, EVP_RAND_instantiate,
|
||||
EVP_RAND_uninstantiate, EVP_RAND_generate, EVP_RAND_reseed,
|
||||
EVP_RAND_nonce, EVP_RAND_enable_locking, EVP_RAND_set_callbacks,
|
||||
EVP_RAND_verify_zeroization, EVP_RAND_strength, EVP_RAND_state,
|
||||
EVP_RAND_provider, EVP_RAND_CTX_rand, EVP_RAND_is_a, EVP_RAND_number,
|
||||
EVP_RAND_name, EVP_RAND_names_do_all, EVP_RAND_get_ctx_params,
|
||||
EVP_RAND_set_ctx_params, EVP_RAND_do_all_provided, EVP_RAND_get_params,
|
||||
EVP_RAND_gettable_ctx_params, EVP_RAND_settable_ctx_params,
|
||||
EVP_RAND_gettable_params, EVP_RAND_STATE_UNINITIALISED, EVP_RAND_STATE_READY,
|
||||
EVP_RAND_STATE_ERROR - EVP RAND routines
|
||||
|
||||
=head1 SYNOPSIS
|
||||
|
||||
#include <openssl/evp.h>
|
||||
|
||||
typedef struct evp_rand_st EVP_RAND;
|
||||
typedef struct evp_rand_ctx_st EVP_RAND_CTX;
|
||||
|
||||
EVP_RAND *EVP_RAND_fetch(OPENSSL_CTX *libctx, const char *algorithm,
|
||||
const char *properties);
|
||||
int EVP_RAND_up_ref(EVP_RAND *rand);
|
||||
void EVP_RAND_free(EVP_RAND *rand);
|
||||
EVP_RAND_CTX *EVP_RAND_CTX_new(EVP_RAND *rand, EVP_RAND_CTX *parent);
|
||||
void EVP_RAND_CTX_free(EVP_RAND_CTX *ctx);
|
||||
EVP_RAND *EVP_RAND_CTX_rand(EVP_RAND_CTX *ctx);
|
||||
int EVP_RAND_get_params(EVP_RAND *rand, OSSL_PARAM params[]);
|
||||
int EVP_RAND_get_ctx_params(EVP_RAND_CTX *ctx, OSSL_PARAM params[]);
|
||||
int EVP_RAND_set_ctx_params(EVP_RAND_CTX *ctx, const OSSL_PARAM params[]);
|
||||
const OSSL_PARAM *EVP_RAND_gettable_params(const EVP_RAND *rand);
|
||||
const OSSL_PARAM *EVP_RAND_gettable_ctx_params(const EVP_RAND *rand);
|
||||
const OSSL_PARAM *EVP_RAND_settable_ctx_params(const EVP_RAND *rand);
|
||||
int EVP_RAND_number(const EVP_RAND *rand);
|
||||
const char *EVP_RAND_name(const EVP_RAND *rand);
|
||||
int EVP_RAND_is_a(const EVP_RAND *rand, const char *name);
|
||||
const OSSL_PROVIDER *EVP_RAND_provider(const EVP_RAND *rand);
|
||||
void EVP_RAND_do_all_provided(OPENSSL_CTX *libctx,
|
||||
void (*fn)(EVP_RAND *rand, void *arg),
|
||||
void *arg);
|
||||
void EVP_RAND_names_do_all(const EVP_RAND *rand,
|
||||
void (*fn)(const char *name, void *data),
|
||||
void *data);
|
||||
|
||||
int EVP_RAND_instantiate(EVP_RAND_CTX *ctx, unsigned int strength,
|
||||
int prediction_resistance,
|
||||
const unsigned char *pstr, size_t pstr_len);
|
||||
int EVP_RAND_uninstantiate(EVP_RAND_CTX *ctx);
|
||||
int EVP_RAND_generate(EVP_RAND_CTX *ctx, unsigned char *out, size_t outlen,
|
||||
unsigned int strength, int prediction_resistance,
|
||||
const unsigned char *addin, size_t addin_len);
|
||||
int EVP_RAND_reseed(EVP_RAND_CTX *ctx, int prediction_resistance,
|
||||
const unsigned char *ent, size_t ent_len,
|
||||
const unsigned char *addin, size_t addin_len);
|
||||
int EVP_RAND_nonce(EVP_RAND_CTX *ctx, unsigned char *out, size_t outlen);
|
||||
int EVP_RAND_enable_locking(EVP_RAND_CTX *ctx);
|
||||
int EVP_RAND_set_callbacks(EVP_RAND_CTX *ctx, OSSL_CALLBACK *get_entropy,
|
||||
OSSL_CALLBACK *cleanup_entropy,
|
||||
OSSL_CALLBACK *get_nonce,
|
||||
OSSL_CALLBACK *cleanup_nonce, void *arg);
|
||||
int EVP_RAND_verify_zeroization(EVP_RAND_CTX *ctx);
|
||||
unsigned int EVP_RAND_strength(EVP_RAND_CTX *ctx);
|
||||
int EVP_RAND_state(EVP_RAND_CTX *ctx);
|
||||
|
||||
#define EVP_RAND_STATE_UNINITIALISED 0
|
||||
#define EVP_RAND_STATE_READY 1
|
||||
#define EVP_RAND_STATE_ERROR 2
|
||||
|
||||
=head1 DESCRIPTION
|
||||
|
||||
The EVP RAND routines are a high level interface to random number generators
|
||||
both deterministic and not.
|
||||
If you just want to generate random bytes then you don't need to use
|
||||
these functions: just call RAND_bytes() or RAND_priv_bytes().
|
||||
If you want to do more, these calls should be used instead of the older
|
||||
RAND and RAND_DRBG functions.
|
||||
|
||||
After creating a B<EVP_RAND_CTX> for the required algorithm using
|
||||
EVP_RAND_CTX_new(), inputs to the algorithm are supplied
|
||||
using calls to EVP_RAND_set_ctx_params() before
|
||||
calling EVP_RAND_instantiate() and then EVP_RAND_generate() to produce
|
||||
cryptographically secure random bytes.
|
||||
|
||||
=head2 Types
|
||||
|
||||
B<EVP_RAND> is a type that holds the implementation of a RAND.
|
||||
|
||||
B<EVP_RAND_CTX> is a context type that holds the algorithm inputs.
|
||||
|
||||
=head2 Algorithm implementation fetching
|
||||
|
||||
EVP_RAND_fetch() fetches an implementation of a RAND I<algorithm>, given
|
||||
a library context I<libctx> and a set of I<properties>.
|
||||
See L<provider(7)/Fetching algorithms> for further information.
|
||||
|
||||
The returned value must eventually be freed with
|
||||
L<EVP_RAND_free(3)>.
|
||||
|
||||
EVP_RAND_up_ref() increments the reference count of an already fetched
|
||||
RAND.
|
||||
|
||||
EVP_RAND_free() frees a fetched algorithm.
|
||||
NULL is a valid parameter, for which this function is a no-op.
|
||||
|
||||
=head2 Context manipulation functions
|
||||
|
||||
EVP_RAND_CTX_new() creates a new context for the RAND implementation I<rand>.
|
||||
If not NULL, I<parent> specifies the seed source for this implementation.
|
||||
Not all random number generators need to have a seed source specified.
|
||||
If a parent is required, a NULL I<parent> will utilise the operating
|
||||
system entropy sources.
|
||||
It is recommended to minimise the number of random number generators that
|
||||
rely on the operating system for their randomness because this is often scarce.
|
||||
|
||||
EVP_RAND_CTX_free() frees up the context I<ctx>. If I<ctx> is NULL, nothing
|
||||
is done.
|
||||
|
||||
EVP_RAND_CTX_rand() returns the B<EVP_RAND> associated with the context
|
||||
I<ctx>.
|
||||
|
||||
=head2 Random Number Generator Functions
|
||||
|
||||
EVP_RAND_instantiate() instantiates the RAND I<ctx> with a minimum security
|
||||
strength of <strength> and personalisation string I<pstr> of length <pstr_len>.
|
||||
If I<prediction_resistance> is specified, fresh entropy from a live source
|
||||
will be sought. This call operates as per NIST SP 800-90A and SP 800-90C.
|
||||
|
||||
EVP_RAND_uninstantiate() uninstantiates the RAND I<ctx> as per
|
||||
NIST SP 800-90A and SP 800-90C. Subsequent to this call, the RAND cannot
|
||||
be used to generate bytes. It can only be freed or instantiated again.
|
||||
|
||||
EVP_RAND_generate() produces random bytes from the RAND I<ctx> with the
|
||||
additional input I<addin> of length I<addin_len>. The bytes
|
||||
produced will meet the security I<strength>.
|
||||
If I<prediction_resistance> is specified, fresh entropy from a live source
|
||||
will be sought. This call operates as per NIST SP 800-90A and SP 800-90C.
|
||||
|
||||
EVP_RAND_reseed() reseeds the RAND with new entropy.
|
||||
Entropy I<ent> of length I<ent_len> bytes can be supplied as can additional
|
||||
input I<addin> of length I<addin_len> bytes. In the FIPS provider, both are
|
||||
treated as additional input as per NIST SP-800-90Ar1, Sections 9.1 and 9.2.
|
||||
Additional seed material is also drawn from the RAND's parent or the
|
||||
operating system. If I<prediction_resistance> is specified, fresh entropy
|
||||
from a live source will be sought. This call operates as per NIST SP 800-90A
|
||||
and SP 800-90C.
|
||||
|
||||
EVP_RAND_nonce() creates a nonce in I<out> of maximum length I<outlen>
|
||||
bytes from the RAND I<ctx>. The function returns the length of the generated
|
||||
nonce. If I<out> is NULL, the length is still returned but no generation
|
||||
takes place. This allows a caller to dynamically allocate a buffer of the
|
||||
appropriate size.
|
||||
|
||||
EVP_RAND_enable_locking() enables locking for the RAND I<ctx> and all of
|
||||
its parents. After this I<ctx> will operate in a thread safe manner, albeit
|
||||
more slowly.
|
||||
|
||||
EVP_RAND_set_callbacks() sets callbacks on the RAND I<ctx> to accept
|
||||
external entropy and nonce input. The callback I<get_entropy> fills a buffer
|
||||
with new randomness and the callback I<cleanup_entropy> clears and frees the
|
||||
buffer. Likewise for I<get_nonce> and I<cleanup_nonce>. In all cases the
|
||||
callbacks are passed I<arg> in addition to an OSSL_PARAM array.
|
||||
|
||||
EVP_RAND_get_params() retrieves details about the implementation
|
||||
I<rand>.
|
||||
The set of parameters given with I<params> determine exactly what
|
||||
parameters should be retrieved.
|
||||
Note that a parameter that is unknown in the underlying context is
|
||||
simply ignored.
|
||||
|
||||
EVP_RAND_get_ctx_params() retrieves chosen parameters, given the
|
||||
context I<ctx> and its underlying context.
|
||||
The set of parameters given with I<params> determine exactly what
|
||||
parameters should be retrieved.
|
||||
Note that a parameter that is unknown in the underlying context is
|
||||
simply ignored.
|
||||
|
||||
EVP_RAND_set_ctx_params() passes chosen parameters to the underlying
|
||||
context, given a context I<ctx>.
|
||||
The set of parameters given with I<params> determine exactly what
|
||||
parameters are passed down.
|
||||
Note that a parameter that is unknown in the underlying context is
|
||||
simply ignored.
|
||||
Also, what happens when a needed parameter isn't passed down is
|
||||
defined by the implementation.
|
||||
|
||||
EVP_RAND_gettable_params(), EVP_RAND_gettable_ctx_params() and
|
||||
EVP_RAND_settable_ctx_params() get a constant B<OSSL_PARAM> array that
|
||||
describes the retrievable and settable parameters, i.e. parameters that
|
||||
can be used with EVP_RAND_get_params(), EVP_RAND_get_ctx_params()
|
||||
and EVP_RAND_set_ctx_params(), respectively.
|
||||
See L<OSSL_PARAM(3)> for the use of B<OSSL_PARAM> as parameter descriptor.
|
||||
|
||||
=head2 Information functions
|
||||
|
||||
EVP_RAND_strength() returns the security strength of the RAND I<ctx>.
|
||||
|
||||
EVP_RAND_state() returns the current state of the RAND I<ctx>.
|
||||
States defined by the OpenSSL DRBGs are:
|
||||
|
||||
=over 4
|
||||
|
||||
=item *
|
||||
|
||||
EVP_RAND_STATE_UNINITIALISED: this DRBG is currently uninitalised.
|
||||
The instantiate call will change this to the ready state.
|
||||
|
||||
=item *
|
||||
|
||||
EVP_RAND_STATE_READY: this DRBG is currently ready to generate output.
|
||||
|
||||
=item *
|
||||
|
||||
EVP_RAND_STATE_ERROR: this DRBG is in an error state.
|
||||
|
||||
=back
|
||||
|
||||
EVP_RAND_is_a() returns 1 if I<rand> is an implementation of an
|
||||
algorithm that's identifiable with I<name>, otherwise 0.
|
||||
|
||||
EVP_RAND_provider() returns the provider that holds the implementation
|
||||
of the given I<rand>.
|
||||
|
||||
EVP_RAND_do_all_provided() traverses all RAND implemented by all activated
|
||||
providers in the given library context I<libctx>, and for each of the
|
||||
implementations, calls the given function I<fn> with the implementation method
|
||||
and the given I<arg> as argument.
|
||||
|
||||
EVP_RAND_number() returns the internal dynamic number assigned to
|
||||
I<rand>.
|
||||
|
||||
EVP_RAND_name() returns the canonical name of I<rand>.
|
||||
|
||||
EVP_RAND_names_do_all() traverses all names for I<rand>, and calls
|
||||
I<fn> with each name and I<data>.
|
||||
|
||||
EVP_RAND_verify_zeroization() confirms if the internal DRBG state is
|
||||
currently zeroed. This is used by the FIPS provider to support the mandatory
|
||||
self tests.
|
||||
|
||||
=head1 PARAMETERS
|
||||
|
||||
The standard parameter names are:
|
||||
|
||||
=over 4
|
||||
|
||||
=item "state" (B<OSSL_RAND_PARAM_STATE>) <integer>
|
||||
|
||||
Returns the state of the random number generator.
|
||||
|
||||
=item "strength" (B<OSSL_RAND_PARAM_STRENGTH>) <unsigned integer>
|
||||
|
||||
Returns the bit strength of the random number generator.
|
||||
|
||||
=back
|
||||
|
||||
For rands that are also deterministic random bit generators (DRBGs), these
|
||||
additional parameters are recognised. Not all
|
||||
parameters are relevant to, or are understood by all DRBG rands:
|
||||
|
||||
=over 4
|
||||
|
||||
=item "reseed_requests" (B<OSSL_DRBG_PARAM_RESEED_REQUESTS>) <unsigned integer>
|
||||
|
||||
Reads or set the number of generate requests before reseeding the
|
||||
associated RAND ctx.
|
||||
|
||||
=item "reseed_time_interval" (B<OSSL_DRBG_PARAM_RESEED_TIME_INTERVAL>) <integer>
|
||||
|
||||
Reads or set the number of elapsed seconds before reseeding the
|
||||
associated RAND ctx.
|
||||
|
||||
=item "max_request" (B<OSSL_DRBG_PARAM_RESEED_REQUESTS>) <unsigned integer>
|
||||
|
||||
Specifies the maximum number of bytes that can be generated in a single
|
||||
call to OP_rand_generate.
|
||||
|
||||
=item "min_entropylen" (B<OSSL_DRBG_PARAM_MIN_ENTROPYLEN>) <unsigned integer>
|
||||
|
||||
=item "max_entropylen" (B<OSSL_DRBG_PARAM_MAX_ENTROPYLEN>) <unsigned integer>
|
||||
|
||||
Specify the minimum and maximum number of bytes of random material that
|
||||
can be used to seed the DRBG.
|
||||
|
||||
=item "min_noncelen" (B<OSSL_DRBG_PARAM_MIN_NONCELEN>) <unsigned integer>
|
||||
|
||||
=item "max_noncelen" (B<OSSL_DRBG_PARAM_MAX_NONCELEN>) <unsigned integer>
|
||||
|
||||
Specify the minimum and maximum number of bytes of nonce that can be used to
|
||||
seed the DRBG.
|
||||
|
||||
=item "max_perslen" (B<OSSL_DRBG_PARAM_MAX_PERSLEN>) <unsigned integer>
|
||||
|
||||
=item "max_adinlen" (B<OSSL_DRBG_PARAM_MAX_ADINLEN>) <unsigned integer>
|
||||
|
||||
Specify the minimum and maximum number of bytes of personalisation string
|
||||
that can be used with the DRBG.
|
||||
|
||||
=item "reseed_counter" (B<OSSL_DRBG_PARAM_RESEED_CTR>) <unsigned integer>
|
||||
|
||||
Specifies the number of times the DRBG has been seeded or reseeded.
|
||||
|
||||
=item "properties" (B<OSSL_RAND_PARAM_PROPERTIES>) <UTF8 string>
|
||||
|
||||
=item "mac" (B<OSSL_RAND_PARAM_MAC>) <UTF8 string>
|
||||
|
||||
=item "digest" (B<OSSL_RAND_PARAM_DIGEST>) <UTF8 string>
|
||||
|
||||
=item "cipher" (B<OSSL_RAND_PARAM_CIPHER>) <UTF8 string>
|
||||
|
||||
For RAND implementations that use an underlying computation MAC, digest or
|
||||
cipher, these parameters set what the algorithm should be.
|
||||
|
||||
The value is always the name of the intended algorithm,
|
||||
or the properties in the case of B<OSSL_RAND_PARAM_PROPERTIES>.
|
||||
|
||||
=back
|
||||
|
||||
=head1 RETURN VALUES
|
||||
|
||||
EVP_RAND_fetch() returns a pointer to a newly fetched B<EVP_RAND>, or
|
||||
NULL if allocation failed.
|
||||
|
||||
EVP_RAND_provider() returns a pointer to the provider for the RAND, or
|
||||
NULL on error.
|
||||
|
||||
EVP_RAND_CTX_rand() returns a pointer to the B<EVP_RAND> associated with the
|
||||
context.
|
||||
|
||||
EVP_RAND_name() returns the name of the random number generation algorithm.
|
||||
|
||||
EVP_RAND_number() returns the provider specific identification number
|
||||
for the specified algorithm.
|
||||
|
||||
EVP_RAND_up_ref() returns 1 on success, 0 on error.
|
||||
|
||||
EVP_RAND_CTX_new() returns either the newly allocated
|
||||
B<EVP_RAND_CTX> structure or NULL if an error occurred.
|
||||
|
||||
EVP_RAND_CTX_free() does not return a value.
|
||||
|
||||
EVP_RAND_nonce() returns the length of the nonce.
|
||||
|
||||
EVP_RAND_strength() returns the strenght of the random number generator in bits.
|
||||
|
||||
EVP_RAND_gettable_params(), EVP_RAND_gettable_ctx_params() and
|
||||
EVP_RAND_settable_ctx_params() return an array of OSSL_PARAMs.
|
||||
|
||||
EVP_RAND_verify_zeroization() returns 1 if the internal DRBG state is
|
||||
currently zeroed, and 0 if not.
|
||||
|
||||
The remaining functions return 1 for success and 0 or a negative value for
|
||||
failure.
|
||||
|
||||
=head1 SEE ALSO
|
||||
|
||||
L<RAND_bytes(3)>,
|
||||
L<EVP_RAND-CTR-DRBG(7)>,
|
||||
L<EVP_RAND-HASH-DRBG(7)>,
|
||||
L<EVP_RAND-HMAC-DRBG(7)>,
|
||||
L<EVP_RAND-TEST-RAND(7)>,
|
||||
L<provider-rand(7)>
|
||||
|
||||
=head1 HISTORY
|
||||
|
||||
This functionality was added to OpenSSL 3.0.
|
||||
|
||||
=head1 COPYRIGHT
|
||||
|
||||
Copyright 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
|
||||
|
|
@ -8,10 +8,10 @@ OSSL_PARAM_BLD_push_uint, OSSL_PARAM_BLD_push_long,
|
|||
OSSL_PARAM_BLD_push_ulong, OSSL_PARAM_BLD_push_int32,
|
||||
OSSL_PARAM_BLD_push_uint32, OSSL_PARAM_BLD_push_int64,
|
||||
OSSL_PARAM_BLD_push_uint64, OSSL_PARAM_BLD_push_size_t,
|
||||
OSSL_PARAM_BLD_push_double, OSSL_PARAM_BLD_push_BN,
|
||||
OSSL_PARAM_BLD_push_BN_pad, OSSL_PARAM_BLD_push_utf8_string,
|
||||
OSSL_PARAM_BLD_push_utf8_ptr, OSSL_PARAM_BLD_push_octet_string,
|
||||
OSSL_PARAM_BLD_push_octet_ptr
|
||||
OSSL_PARAM_BLD_push_time_t, OSSL_PARAM_BLD_push_double,
|
||||
OSSL_PARAM_BLD_push_BN, OSSL_PARAM_BLD_push_BN_pad,
|
||||
OSSL_PARAM_BLD_push_utf8_string, OSSL_PARAM_BLD_push_utf8_ptr,
|
||||
OSSL_PARAM_BLD_push_octet_string, OSSL_PARAM_BLD_push_octet_ptr
|
||||
- functions to assist in the creation of OSSL_PARAM arrays
|
||||
|
||||
=head1 SYNOPSIS
|
||||
|
|
|
|||
|
|
@ -3,31 +3,33 @@
|
|||
=head1 NAME
|
||||
|
||||
OSSL_PARAM_double, OSSL_PARAM_int, OSSL_PARAM_int32, OSSL_PARAM_int64,
|
||||
OSSL_PARAM_long, OSSL_PARAM_size_t, OSSL_PARAM_time_t, OSSL_PARAM_uint, OSSL_PARAM_uint32,
|
||||
OSSL_PARAM_uint64, OSSL_PARAM_ulong, OSSL_PARAM_BN, OSSL_PARAM_utf8_string,
|
||||
OSSL_PARAM_octet_string, OSSL_PARAM_utf8_ptr, OSSL_PARAM_octet_ptr,
|
||||
OSSL_PARAM_long, OSSL_PARAM_size_t, OSSL_PARAM_time_t, OSSL_PARAM_uint,
|
||||
OSSL_PARAM_uint32, OSSL_PARAM_uint64, OSSL_PARAM_ulong, OSSL_PARAM_BN,
|
||||
OSSL_PARAM_utf8_string, OSSL_PARAM_octet_string, OSSL_PARAM_utf8_ptr,
|
||||
OSSL_PARAM_octet_ptr,
|
||||
OSSL_PARAM_END,
|
||||
OSSL_PARAM_construct_double, OSSL_PARAM_construct_int,
|
||||
OSSL_PARAM_construct_int32, OSSL_PARAM_construct_int64,
|
||||
OSSL_PARAM_construct_long, OSSL_PARAM_construct_size_t, OSSL_PARAM_construct_time_t,
|
||||
OSSL_PARAM_construct_uint, OSSL_PARAM_construct_uint32,
|
||||
OSSL_PARAM_construct_uint64, OSSL_PARAM_construct_ulong,
|
||||
OSSL_PARAM_construct_BN, OSSL_PARAM_construct_utf8_string,
|
||||
OSSL_PARAM_construct_utf8_ptr, OSSL_PARAM_construct_octet_string,
|
||||
OSSL_PARAM_construct_octet_ptr, OSSL_PARAM_construct_end,
|
||||
OSSL_PARAM_construct_long, OSSL_PARAM_construct_size_t,
|
||||
OSSL_PARAM_construct_time_t, OSSL_PARAM_construct_uint,
|
||||
OSSL_PARAM_construct_uint32, OSSL_PARAM_construct_uint64,
|
||||
OSSL_PARAM_construct_ulong, OSSL_PARAM_construct_BN,
|
||||
OSSL_PARAM_construct_utf8_string, OSSL_PARAM_construct_utf8_ptr,
|
||||
OSSL_PARAM_construct_octet_string, OSSL_PARAM_construct_octet_ptr,
|
||||
OSSL_PARAM_construct_end,
|
||||
OSSL_PARAM_locate, OSSL_PARAM_locate_const,
|
||||
OSSL_PARAM_get_double, OSSL_PARAM_get_int, OSSL_PARAM_get_int32,
|
||||
OSSL_PARAM_get_int64, OSSL_PARAM_get_long, OSSL_PARAM_get_size_t, OSSL_PARAM_get_time_t,
|
||||
OSSL_PARAM_get_uint, OSSL_PARAM_get_uint32, OSSL_PARAM_get_uint64,
|
||||
OSSL_PARAM_get_ulong, OSSL_PARAM_get_BN, OSSL_PARAM_get_utf8_string,
|
||||
OSSL_PARAM_get_octet_string, OSSL_PARAM_get_utf8_ptr,
|
||||
OSSL_PARAM_get_octet_ptr,
|
||||
OSSL_PARAM_get_int64, OSSL_PARAM_get_long, OSSL_PARAM_get_size_t,
|
||||
OSSL_PARAM_get_time_t, OSSL_PARAM_get_uint, OSSL_PARAM_get_uint32,
|
||||
OSSL_PARAM_get_uint64, OSSL_PARAM_get_ulong, OSSL_PARAM_get_BN,
|
||||
OSSL_PARAM_get_utf8_string, OSSL_PARAM_get_octet_string,
|
||||
OSSL_PARAM_get_utf8_ptr, OSSL_PARAM_get_octet_ptr,
|
||||
OSSL_PARAM_set_double, OSSL_PARAM_set_int, OSSL_PARAM_set_int32,
|
||||
OSSL_PARAM_set_int64, OSSL_PARAM_set_long, OSSL_PARAM_set_size_t, OSSL_PARAM_set_time_t,
|
||||
OSSL_PARAM_set_uint, OSSL_PARAM_set_uint32, OSSL_PARAM_set_uint64,
|
||||
OSSL_PARAM_set_ulong, OSSL_PARAM_set_BN, OSSL_PARAM_set_utf8_string,
|
||||
OSSL_PARAM_set_octet_string, OSSL_PARAM_set_utf8_ptr,
|
||||
OSSL_PARAM_set_octet_ptr,
|
||||
OSSL_PARAM_set_int64, OSSL_PARAM_set_long, OSSL_PARAM_set_size_t,
|
||||
OSSL_PARAM_set_time_t, OSSL_PARAM_set_uint, OSSL_PARAM_set_uint32,
|
||||
OSSL_PARAM_set_uint64, OSSL_PARAM_set_ulong, OSSL_PARAM_set_BN,
|
||||
OSSL_PARAM_set_utf8_string, OSSL_PARAM_set_octet_string,
|
||||
OSSL_PARAM_set_utf8_ptr, OSSL_PARAM_set_octet_ptr,
|
||||
OSSL_PARAM_UNMODIFIED, OSSL_PARAM_modified, OSSL_PARAM_set_all_unmodified
|
||||
- OSSL_PARAM helpers
|
||||
|
||||
|
|
|
|||
|
|
@ -4,13 +4,12 @@
|
|||
|
||||
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
|
||||
RAND_DRBG_free,
|
||||
RAND_DRBG_verify_zeroization
|
||||
- initialize and cleanup a RAND_DRBG instance
|
||||
|
||||
=head1 SYNOPSIS
|
||||
|
|
@ -26,15 +25,6 @@ RAND_DRBG_free
|
|||
unsigned int flags,
|
||||
RAND_DRBG *parent);
|
||||
|
||||
RAND_DRBG *RAND_DRBG_secure_new_ex(OPENSSL_CTX *ctx,
|
||||
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_defaults(int type, unsigned int flags);
|
||||
|
||||
int RAND_DRBG_instantiate(RAND_DRBG *drbg,
|
||||
|
|
@ -43,6 +33,7 @@ RAND_DRBG_free
|
|||
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
|
||||
|
|
@ -53,14 +44,11 @@ L<openssl_user_macros(7)>:
|
|||
|
||||
=head1 DESCRIPTION
|
||||
|
||||
RAND_DRBG_new_ex() and RAND_DRBG_secure_new_ex() create a new DRBG instance
|
||||
of the given B<type> for the given OPENSSL_CTX <ctx>.
|
||||
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() and RAND_DRBG_secure_new() are the same as RAND_DRBG_new_ex()
|
||||
and RAND_DRBG_secure_new_ex() except that the default OPENSSL_CTX is always
|
||||
used.
|
||||
As of OpenSSL 3.0, there is no different between the new and secure_new
|
||||
functions.
|
||||
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
|
||||
|
|
@ -114,7 +102,6 @@ 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
|
||||
|
|
@ -125,18 +112,23 @@ 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(), RAND_DRBG_new(), RAND_DRBG_secure_new_ex() and
|
||||
RAND_DRBG_secure_new() return a pointer to a DRBG instance allocated on the
|
||||
heap.
|
||||
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
|
||||
|
|
@ -155,15 +147,8 @@ To ensure that they are applied to the global and thread-local DRBG instances
|
|||
RAND_DRBG_set_defaults() before creating any thread and before calling any
|
||||
cryptographic routines that obtain random data directly or indirectly.
|
||||
|
||||
As of OpenSSL 3.0, RAND_DRBG_new() and RAND_DRBG_secure_new() are
|
||||
functionally identical. The DRBG is allocated on the normal heap and its
|
||||
sensitive state is allocated on the secure heap. Likewise for,
|
||||
RAND_DRBG_new_ex() and RAND_DRBG_secure_new_ex().
|
||||
|
||||
=head1 SEE ALSO
|
||||
|
||||
L<OPENSSL_zalloc(3)>,
|
||||
L<OPENSSL_secure_zalloc(3)>,
|
||||
L<RAND_DRBG_generate(3)>,
|
||||
L<RAND_DRBG(7)>
|
||||
|
||||
|
|
|
|||
|
|
@ -131,7 +131,7 @@ 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", i.e., contains 8 bits of entropy per byte. In a FIPS context,
|
||||
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>()
|
||||
|
|
|
|||
|
|
@ -69,7 +69,8 @@ chroot(2) jail without the associated device nodes being available. When
|
|||
the B<keep> argument is zero, this call disables the retention of file
|
||||
descriptors. Conversely, a nonzero argument enables the retention of
|
||||
file descriptors. This function is usually called during initialization
|
||||
and it takes effect immediately.
|
||||
and it takes effect immediately. This capability only applies to the default
|
||||
provider.
|
||||
|
||||
RAND_event() and RAND_screen() are equivalent to RAND_poll() and exist
|
||||
for compatibility reasons only. See HISTORY section below.
|
||||
|
|
|
|||
|
|
@ -0,0 +1,108 @@
|
|||
=pod
|
||||
|
||||
=head1 NAME
|
||||
|
||||
EVP_RAND-CTR-DRBG - The CTR DRBG EVP_RAND implementation
|
||||
|
||||
=head1 DESCRIPTION
|
||||
|
||||
Support for the counter deterministic random bit generator through the
|
||||
B<EVP_RAND> API.
|
||||
|
||||
=head2 Identity
|
||||
|
||||
"CTR-DRBG" is the name for this implementation; it can be used with the
|
||||
EVP_RAND_fetch() function.
|
||||
|
||||
=head2 Supported parameters
|
||||
|
||||
The supported parameters are:
|
||||
|
||||
=over 4
|
||||
|
||||
=item "state" (B<OSSL_RAND_PARAM_STATE>) <integer>
|
||||
|
||||
=item "strength" (B<OSSL_RAND_PARAM_STRENGTH>) <unsigned integer>
|
||||
|
||||
=item "reseed_requests" (B<OSSL_DRBG_PARAM_RESEED_REQUESTS>) <unsigned integer>
|
||||
|
||||
=item "reseed_time_interval" (B<OSSL_DRBG_PARAM_RESEED_TIME_INTERVAL>) <integer>
|
||||
|
||||
=item "max_request" (B<OSSL_DRBG_PARAM_MAX_REQUEST>) <unsigned integer>
|
||||
|
||||
=item "min_entropylen" (B<OSSL_DRBG_PARAM_MIN_ENTROPYLEN>) <unsigned integer>
|
||||
|
||||
=item "max_entropylen" (B<OSSL_DRBG_PARAM_MAX_ENTROPYLEN>) <unsigned integer>
|
||||
|
||||
=item "min_noncelen" (B<OSSL_DRBG_PARAM_MIN_NONCELEN>) <unsigned integer>
|
||||
|
||||
=item "max_noncelen" (B<OSSL_DRBG_PARAM_MAX_NONCELEN>) <unsigned integer>
|
||||
|
||||
=item "max_perslen" (B<OSSL_DRBG_PARAM_MAX_PERSLEN>) <unsigned integer>
|
||||
|
||||
=item "max_adinlen" (B<OSSL_DRBG_PARAM_MAX_ADINLEN>) <unsigned integer>
|
||||
|
||||
=item "reseed_counter" (B<OSSL_DRBG_PARAM_RESEED_CTR>) <unsigned integer>
|
||||
|
||||
=item "properties" (B<OSSL_DRBG_PARAM_PROPERTIES>) <UTF8 string>
|
||||
|
||||
=item "cipher" (B<OSSL_DRBG_PARAM_CIPHER>) <UTF8 string>
|
||||
|
||||
These parameters work as described in L<EVP_RAND(3)/PARAMETERS>.
|
||||
|
||||
=item "use_derivation_function" (B<OSSL_DRBG_PARAM_USE_DF>) <int>
|
||||
|
||||
This Boolean indicates if a derivation function should be used or not.
|
||||
A nonzero value (the default) uses the derivation function. A zero value
|
||||
does not. The FIPS provider always uses the derivation function and attempts
|
||||
to set this value result in an error.
|
||||
|
||||
=back
|
||||
|
||||
=head1 NOTES
|
||||
|
||||
A context for CTR DRBG can be obtained by calling:
|
||||
|
||||
EVP_RAND *rand = EVP_RAND_fetch(NULL, "CTR-DRBG", NULL);
|
||||
EVP_RAND_CTX *rctx = EVP_RAND_CTX_new(rand);
|
||||
|
||||
=head1 EXAMPLES
|
||||
|
||||
EVP_RAND *rand;
|
||||
EVP_RAND_CTX *rctx;
|
||||
unsigned char bytes[100];
|
||||
OSSL_PARAM params[2], *p = params;
|
||||
unsigned int strength = 128;
|
||||
|
||||
rand = EVP_RAND_fetch(NULL, "CTR-DRBG", NULL);
|
||||
rctx = EVP_RAND_CTX_new(rand, NULL);
|
||||
EVP_RAND_free(rand);
|
||||
|
||||
*p++ = OSSL_PARAM_construct_utf8_string(OSSL_DRBG_PARAM_CIPHER,
|
||||
SN_aes_256_ctr, 0);
|
||||
*p = OSSL_PARAM_construct_end();
|
||||
EVP_RAND_set_ctx_params(rctx, params);
|
||||
|
||||
EVP_RAND_generate(rctx, bytes, sizeof(bytes), strength, 0, NULL, 0);
|
||||
|
||||
EVP_RAND_CTX_free(rctx);
|
||||
|
||||
=head1 CONFORMING TO
|
||||
|
||||
NIST SP 800-90A and SP 800-90B
|
||||
|
||||
=head1 SEE ALSO
|
||||
|
||||
L<EVP_RAND(3)>,
|
||||
L<EVP_RAND(3)/PARAMETERS>
|
||||
|
||||
=head1 COPYRIGHT
|
||||
|
||||
Copyright 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
|
||||
|
|
@ -0,0 +1,100 @@
|
|||
=pod
|
||||
|
||||
=head1 NAME
|
||||
|
||||
EVP_RAND-HASH-DRBG - The HASH DRBG EVP_RAND implementation
|
||||
|
||||
=head1 DESCRIPTION
|
||||
|
||||
Support for the hash deterministic random bit generator through the
|
||||
B<EVP_RAND> API.
|
||||
|
||||
=head2 Identity
|
||||
|
||||
"HASH-DRBG" is the name for this implementation; it can be used with the
|
||||
EVP_RAND_fetch() function.
|
||||
|
||||
=head2 Supported parameters
|
||||
|
||||
The supported parameters are:
|
||||
|
||||
=over 4
|
||||
|
||||
=item "state" (B<OSSL_RAND_PARAM_STATE>) <integer>
|
||||
|
||||
=item "strength" (B<OSSL_RAND_PARAM_STRENGTH>) <unsigned integer>
|
||||
|
||||
=item "reseed_requests" (B<OSSL_DRBG_PARAM_RESEED_REQUESTS>) <unsigned integer>
|
||||
|
||||
=item "reseed_time_interval" (B<OSSL_DRBG_PARAM_RESEED_TIME_INTERVAL>) <integer>
|
||||
|
||||
=item "max_request" (B<OSSL_DRBG_PARAM_MAX_REQUEST>) <unsigned integer>
|
||||
|
||||
=item "min_entropylen" (B<OSSL_DRBG_PARAM_MIN_ENTROPYLEN>) <unsigned integer>
|
||||
|
||||
=item "max_entropylen" (B<OSSL_DRBG_PARAM_MAX_ENTROPYLEN>) <unsigned integer>
|
||||
|
||||
=item "min_noncelen" (B<OSSL_DRBG_PARAM_MIN_NONCELEN>) <unsigned integer>
|
||||
|
||||
=item "max_noncelen" (B<OSSL_DRBG_PARAM_MAX_NONCELEN>) <unsigned integer>
|
||||
|
||||
=item "max_perslen" (B<OSSL_DRBG_PARAM_MAX_PERSLEN>) <unsigned integer>
|
||||
|
||||
=item "max_adinlen" (B<OSSL_DRBG_PARAM_MAX_ADINLEN>) <unsigned integer>
|
||||
|
||||
=item "reseed_counter" (B<OSSL_DRBG_PARAM_RESEED_CTR>) <unsigned integer>
|
||||
|
||||
=item "properties" (B<OSSL_DRBG_PARAM_PROPERTIES>) <UTF8 string>
|
||||
|
||||
=item "digest" (B<OSSL_DRBG_PARAM_DIGEST>) <UTF8 string>
|
||||
|
||||
These parameters work as described in L<EVP_RAND(3)/PARAMETERS>.
|
||||
|
||||
=back
|
||||
|
||||
=head1 NOTES
|
||||
|
||||
A context for HASH DRBG can be obtained by calling:
|
||||
|
||||
EVP_RAND *rand = EVP_RAND_fetch(NULL, "HASH-DRBG", NULL);
|
||||
EVP_RAND_CTX *rctx = EVP_RAND_CTX_new(rand);
|
||||
|
||||
=head1 EXAMPLES
|
||||
|
||||
EVP_RAND *rand;
|
||||
EVP_RAND_CTX *rctx;
|
||||
unsigned char bytes[100];
|
||||
OSSL_PARAM params[2], *p = params;
|
||||
unsigned int strength = 128;
|
||||
|
||||
rand = EVP_RAND_fetch(NULL, "HASH-DRBG", NULL);
|
||||
rctx = EVP_RAND_CTX_new(rand, NULL);
|
||||
EVP_RAND_free(rand);
|
||||
|
||||
*p++ = OSSL_PARAM_construct_utf8_string(OSSL_DRBG_PARAM_DIGEST, SN_sha512, 0);
|
||||
*p = OSSL_PARAM_construct_end();
|
||||
EVP_RAND_set_ctx_params(rctx, params);
|
||||
|
||||
EVP_RAND_generate(rctx, bytes, sizeof(bytes), strength, 0, NULL, 0);
|
||||
|
||||
EVP_RAND_CTX_free(rctx);
|
||||
|
||||
=head1 CONFORMING TO
|
||||
|
||||
NIST SP 800-90A and SP 800-90B
|
||||
|
||||
=head1 SEE ALSO
|
||||
|
||||
L<EVP_RAND(3)>,
|
||||
L<EVP_RAND(3)/PARAMETERS>
|
||||
|
||||
=head1 COPYRIGHT
|
||||
|
||||
Copyright 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
|
||||
|
|
@ -0,0 +1,103 @@
|
|||
=pod
|
||||
|
||||
=head1 NAME
|
||||
|
||||
EVP_RAND-HMAC-DRBG - The HMAC DRBG EVP_RAND implementation
|
||||
|
||||
=head1 DESCRIPTION
|
||||
|
||||
Support for the HMAC deterministic random bit generator through the
|
||||
B<EVP_RAND> API.
|
||||
|
||||
=head2 Identity
|
||||
|
||||
"HMAC-DRBG" is the name for this implementation; it can be used with the
|
||||
EVP_RAND_fetch() function.
|
||||
|
||||
=head2 Supported parameters
|
||||
|
||||
The supported parameters are:
|
||||
|
||||
=over 4
|
||||
|
||||
=item "state" (B<OSSL_RAND_PARAM_STATE>) <integer>
|
||||
|
||||
=item "strength" (B<OSSL_RAND_PARAM_STRENGTH>) <unsigned integer>
|
||||
|
||||
=item "reseed_requests" (B<OSSL_DRBG_PARAM_RESEED_REQUESTS>) <unsigned integer>
|
||||
|
||||
=item "reseed_time_interval" (B<OSSL_DRBG_PARAM_RESEED_TIME_INTERVAL>) <integer>
|
||||
|
||||
=item "max_request" (B<OSSL_DRBG_PARAM_MAX_REQUEST>) <unsigned integer>
|
||||
|
||||
=item "min_entropylen" (B<OSSL_DRBG_PARAM_MIN_ENTROPYLEN>) <unsigned integer>
|
||||
|
||||
=item "max_entropylen" (B<OSSL_DRBG_PARAM_MAX_ENTROPYLEN>) <unsigned integer>
|
||||
|
||||
=item "min_noncelen" (B<OSSL_DRBG_PARAM_MIN_NONCELEN>) <unsigned integer>
|
||||
|
||||
=item "max_noncelen" (B<OSSL_DRBG_PARAM_MAX_NONCELEN>) <unsigned integer>
|
||||
|
||||
=item "max_perslen" (B<OSSL_DRBG_PARAM_MAX_PERSLEN>) <unsigned integer>
|
||||
|
||||
=item "max_adinlen" (B<OSSL_DRBG_PARAM_MAX_ADINLEN>) <unsigned integer>
|
||||
|
||||
=item "reseed_counter" (B<OSSL_DRBG_PARAM_RESEED_CTR>) <unsigned integer>
|
||||
|
||||
=item "properties" (B<OSSL_DRBG_PARAM_PROPERTIES>) <UTF8 string>
|
||||
|
||||
=item "mac" (B<OSSL_DRBG_PARAM_MAC>) <UTF8 string>
|
||||
|
||||
=item "digest" (B<OSSL_DRBG_PARAM_DIGEST>) <UTF8 string>
|
||||
|
||||
These parameters work as described in L<EVP_RAND(3)/PARAMETERS>.
|
||||
|
||||
=back
|
||||
|
||||
=head1 NOTES
|
||||
|
||||
A context for HMAC DRBG can be obtained by calling:
|
||||
|
||||
EVP_RAND *rand = EVP_RAND_fetch(NULL, "HMAC-DRBG", NULL);
|
||||
EVP_RAND_CTX *rctx = EVP_RAND_CTX_new(rand);
|
||||
|
||||
=head1 EXAMPLES
|
||||
|
||||
EVP_RAND *rand;
|
||||
EVP_RAND_CTX *rctx;
|
||||
unsigned char bytes[100];
|
||||
OSSL_PARAM params[3], *p = params;
|
||||
unsigned int strength = 128;
|
||||
|
||||
rand = EVP_RAND_fetch(NULL, "HMAC-DRBG", NULL);
|
||||
rctx = EVP_RAND_CTX_new(rand, NULL);
|
||||
EVP_RAND_free(rand);
|
||||
|
||||
*p++ = OSSL_PARAM_construct_utf8_string(OSSL_DRBG_PARAM_MAC, SN_hmac, 0);
|
||||
*p++ = OSSL_PARAM_construct_utf8_string(OSSL_DRBG_PARAM_DIGEST, SN_sha256, 0);
|
||||
*p = OSSL_PARAM_construct_end();
|
||||
EVP_RAND_set_ctx_params(rctx, params);
|
||||
|
||||
EVP_RAND_generate(rctx, bytes, sizeof(bytes), strength, 0, NULL, 0);
|
||||
|
||||
EVP_RAND_CTX_free(rctx);
|
||||
|
||||
=head1 CONFORMING TO
|
||||
|
||||
NIST SP 800-90A and SP 800-90B
|
||||
|
||||
=head1 SEE ALSO
|
||||
|
||||
L<EVP_RAND(3)>,
|
||||
L<EVP_RAND(3)/PARAMETERS>
|
||||
|
||||
=head1 COPYRIGHT
|
||||
|
||||
Copyright 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
|
||||
|
|
@ -0,0 +1,113 @@
|
|||
=pod
|
||||
|
||||
=head1 NAME
|
||||
|
||||
EVP_RAND-TEST-RAND - The test EVP_RAND implementation
|
||||
|
||||
=head1 DESCRIPTION
|
||||
|
||||
Support for a test generator through the B<EVP_RAND> API. This generator is
|
||||
for test purposes only, it does not generate random numbers.
|
||||
|
||||
=head2 Identity
|
||||
|
||||
"TEST-RAND" is the name for this implementation; it can be used with the
|
||||
EVP_RAND_fetch() function.
|
||||
|
||||
=head2 Supported parameters
|
||||
|
||||
The supported parameters are:
|
||||
|
||||
=over 4
|
||||
|
||||
=item "state" (B<OSSL_RAND_PARAM_STATE>) <integer>
|
||||
|
||||
These parameter works as described in L<EVP_RAND(3)/PARAMETERS>.
|
||||
|
||||
=item "strength" (B<OSSL_RAND_PARAM_STRENGTH>) <unsigned integer>
|
||||
|
||||
=item "reseed_requests" (B<OSSL_DRBG_PARAM_RESEED_REQUESTS>) <unsigned integer>
|
||||
|
||||
=item "reseed_time_interval" (B<OSSL_DRBG_PARAM_RESEED_TIME_INTERVAL>) <integer>
|
||||
|
||||
=item "max_request" (B<OSSL_DRBG_PARAM_RESEED_REQUESTS>) <unsigned integer>
|
||||
|
||||
=item "min_entropylen" (B<OSSL_DRBG_PARAM_MIN_ENTROPYLEN>) <unsigned integer>
|
||||
|
||||
=item "max_entropylen" (B<OSSL_DRBG_PARAM_MAX_ENTROPYLEN>) <unsigned integer>
|
||||
|
||||
=item "min_noncelen" (B<OSSL_DRBG_PARAM_MIN_NONCELEN>) <unsigned integer>
|
||||
|
||||
=item "max_noncelen" (B<OSSL_DRBG_PARAM_MAX_NONCELEN>) <unsigned integer>
|
||||
|
||||
=item "max_perslen" (B<OSSL_DRBG_PARAM_MAX_PERSLEN>) <unsigned integer>
|
||||
|
||||
=item "max_adinlen" (B<OSSL_DRBG_PARAM_MAX_ADINLEN>) <unsigned integer>
|
||||
|
||||
=item "reseed_counter" (B<OSSL_DRBG_PARAM_RESEED_CTR>) <unsigned integer>
|
||||
|
||||
These parameters work as described in L<EVP_RAND(3)/PARAMETERS>, except that
|
||||
they can all be set as well as read.
|
||||
|
||||
=item "test_entropy" (B<OSSL_RAND_PARAM_TEST_ENTROPY>) <octet string>
|
||||
|
||||
Sets the bytes returned when the test generator is sent an entropy request.
|
||||
When entropy is requested, these bytes are treated as a cyclic buffer and they
|
||||
are repeated as required. The current position is remembered across generate
|
||||
calls.
|
||||
|
||||
=item "test_nonce" (B<OSSL_RAND_PARAM_TEST_NONCE>) <octet string>
|
||||
|
||||
Sets the bytes returned when the test generator is sent a nonce request.
|
||||
Each nonce request will return all of the bytes.
|
||||
|
||||
=back
|
||||
|
||||
=head1 NOTES
|
||||
|
||||
A context for a test generator can be obtained by calling:
|
||||
|
||||
EVP_RAND *rand = EVP_RAND_fetch(NULL, "TEST-RAND", NULL);
|
||||
EVP_RAND_CTX *rctx = EVP_RAND_CTX_new(rand);
|
||||
|
||||
=head1 EXAMPLES
|
||||
|
||||
EVP_RAND *rand;
|
||||
EVP_RAND_CTX *rctx;
|
||||
unsigned char bytes[100];
|
||||
OSSL_PARAM params[4], *p = params;
|
||||
unsigned char entropy[1000] = { ... };
|
||||
unsigned char nonce[20] = { ... };
|
||||
unsigned int strength = 48;
|
||||
|
||||
rand = EVP_RAND_fetch(NULL, "TEST-RAND", NULL);
|
||||
rctx = EVP_RAND_CTX_new(rand, NULL);
|
||||
EVP_RAND_free(rand);
|
||||
|
||||
*p++ = OSSL_PARAM_construct_uint(OSSL_RAND_PARAM_STRENGTH, &strength);
|
||||
*p++ = OSSL_PARAM_construct_octet_string(OSSL_RAND_PARAM_TEST_ENTROPY,
|
||||
entropy, sizeof(entropy));
|
||||
*p++ = OSSL_PARAM_construct_octet_string(OSSL_RAND_PARAM_TEST_NONCE,
|
||||
nonce, sizeof(nonce));
|
||||
*p = OSSL_PARAM_construct_end();
|
||||
EVP_RAND_set_ctx_params(rctx, params);
|
||||
|
||||
EVP_RAND_generate(rctx, bytes, sizeof(bytes), strength, 0, NULL, 0);
|
||||
|
||||
EVP_RAND_CTX_free(rctx);
|
||||
|
||||
=head1 SEE ALSO
|
||||
|
||||
L<EVP_RAND(3)>,
|
||||
L<EVP_RAND(3)/PARAMETERS>
|
||||
|
||||
=head1 COPYRIGHT
|
||||
|
||||
Copyright 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
|
||||
|
|
@ -0,0 +1,276 @@
|
|||
=pod
|
||||
|
||||
=head1 NAME
|
||||
|
||||
provider-rand - The random number generation library E<lt>-E<gt> provider
|
||||
functions
|
||||
|
||||
=head1 SYNOPSIS
|
||||
|
||||
=for openssl multiple includes
|
||||
|
||||
#include <openssl/core_numbers.h>
|
||||
#include <openssl/core_names.h>
|
||||
|
||||
/*
|
||||
* None of these are actual functions, but are displayed like this for
|
||||
* the function signatures for functions that are offered as function
|
||||
* pointers in OSSL_DISPATCH arrays.
|
||||
*/
|
||||
|
||||
/* Context management */
|
||||
void *OP_rand_newctx(void *provctx, void *parent,
|
||||
const OSSL_DISPATCH *parent_calls);
|
||||
void OP_rand_freectx(void *ctx);
|
||||
|
||||
/* Random number generator functions: NIST */
|
||||
int OP_rand_instantiate(void *ctx, unsigned int strength,
|
||||
int prediction_resistance,
|
||||
const unsigned char *pstr, size_t pstr_len);
|
||||
int OP_rand_uninstantiate(void *ctx);
|
||||
int OP_rand_generate(void *ctx, unsigned char *out, size_t outlen,
|
||||
unsigned int strength, int prediction_resistance,
|
||||
const unsigned char *addin, size_t addin_len);
|
||||
int OP_rand_reseed(void *ctx, int prediction_resistance,
|
||||
const unsigned char *ent, size_t ent_len,
|
||||
const unsigned char *addin, size_t addin_len);
|
||||
|
||||
/* Random number generator functions: additional */
|
||||
size_t OP_rand_nonce(void *ctx, unsigned char *out, size_t outlen,
|
||||
int strength, size_t min_noncelen, size_t max_noncelen);
|
||||
void OP_rand_set_callbacks(void *ctx, OSSL_CALLBACK *get_entropy,
|
||||
OSSL_CALLBACK *cleanup_entropy,
|
||||
OSSL_CALLBACK *get_nonce,
|
||||
OSSL_CALLBACK *cleanup_nonce, void *arg);
|
||||
int OP_rand_verify_zeroization(void *ctx);
|
||||
|
||||
/* Context Locking */
|
||||
int OP_rand_enable_locking(void *ctx);
|
||||
int OP_rand_lock(void *ctx);
|
||||
void OP_rand_unlock(void *ctx);
|
||||
|
||||
/* RAND parameter descriptors */
|
||||
const OSSL_PARAM *OP_rand_gettable_params(void);
|
||||
const OSSL_PARAM *OP_rand_gettable_ctx_params(void);
|
||||
const OSSL_PARAM *OP_rand_settable_ctx_params(void);
|
||||
|
||||
/* RAND parameters */
|
||||
int OP_rand_get_params(OSSL_PARAM params[]);
|
||||
int OP_rand_get_ctx_params(void *ctx, OSSL_PARAM params[]);
|
||||
int OP_rand_set_ctx_params(void *ctx, const OSSL_PARAM params[]);
|
||||
|
||||
=head1 DESCRIPTION
|
||||
|
||||
This documentation is primarily aimed at provider authors. See L<provider(7)>
|
||||
for further information.
|
||||
|
||||
The RAND operation enables providers to implement random number generation
|
||||
algorithms and random number sources and make
|
||||
them available to applications via the API function L<EVP_RAND(3)>.
|
||||
|
||||
=head2 Context Management Functions
|
||||
|
||||
OP_rand_newctx() should create and return a pointer to a provider side
|
||||
structure for holding context information during a rand operation.
|
||||
A pointer to this context will be passed back in a number of the other rand
|
||||
operation function calls.
|
||||
The parameter I<provctx> is the provider context generated during provider
|
||||
initialisation (see L<provider(7)>).
|
||||
The parameter I<parent> specifies another rand instance to be used for
|
||||
seeding purposes. If NULL and the specific instance supports it, the
|
||||
operating system will be used for seeding.
|
||||
The parameter I<parent_calls> points to the dispatch table for I<parent>.
|
||||
Thus, the parent need not be from the same provider as the new instance.
|
||||
|
||||
OP_rand_freectx() is passed a pointer to the provider side rand context in
|
||||
the I<mctx> parameter.
|
||||
If it receives NULL as I<ctx> value, it should not do anything other than
|
||||
return.
|
||||
This function should free any resources associated with that context.
|
||||
|
||||
=head2 Random Number Generator Functions: NIST
|
||||
|
||||
These functions correspond to those defined in NIST SP 800-90A and SP 800-90C.
|
||||
|
||||
OP_rand_instantiate() is used to instantiate the DRBG I<ctx> at a requested
|
||||
security I<strength>. In addition, I<prediction_resistance> can be requested.
|
||||
Additional input I<addin> of length I<addin_len> bytes can optionally
|
||||
be provided.
|
||||
|
||||
OP_rand_uninstantiate() is used to uninstantiate the DRBG I<ctx>. After being
|
||||
uninstantiated, a DRBG is unable to produce output until it is instantiated
|
||||
anew.
|
||||
|
||||
OP_rand_generate() is used to generate random bytes from the DRBG I<ctx>.
|
||||
It will generate I<outlen> bytes placing them into the buffer pointed to by
|
||||
I<out>. The generated bytes will meet the specified security I<strength> and,
|
||||
if I<prediction_resistance> is true, the bytes will be produced after reseeding
|
||||
from a live entropy source. Additional input I<addin> of length I<addin_len>
|
||||
bytes can optionally be provided.
|
||||
|
||||
=head2 Random Number Generator Functions: Additional
|
||||
|
||||
OP_rand_nonce() is used to generate a nonce of the given I<strength> with a
|
||||
length from I<min_noncelen> to I<max_noncelen>. If the output buffer I<out> is
|
||||
NULL, the length of the nonce should be returned.
|
||||
|
||||
OP_rand_set_callbacks() is used to supply custom entropy and nonce callbacks.
|
||||
Instead of gathering seed material from its usual sources, the DRBG I<ctx>
|
||||
should call these functions.
|
||||
The I<get_entropy> and I<cleanup_entropy> callbacks obtain and release bytes
|
||||
of entropy.
|
||||
The I<get_nonce> and I<cleanup_nonce> functions obtain and release nonce bytes.
|
||||
In all cases, the additional argument I<arg> is passed to the callbacks.
|
||||
|
||||
OP_rand_verify_zeroization() is used to determine if the internal state of the
|
||||
DRBG is zero. This capability is mandated by NIST as part of the self
|
||||
tests, it is unlikely to be useful in other circumstances.
|
||||
|
||||
=head2 Context Locking
|
||||
|
||||
When DRBGs are used by multiple threads, there must be locking employed to
|
||||
ensure their proper operation. Because locking introduces an overhead, it
|
||||
is disabled by default.
|
||||
|
||||
OP_rand_enable_locking() allows locking to be turned on for a DRBG and all of
|
||||
its parent DRBGs. From this call onwards, the DRBG can be used in a thread
|
||||
safe manner.
|
||||
|
||||
OP_rand_lock() is used to lock a DRBG. Once locked, exclusive access
|
||||
is guaranteed.
|
||||
|
||||
OP_rand_unlock() is used to unlock a DRBG.
|
||||
|
||||
=head2 Rand Parameters
|
||||
|
||||
See L<OSSL_PARAM(3)> for further details on the parameters structure used by
|
||||
these functions.
|
||||
|
||||
OP_rand_get_params() gets details of parameter values associated with the
|
||||
provider algorithm and stores them in I<params>.
|
||||
|
||||
OP_rand_set_ctx_params() sets rand parameters associated with the given
|
||||
provider side rand context I<ctx> to I<params>.
|
||||
Any parameter settings are additional to any that were previously set.
|
||||
|
||||
OP_rand_get_ctx_params() gets details of currently set parameter values
|
||||
associated with the given provider side rand context I<ctx> and stores them
|
||||
in I<params>.
|
||||
|
||||
OP_rand_gettable_params(), OP_rand_gettable_ctx_params(), and
|
||||
OP_rand_settable_ctx_params() all return constant B<OSSL_PARAM> arrays
|
||||
as descriptors of the parameters that OP_rand_get_params(),
|
||||
OP_rand_get_ctx_params(), and OP_rand_set_ctx_params() can handle,
|
||||
respectively.
|
||||
|
||||
Parameters currently recognised by built-in rands are as follows. Not all
|
||||
parameters are relevant to, or are understood by all rands:
|
||||
|
||||
=over 4
|
||||
|
||||
=item "state" (B<OSSL_RAND_PARAM_STATE>) <integer>
|
||||
|
||||
Returns the state of the random number generator.
|
||||
|
||||
=item "strength" (B<OSSL_RAND_PARAM_STRENGTH>) <unsigned integer>
|
||||
|
||||
Returns the bit strength of the random number generator.
|
||||
|
||||
=back
|
||||
|
||||
For rands that are also deterministic random bit generators (DRBGs), these
|
||||
additional parameters are recognised. Not all
|
||||
parameters are relevant to, or are understood by all DRBG rands:
|
||||
|
||||
=over 4
|
||||
|
||||
=item "reseed_requests" (B<OSSL_DRBG_PARAM_RESEED_REQUESTS>) <unsigned integer>
|
||||
|
||||
Reads or set the number of generate requests before reseeding the
|
||||
associated RAND ctx.
|
||||
|
||||
=item "reseed_time_interval" (B<OSSL_DRBG_PARAM_RESEED_TIME_INTERVAL>) <integer>
|
||||
|
||||
Reads or set the number of elapsed seconds before reseeding the
|
||||
associated RAND ctx.
|
||||
|
||||
=item "max_request" (B<OSSL_DRBG_PARAM_RESEED_REQUESTS>) <unsigned integer>
|
||||
|
||||
Specifies the maximum number of bytes that can be generated in a single
|
||||
call to OP_rand_generate.
|
||||
|
||||
=item "min_entropylen" (B<OSSL_DRBG_PARAM_MIN_ENTROPYLEN>) <unsigned integer>
|
||||
|
||||
=item "max_entropylen" (B<OSSL_DRBG_PARAM_MAX_ENTROPYLEN>) <unsigned integer>
|
||||
|
||||
Specify the minimum and maximum number of bytes of random material that
|
||||
can be used to seed the DRBG.
|
||||
|
||||
=item "min_noncelen" (B<OSSL_DRBG_PARAM_MIN_NONCELEN>) <unsigned integer>
|
||||
|
||||
=item "max_noncelen" (B<OSSL_DRBG_PARAM_MAX_NONCELEN>) <unsigned integer>
|
||||
|
||||
Specify the minimum and maximum number of bytes of nonce that can be used to
|
||||
instantiate the DRBG.
|
||||
|
||||
=item "max_perslen" (B<OSSL_DRBG_PARAM_MAX_PERSLEN>) <unsigned integer>
|
||||
|
||||
=item "max_adinlen" (B<OSSL_DRBG_PARAM_MAX_ADINLEN>) <unsigned integer>
|
||||
|
||||
Specify the minimum and maximum number of bytes of personalisation string
|
||||
that can be used with the DRBG.
|
||||
|
||||
=item "reseed_counter" (B<OSSL_DRBG_PARAM_RESEED_CTR>) <unsigned integer>
|
||||
|
||||
Specifies the number of times the DRBG has been seeded or reseeded.
|
||||
|
||||
=item "digest" (B<OSSL_DRBG_PARAM_DIGEST>) <UTF8 string>
|
||||
|
||||
=item "cipher" (B<OSSL_DRBG_PARAM_CIPHER>) <UTF8 string>
|
||||
|
||||
=item "mac" (B<OSSL_DRBG_PARAM_MAC>) <UTF8 string>
|
||||
|
||||
Sets the name of the underlying cipher, digest or MAC to be used.
|
||||
It must name a suitable algorithm for the DRBG that's being used.
|
||||
|
||||
=item "properties" (B<OSSL_DRBG_PARAM_PROPERTIES>) <UTF8 string>
|
||||
|
||||
Sets the properties to be queried when trying to fetch an underlying algorithm.
|
||||
This must be given together with the algorithm naming parameter to be
|
||||
considered valid.
|
||||
|
||||
=back
|
||||
|
||||
=head1 RETURN VALUES
|
||||
|
||||
OP_rand_newctx() should return the newly created
|
||||
provider side rand context, or NULL on failure.
|
||||
|
||||
OP_rand_gettable_params(), OP_rand_gettable_ctx_params() and
|
||||
OP_rand_settable_ctx_params() should return a constant B<OSSL_PARAM>
|
||||
array, or NULL if none is offered.
|
||||
|
||||
OP_rand_nonce() returns the size of the generated nonce, or 0 on error.
|
||||
|
||||
All of the remaining functions should return 1 for success or 0 on error.
|
||||
|
||||
=head1 SEE ALSO
|
||||
|
||||
L<provider(7)>,
|
||||
L<RAND(7)>,
|
||||
L<RAND_DRBG(7)>
|
||||
|
||||
=head1 HISTORY
|
||||
|
||||
The provider RAND interface was introduced in OpenSSL 3.0.
|
||||
|
||||
=head1 COPYRIGHT
|
||||
|
||||
Copyright 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
|
||||
|
|
@ -35,6 +35,8 @@ EVP_MAC_CTX datatype
|
|||
EVP_PKEY_gen_cb datatype
|
||||
EVP_PKEY_METHOD datatype
|
||||
EVP_PKEY_ASN1_METHOD datatype
|
||||
EVP_RAND datatype
|
||||
EVP_RAND_CTX datatype
|
||||
GEN_SESSION_CB datatype
|
||||
OPENSSL_Applink external
|
||||
OPENSSL_CTX datatype
|
||||
|
|
@ -300,6 +302,9 @@ EVP_PKEY_assign_EC_KEY define
|
|||
EVP_PKEY_assign_POLY1305 define
|
||||
EVP_PKEY_assign_RSA define
|
||||
EVP_PKEY_assign_SIPHASH define
|
||||
EVP_RAND_STATE_ERROR define
|
||||
EVP_RAND_STATE_READY define
|
||||
EVP_RAND_STATE_UNINITIALISED define
|
||||
EVP_SealUpdate define
|
||||
EVP_SignInit define
|
||||
EVP_SignInit_ex define
|
||||
|
|
|
|||
Loading…
Reference in New Issue