diff options
author | Pauli <paul.dale@oracle.com> | 2020-05-25 14:45:49 +1000 |
---|---|---|
committer | Pauli <paul.dale@oracle.com> | 2020-06-24 20:07:46 +1000 |
commit | dc4e74ef6c10a13d8a8947c71e9ee70a0abe642e (patch) | |
tree | 71874ab26e07fa58dac4240ff772b9eb84fa9571 /doc | |
parent | 6154f9a7cad7805a551343ed2111231aa2e00681 (diff) |
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)
Diffstat (limited to 'doc')
-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 |
12 files changed, 1133 insertions, 55 deletions
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 |