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)
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
--- /dev/null
+/*
+ * 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
[B<-digest-algorithms>]
[B<-kdf-algorithms>]
[B<-mac-algorithms>]
+[B<-random-generators>]
[B<-cipher-commands>]
[B<-cipher-algorithms>]
[B<-public-key-algorithms>]
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
--- /dev/null
+=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
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
=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
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
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,
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
=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
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
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
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)>
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>()
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.
--- /dev/null
+=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
--- /dev/null
+=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
--- /dev/null
+=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
--- /dev/null
+=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
--- /dev/null
+=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
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
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
projects / openssl.git / commitdiff