diff options
author | Pauli <paul.dale@oracle.com> | 2020-05-25 06:45:49 +0200 |
---|---|---|
committer | Pauli <paul.dale@oracle.com> | 2020-06-24 12:07:46 +0200 |
commit | dc4e74ef6c10a13d8a8947c71e9ee70a0abe642e (patch) | |
tree | 71874ab26e07fa58dac4240ff772b9eb84fa9571 | |
parent | fips rand: DRBG KAT self test updates to provider model. (diff) | |
download | openssl-dc4e74ef6c10a13d8a8947c71e9ee70a0abe642e.tar.xz openssl-dc4e74ef6c10a13d8a8947c71e9ee70a0abe642e.zip |
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)
-rw-r--r-- | crypto/rand/build.info | 2 | ||||
-rw-r--r-- | crypto/rand/rand_deprecated.c | 35 | ||||
-rw-r--r-- | doc/man1/openssl-list.pod.in | 11 | ||||
-rw-r--r-- | doc/man3/EVP_RAND.pod | 379 | ||||
-rw-r--r-- | doc/man3/OSSL_PARAM_BLD.pod | 8 | ||||
-rw-r--r-- | doc/man3/OSSL_PARAM_int.pod | 40 | ||||
-rw-r--r-- | doc/man3/RAND_DRBG_new.pod | 45 | ||||
-rw-r--r-- | doc/man3/RAND_DRBG_set_callbacks.pod | 2 | ||||
-rw-r--r-- | doc/man3/RAND_add.pod | 3 | ||||
-rw-r--r-- | doc/man7/EVP_RAND-CTR-DRBG.pod | 108 | ||||
-rw-r--r-- | doc/man7/EVP_RAND-HASH-DRBG.pod | 100 | ||||
-rw-r--r-- | doc/man7/EVP_RAND-HMAC-DRBG.pod | 103 | ||||
-rw-r--r-- | doc/man7/EVP_RAND-TEST-RAND.pod | 113 | ||||
-rw-r--r-- | doc/man7/provider-rand.pod | 276 | ||||
-rw-r--r-- | util/other.syms | 5 |
15 files changed, 1174 insertions, 56 deletions
diff --git a/crypto/rand/build.info b/crypto/rand/build.info index b7a4d598f1..7776ca8820 100644 --- a/crypto/rand/build.info +++ b/crypto/rand/build.info @@ -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 diff --git a/crypto/rand/rand_deprecated.c b/crypto/rand/rand_deprecated.c new file mode 100644 index 0000000000..dd69f1beb7 --- /dev/null +++ b/crypto/rand/rand_deprecated.c @@ -0,0 +1,35 @@ +/* + * Copyright 1995-2020 The OpenSSL Project Authors. All Rights Reserved. + * + * Licensed under the Apache License 2.0 (the "License"). You may not use + * this file except in compliance with the License. You can obtain a copy + * in the file LICENSE in the source distribution or at + * https://www.openssl.org/source/license.html + */ + +#include <e_os.h> +#include <openssl/macros.h> +#include <openssl/rand.h> + +#if defined(OPENSSL_SYS_WINDOWS) || defined(OPENSSL_SYS_WIN32) +# include <windows.h> +# if OPENSSL_API_COMPAT < 0x10100000L + +# define DEPRECATED_RAND_FUNCTIONS_DEFINED + +int RAND_event(UINT iMsg, WPARAM wParam, LPARAM lParam) +{ + RAND_poll(); + return RAND_status(); +} + +void RAND_screen(void) +{ + RAND_poll(); +} +# endif +#endif + +#ifndef DEPRECATED_RAND_FUNCTIONS_DEFINED +NON_EMPTY_TRANSLATION_UNIT +#endif diff --git a/doc/man1/openssl-list.pod.in b/doc/man1/openssl-list.pod.in index d7e062bf01..1eb62d3feb 100644 --- a/doc/man1/openssl-list.pod.in +++ b/doc/man1/openssl-list.pod.in @@ -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 diff --git a/doc/man3/EVP_RAND.pod b/doc/man3/EVP_RAND.pod new file mode 100644 index 0000000000..c32217543e --- /dev/null +++ b/doc/man3/EVP_RAND.pod @@ -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 diff --git a/doc/man3/OSSL_PARAM_BLD.pod b/doc/man3/OSSL_PARAM_BLD.pod index ed82e32073..844b715820 100644 --- a/doc/man3/OSSL_PARAM_BLD.pod +++ b/doc/man3/OSSL_PARAM_BLD.pod @@ -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 diff --git a/doc/man3/OSSL_PARAM_int.pod b/doc/man3/OSSL_PARAM_int.pod index ca4e9d066e..7aa6b9377f 100644 --- a/doc/man3/OSSL_PARAM_int.pod +++ b/doc/man3/OSSL_PARAM_int.pod @@ -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 diff --git a/doc/man3/RAND_DRBG_new.pod b/doc/man3/RAND_DRBG_new.pod index cd770fd673..7d7cdbad44 100644 --- a/doc/man3/RAND_DRBG_new.pod +++ b/doc/man3/RAND_DRBG_new.pod @@ -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)> diff --git a/doc/man3/RAND_DRBG_set_callbacks.pod b/doc/man3/RAND_DRBG_set_callbacks.pod index 0ae3028a5a..543b3cc911 100644 --- a/doc/man3/RAND_DRBG_set_callbacks.pod +++ b/doc/man3/RAND_DRBG_set_callbacks.pod @@ -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>() diff --git a/doc/man3/RAND_add.pod b/doc/man3/RAND_add.pod index b4151164c2..7eafe7bb53 100644 --- a/doc/man3/RAND_add.pod +++ b/doc/man3/RAND_add.pod @@ -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. diff --git a/doc/man7/EVP_RAND-CTR-DRBG.pod b/doc/man7/EVP_RAND-CTR-DRBG.pod new file mode 100644 index 0000000000..e35703670f --- /dev/null +++ b/doc/man7/EVP_RAND-CTR-DRBG.pod @@ -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 diff --git a/doc/man7/EVP_RAND-HASH-DRBG.pod b/doc/man7/EVP_RAND-HASH-DRBG.pod new file mode 100644 index 0000000000..879384993e --- /dev/null +++ b/doc/man7/EVP_RAND-HASH-DRBG.pod @@ -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 diff --git a/doc/man7/EVP_RAND-HMAC-DRBG.pod b/doc/man7/EVP_RAND-HMAC-DRBG.pod new file mode 100644 index 0000000000..31b17a97ba --- /dev/null +++ b/doc/man7/EVP_RAND-HMAC-DRBG.pod @@ -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 diff --git a/doc/man7/EVP_RAND-TEST-RAND.pod b/doc/man7/EVP_RAND-TEST-RAND.pod new file mode 100644 index 0000000000..4736b5a976 --- /dev/null +++ b/doc/man7/EVP_RAND-TEST-RAND.pod @@ -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 diff --git a/doc/man7/provider-rand.pod b/doc/man7/provider-rand.pod new file mode 100644 index 0000000000..891b824561 --- /dev/null +++ b/doc/man7/provider-rand.pod @@ -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 diff --git a/util/other.syms b/util/other.syms index d993485931..ab60424a8f 100644 --- a/util/other.syms +++ b/util/other.syms @@ -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 |