Browse Source

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)
master
Pauli 2 years ago
parent
commit
dc4e74ef6c
15 changed files with 1174 additions and 56 deletions
  1. +1
    -1
      crypto/rand/build.info
  2. +35
    -0
      crypto/rand/rand_deprecated.c
  3. +11
    -0
      doc/man1/openssl-list.pod.in
  4. +379
    -0
      doc/man3/EVP_RAND.pod
  5. +4
    -4
      doc/man3/OSSL_PARAM_BLD.pod
  6. +21
    -19
      doc/man3/OSSL_PARAM_int.pod
  7. +15
    -30
      doc/man3/RAND_DRBG_new.pod
  8. +1
    -1
      doc/man3/RAND_DRBG_set_callbacks.pod
  9. +2
    -1
      doc/man3/RAND_add.pod
  10. +108
    -0
      doc/man7/EVP_RAND-CTR-DRBG.pod
  11. +100
    -0
      doc/man7/EVP_RAND-HASH-DRBG.pod
  12. +103
    -0
      doc/man7/EVP_RAND-HMAC-DRBG.pod
  13. +113
    -0
      doc/man7/EVP_RAND-TEST-RAND.pod
  14. +276
    -0
      doc/man7/provider-rand.pod
  15. +5
    -0
      util/other.syms

+ 1
- 1
crypto/rand/build.info View File

@ -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


+ 35
- 0
crypto/rand/rand_deprecated.c View File

@ -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

+ 11
- 0
doc/man1/openssl-list.pod.in View File

@ -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


+ 379
- 0
doc/man3/EVP_RAND.pod View File

@ -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

+ 4
- 4
doc/man3/OSSL_PARAM_BLD.pod View File

@ -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


+ 21
- 19
doc/man3/OSSL_PARAM_int.pod View File

@ -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


+ 15
- 30
doc/man3/RAND_DRBG_new.pod View File

@ -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)>


+ 1
- 1
doc/man3/RAND_DRBG_set_callbacks.pod View File

@ -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>()


+ 2
- 1
doc/man3/RAND_add.pod View File

@ -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.


+ 108
- 0
doc/man7/EVP_RAND-CTR-DRBG.pod View File

@ -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

+ 100
- 0
doc/man7/EVP_RAND-HASH-DRBG.pod View File

@ -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

+ 103
- 0
doc/man7/EVP_RAND-HMAC-DRBG.pod View File

@ -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

+ 113
- 0
doc/man7/EVP_RAND-TEST-RAND.pod View File

@ -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

+ 276
- 0
doc/man7/provider-rand.pod View File

@ -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

+ 5
- 0
util/other.syms View File

@ -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…
Cancel
Save