diff options
author | Dr. Matthias St. Pierre <Matthias.St.Pierre@ncp-e.com> | 2018-02-27 19:02:24 +0100 |
---|---|---|
committer | Dr. Matthias St. Pierre <Matthias.St.Pierre@ncp-e.com> | 2018-03-30 00:10:38 +0200 |
commit | a73d990e2b6b1a406b1c85837a176bf7525d3914 (patch) | |
tree | 59aaa4b3929db741e928c44174a0d6c75727fc7f | |
parent | 3484236d8d7afedd3e5c7771bd49d3385340e3bf (diff) |
Add documentation for the RAND_DRBG API
The RAND_DRBG API was added in PR #5462 and modified by PR #5547.
This commit adds the corresponding documention.
Reviewed-by: Kurt Roeckx <kurt@roeckx.be>
Reviewed-by: Rich Salz <rsalz@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/5461)
-rw-r--r-- | CHANGES | 4 | ||||
-rw-r--r-- | INSTALL | 57 | ||||
-rw-r--r-- | crypto/rand/drbg_lib.c | 157 | ||||
-rw-r--r-- | doc/man3/CRYPTO_get_ex_new_index.pod | 20 | ||||
-rw-r--r-- | doc/man3/RAND_DRBG_generate.pod | 88 | ||||
-rw-r--r-- | doc/man3/RAND_DRBG_get0_master.pod | 80 | ||||
-rw-r--r-- | doc/man3/RAND_DRBG_new.pod | 127 | ||||
-rw-r--r-- | doc/man3/RAND_DRBG_reseed.pod | 111 | ||||
-rw-r--r-- | doc/man3/RAND_DRBG_set_callbacks.pod | 147 | ||||
-rw-r--r-- | doc/man3/RAND_DRBG_set_ex_data.pod | 68 | ||||
-rw-r--r-- | doc/man3/RAND_add.pod | 123 | ||||
-rw-r--r-- | doc/man3/RAND_bytes.pod | 12 | ||||
-rw-r--r-- | doc/man3/RAND_cleanup.pod | 4 | ||||
-rw-r--r-- | doc/man3/RAND_egd.pod | 4 | ||||
-rw-r--r-- | doc/man3/RAND_load_file.pod | 6 | ||||
-rw-r--r-- | doc/man3/RAND_set_rand_method.pod | 9 | ||||
-rw-r--r-- | doc/man7/RAND.pod | 78 | ||||
-rw-r--r-- | doc/man7/RAND_DRBG.pod | 300 | ||||
-rw-r--r-- | include/openssl/rand_drbg.h | 12 | ||||
-rw-r--r-- | util/private.num | 6 |
20 files changed, 1173 insertions, 240 deletions
@@ -9,6 +9,10 @@ Changes between 1.1.0g and 1.1.1 [xx XXX xxxx] + *) Added new public header file <openssl/rand_drbg.h> and documentation + for the RAND_DRBG API. See manual page RAND_DRBG(7) for an overview. + [Matthias St. Pierre] + *) QNX support removed (cannot find contributors to get their approval for the license change). [Rich Salz] @@ -1,4 +1,3 @@ - OPENSSL INSTALLATION -------------------- @@ -209,12 +208,40 @@ without a path). This flag must be provided if the zlib-dynamic option is not also used. If zlib-dynamic is used then this flag is optional and a default value ("ZLIB1") is - used if not provided. + used if not provided. On VMS: this is the filename of the zlib library (with or without a path). This flag is optional and if not provided then "GNV$LIBZSHR", "GNV$LIBZSHR32" or "GNV$LIBZSHR64" is used by default depending on the pointer size chosen. + + --with-rand-seed=seed1[,seed2,...] + A comma separated list of seeding methods which will be tried + by OpenSSL in order to obtain random input (a.k.a "entropy") + for seeding its cryptographically secure random number + generator (CSPRNG). The current seeding methods are: + + os: Use a trusted operating system entropy source. + This is the default method if such an entropy + source exists. + getrandom: Use the L<getrandom(2)> system call if available. + devrandom: Use the the first device from the DEVRANDOM list + which can be opened to read random bytes. The + DEVRANDOM preprocessor constant expands to + "/dev/urandom","/dev/random","/dev/srandom" on + most unix-ish operating systems. + egd: Check for an entropy generating daemon. + rdcpu: Use the RDSEED or RDRAND command if provided by + the CPU. + librandom: Use librandom (not implemented yet). + none: Disable automatic seeding. This is the default + on some operating systems where no suitable + entropy source exists, or no support for it is + implemented yet. + + For more information, see the section 'Note on random number + generation' at the end of this document. + no-afalgeng Don't build the AFALG engine. This option will be forced if on a platform that does not support AFALG. @@ -810,7 +837,7 @@ $ nmake TESTS='test_rsa test_dsa' test # Windows And of course, you can combine (Unix example shown): - + $ make VERBOSE=1 TESTS='test_rsa test_dsa' test You can find the list of available tests like this: @@ -883,7 +910,7 @@ command symbols. [.SYSTEST] Contains the installation verification procedure. [.HTML] Contains the HTML rendition of the manual pages. - + Additionally, install will add the following directories under OPENSSLDIR (the directory given with --openssldir or its default) @@ -1164,10 +1191,22 @@ Availability of cryptographically secure random numbers is required for secret key generation. OpenSSL provides several options to seed the - internal PRNG. If not properly seeded, the internal PRNG will refuse + internal CSPRNG. If not properly seeded, the internal CSPRNG will refuse to deliver random bytes and a "PRNG not seeded error" will occur. - On systems without /dev/urandom (or similar) device, it may be necessary - to install additional support software to obtain a random seed. - Please check out the manual pages for RAND_add(), RAND_bytes(), RAND_egd(), - and the FAQ for more information. + The seeding method can be configured using the --with-rand-seed option, + which can be used to specify a comma separated list of seed methods. + However in most cases OpenSSL will choose a suitable default method, + so it is not necessary to explicitely provide this option. Note also + that not all methods are available on all platforms. + + I) On operating systems which provide a suitable randomness source (in + form of a system call or system device), OpenSSL will use the optimal + available method to seed the CSPRNG from the operating system's + randomness sources. This corresponds to the option --with-rand-seed=os. + + II) On systems without such a suitable randomness source, automatic seeding + and reseeding is disabled (--with-rand-seed=none) and it may be necessary + to install additional support software to obtain a random seed and reseed + the CSPRNG manually. Please check out the manual pages for RAND_add(), + RAND_bytes(), RAND_egd(), and the FAQ for more information. diff --git a/crypto/rand/drbg_lib.c b/crypto/rand/drbg_lib.c index 723f6307fd..e1b3ddb57f 100644 --- a/crypto/rand/drbg_lib.c +++ b/crypto/rand/drbg_lib.c @@ -17,8 +17,9 @@ #include "internal/cryptlib_int.h" /* - * Support framework for NIST SP 800-90A DRBG, AES-CTR mode. - * The RAND_DRBG is OpenSSL's pointer to an instance of the DRBG. + * Support framework for NIST SP 800-90A DRBG + * + * See manual page RAND_DRBG(7) for a general overview. * * The OpenSSL model is to have new and free functions, and that new * does all initialization. That is not the NIST model, which has @@ -29,80 +30,46 @@ */ /* - * THE THREE SHARED DRBGs - * - * There are three shared DRBGs (master, public and private), which are - * accessed concurrently by all threads. + * The three shared DRBG instances * - * THE MASTER DRBG + * There are three shared DRBG instances: <master>, <public>, and <private>. + */ + +/* + * The <master> DRBG * * Not used directly by the application, only for reseeding the two other * DRBGs. It reseeds itself by pulling either randomness from os entropy - * sources or by consuming randomnes which was added by RAND_add() - */ -static RAND_DRBG *drbg_master; -/*+ - * DRBG HIERARCHY - * - * In addition there are DRBGs, which are not shared, but used only by a - * single thread at every time, for example the DRBGs which are owned by - * an SSL context. All DRBGs are organized in a hierarchical fashion - * with the <master> DRBG as root. + * sources or by consuming randomness which was added by RAND_add(). * - * This gives the following overall picture: - * - * <os entropy sources> - * | - * RAND_add() ==> <master> \ - * / \ | shared DRBGs (with locking) - * <public> <private> / - * | - * <ssl> owned by an SSL context - * - * AUTOMATIC RESEEDING - * - * Before satisfying a generate request, a DRBG reseeds itself automatically, - * if one of the following two conditions holds: - * - * - the number of generate requests since the last reseeding exceeds a - * certain threshold, the so called |reseed_interval|. This behaviour - * can be disabled by setting the |reseed_interval| to 0. - * - * - the time elapsed since the last reseeding exceeds a certain time - * interval, the so called |reseed_time_interval|. This behaviour - * can be disabled by setting the |reseed_time_interval| to 0. - * - * MANUAL RESEEDING + * The <master> DRBG is a global instance which is accessed concurrently by + * all threads. The necessary locking is managed automatically by its child + * DRBG instances during reseeding. + */ +static RAND_DRBG *master_drbg; +/* + * The <public> DRBG * - * For the three shared DRBGs (and only for these) there is another way to - * reseed them manually by calling RAND_seed() (or RAND_add() with a positive - * |randomness| argument). This will immediately reseed the <master> DRBG. - * The <public> and <private> DRBG will detect this on their next generate - * call and reseed, pulling randomness from <master>. + * Used by default for generating random bytes using RAND_bytes(). * - * LOCKING + * The <public> DRBG is thread-local, i.e., there is one instance per thread. + */ +static CRYPTO_THREAD_LOCAL public_drbg; +/* + * The <private> DRBG * - * The three shared DRBGs are intended to be used concurrently, so they - * support locking. The RAND methods take the locks automatically, so using - * the RAND api (in particular RAND_bytes() and RAND_priv_bytes()) is - * thread-safe. Note however that accessing the shared DRBGs directly via - * the RAND_DRBG interface is *not* thread-safe. + * Used by default for generating private keys using RAND_priv_bytes() * - * All other DRBG instances don't support locking, because they are - * intendended to be used by a single thread. Instead of accessing a single - * DRBG instance concurrently from different threads, it is recommended to - * instantiate a separate DRBG instance per thread. Using the same shared - * DRBG (preferrably the public DRBG) as parent of DRBG instances on - * different threads is safe. + * The <private> DRBG is thread-local, i.e., there is one instance per thread. */ +static CRYPTO_THREAD_LOCAL private_drbg; + /* NIST SP 800-90A DRBG recommends the use of a personalization string. */ static const char ossl_pers_string[] = "OpenSSL NIST SP 800-90A DRBG"; static CRYPTO_ONCE rand_drbg_init = CRYPTO_ONCE_STATIC_INIT; -static CRYPTO_THREAD_LOCAL private_drbg_thread_local_key; -static CRYPTO_THREAD_LOCAL public_drbg_thread_local_key; @@ -683,40 +650,10 @@ err: /* * Set the RAND_DRBG callbacks for obtaining entropy and nonce. * - * In the following, the signature and the semantics of the - * get_entropy() and cleanup_entropy() callbacks are explained. - * - * GET_ENTROPY - * - * size_t get_entropy(RAND_DRBG *ctx, - * unsigned char **pout, - * int entropy, - * size_t min_len, size_t max_len); - * - * This is a request to allocate and fill a buffer of size - * |min_len| <= size <= |max_len| (in bytes) which contains - * at least |entropy| bits of randomness. The buffer's address is - * to be returned in |*pout| and the number of collected - * randomness bytes (which may be less than the allocated size - * of the buffer) as return value. + * Setting the callbacks is allowed only if the drbg has not been + * initialized yet. Otherwise, the operation will fail. * - * If the callback fails to acquire at least |entropy| bits of - * randomness, it shall return a buffer length of 0. - * - * CLEANUP_ENTROPY - * - * void cleanup_entropy(RAND_DRBG *ctx, - * unsigned char *out, size_t outlen); - * - * A request to clear and free the buffer allocated by get_entropy(). - * The values |out| and |outlen| are expected to be the random buffer's - * address and length, as returned by the get_entropy() callback. - * - * GET_NONCE, CLEANUP_NONCE - * - * Signature and semantics of the get_nonce() and cleanup_nonce() - * callbacks are analogous to get_entropy() and cleanup_entropy(). - * Currently, the nonce is used only for the known answer tests. + * Returns 1 on success, 0 on failure. */ int RAND_DRBG_set_callbacks(RAND_DRBG *drbg, RAND_DRBG_get_entropy_fn get_entropy, @@ -936,12 +873,12 @@ DEFINE_RUN_ONCE_STATIC(do_rand_drbg_init) ossl_init_thread_start(OPENSSL_INIT_THREAD_RAND); - drbg_master = drbg_setup(NULL); + master_drbg = drbg_setup(NULL); - ret &= CRYPTO_THREAD_init_local(&private_drbg_thread_local_key, NULL); - ret &= CRYPTO_THREAD_init_local(&public_drbg_thread_local_key, NULL); + ret &= CRYPTO_THREAD_init_local(&private_drbg, NULL); + ret &= CRYPTO_THREAD_init_local(&public_drbg, NULL); - if (drbg_master == NULL || ret == 0) + if (master_drbg == NULL || ret == 0) return 0; return 1; @@ -950,21 +887,21 @@ DEFINE_RUN_ONCE_STATIC(do_rand_drbg_init) /* Clean up the global DRBGs before exit */ void rand_drbg_cleanup_int(void) { - RAND_DRBG_free(drbg_master); - drbg_master = NULL; + RAND_DRBG_free(master_drbg); + master_drbg = NULL; - CRYPTO_THREAD_cleanup_local(&private_drbg_thread_local_key); - CRYPTO_THREAD_cleanup_local(&public_drbg_thread_local_key); + CRYPTO_THREAD_cleanup_local(&private_drbg); + CRYPTO_THREAD_cleanup_local(&public_drbg); } void drbg_delete_thread_state() { RAND_DRBG *drbg; - drbg = CRYPTO_THREAD_get_local(&public_drbg_thread_local_key); + drbg = CRYPTO_THREAD_get_local(&public_drbg); RAND_DRBG_free(drbg); - drbg = CRYPTO_THREAD_get_local(&private_drbg_thread_local_key); + drbg = CRYPTO_THREAD_get_local(&private_drbg); RAND_DRBG_free(drbg); } @@ -1044,7 +981,7 @@ RAND_DRBG *RAND_DRBG_get0_master(void) if (!RUN_ONCE(&rand_drbg_init, do_rand_drbg_init)) return NULL; - return drbg_master; + return master_drbg; } /* @@ -1058,11 +995,11 @@ RAND_DRBG *RAND_DRBG_get0_public(void) if (!RUN_ONCE(&rand_drbg_init, do_rand_drbg_init)) return NULL; - drbg = CRYPTO_THREAD_get_local(&public_drbg_thread_local_key); + drbg = CRYPTO_THREAD_get_local(&public_drbg); if (drbg == NULL) { ossl_init_thread_start(OPENSSL_INIT_THREAD_RAND); - drbg = drbg_setup(drbg_master); - CRYPTO_THREAD_set_local(&public_drbg_thread_local_key, drbg); + drbg = drbg_setup(master_drbg); + CRYPTO_THREAD_set_local(&public_drbg, drbg); } return drbg; } @@ -1078,11 +1015,11 @@ RAND_DRBG *RAND_DRBG_get0_private(void) if (!RUN_ONCE(&rand_drbg_init, do_rand_drbg_init)) return NULL; - drbg = CRYPTO_THREAD_get_local(&private_drbg_thread_local_key); + drbg = CRYPTO_THREAD_get_local(&private_drbg); if (drbg == NULL) { ossl_init_thread_start(OPENSSL_INIT_THREAD_RAND); - drbg = drbg_setup(drbg_master); - CRYPTO_THREAD_set_local(&private_drbg_thread_local_key, drbg); + drbg = drbg_setup(master_drbg); + CRYPTO_THREAD_set_local(&private_drbg, drbg); } return drbg; } diff --git a/doc/man3/CRYPTO_get_ex_new_index.pod b/doc/man3/CRYPTO_get_ex_new_index.pod index 1a4ad52de0..4d5a2b93a0 100644 --- a/doc/man3/CRYPTO_get_ex_new_index.pod +++ b/doc/man3/CRYPTO_get_ex_new_index.pod @@ -40,20 +40,22 @@ Several OpenSSL structures can have application-specific data attached to them, known as "exdata." The specific structures are: - SSL - SSL_CTX - SSL_SESSION - X509 - X509_STORE - X509_STORE_CTX + APP + BIO DH + DRBG DSA EC_KEY - RSA ENGINE + RSA + SSL + SSL_CTX + SSL_SESSION UI UI_METHOD - BIO + X509 + X509_STORE + X509_STORE_CTX Each is identified by an B<CRYPTO_EX_INDEX_xxx> define in the B<crypto.h> header file. In addition, B<CRYPTO_EX_INDEX_APP> is reserved for @@ -155,7 +157,7 @@ dup_func() should return 0 for failure and 1 for success. =head1 COPYRIGHT -Copyright 2015-2017 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2015-2018 The OpenSSL Project Authors. All Rights Reserved. Licensed under the OpenSSL license (the "License"). You may not use this file except in compliance with the License. You can obtain a copy diff --git a/doc/man3/RAND_DRBG_generate.pod b/doc/man3/RAND_DRBG_generate.pod new file mode 100644 index 0000000000..b39ee93f51 --- /dev/null +++ b/doc/man3/RAND_DRBG_generate.pod @@ -0,0 +1,88 @@ +=pod + +=head1 NAME + +RAND_DRBG_generate, +RAND_DRBG_bytes +- generate random bytes using the given drbg instance + +=head1 SYNOPSIS + + #include <openssl/rand_drbg.h> + + int RAND_DRBG_generate(RAND_DRBG *drbg, + unsigned char *out, size_t outlen, + int prediction_resistance, + const unsigned char *adin, size_t adinlen); + + int RAND_DRBG_bytes(RAND_DRBG *drbg, + unsigned char *out, size_t outlen); + + +=head1 DESCRIPTION + +RAND_DRBG_generate() generates B<outlen> random bytes using the given +DRBG instance B<drbg> and stores them in the buffer at B<out>. + +Before generating the output, the DRBG instance checks whether the maximum +number of generate requests (I<reseed interval>) or the maximum timespan +(I<reseed time interval>) since its last seeding have been reached. +If this is the case, the DRBG reseeds automatically. +Additionally, an immediate reseeding can be requested by setting the +B<prediction_resistance> flag to 1. See NOTES section for more details. + +The caller can optionally provide additional data to be used for reseeding +by passing a pointer B<adin> to a buffer of length B<adinlen>. +This additional data is mixed into the internal state of the random +generator but does not contribute to the entropy count. +The additional data can be omitted by setting B<adin> to NULL and +B<adinlen> to 0; + +RAND_DRBG_bytes() generates B<outlen> random bytes using the given +DRBG instance B<drbg> and stores them in the buffer at B<out>. +This function is a wrapper around the RAND_DRBG_generate() call, +which collects some additional data from low entropy sources +(e.g., a high resolution timer) and calls +RAND_DRBG_generate(drbg, out, outlen, 0, adin, adinlen). + + +=head1 RETURN VALUES + +RAND_DRBG_generate() and RAND_DRBG_bytes() return 1 on success, +and 0 on failure. + +=head1 NOTES + +The I<reseed interval> and I<reseed time interval> of the B<drbg> are set to +reasonable default values, which in general do not have to be adjusted. +If necessary, they can be changed using L<RAND_DRBG_set_reseed_interval(3)> +and L<RAND_DRBG_set_reseed_time_interval(3)>, respectively. + +A request for prediction resistance can only be satisfied by pulling fresh +entropy from one of the approved entropy sources listed in section 5.5.2 of +[NIST SP 800-90C]. +Since the default DRBG implementation does not have access to such an approved +entropy source, a request for prediction resistance will always fail. +In other words, prediction resistance is currently not supported yet by the DRBG. + +=head1 HISTORY + +The RAND_DRBG functions were added in OpenSSL 1.1.1. + +=head1 SEE ALSO + +L<RAND_bytes(3)>, +L<RAND_DRBG_set_reseed_interval(3)>, +L<RAND_DRBG_set_reseed_time_interval(3)>, +L<RAND_DRBG(7)> + +=head1 COPYRIGHT + +Copyright 2017-2018 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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/RAND_DRBG_get0_master.pod b/doc/man3/RAND_DRBG_get0_master.pod new file mode 100644 index 0000000000..c958bf20ec --- /dev/null +++ b/doc/man3/RAND_DRBG_get0_master.pod @@ -0,0 +1,80 @@ +=pod + +=head1 NAME + +RAND_DRBG_get0_master, +RAND_DRBG_get0_public, +RAND_DRBG_get0_private +- get access to the global RAND_DRBG instances + +=head1 SYNOPSIS + + #include <openssl/rand_drbg.h> + + RAND_DRBG *RAND_DRBG_get0_master(void); + RAND_DRBG *RAND_DRBG_get0_public(void); + RAND_DRBG *RAND_DRBG_get0_private(void); + + +=head1 DESCRIPTION + +The default RAND API implementation (RAND_OpenSSL()) utilizes three +shared DRBG instances which are accessed via the RAND API: + +The <public> and <private> DRBG are thread-local instances, which are used +by RAND_bytes() and RAND_priv_bytes(), respectively. +The <master> DRBG is a global instance, which is not intended to be used +directly, but is used internally to reseed the other two instances. + +These functions here provide access to the shared DRBG instances. + +=head1 RETURN VALUES + +RAND_DRBG_get0_master() returns a pointer to the <master> DRBG instance. + +RAND_DRBG_get0_public() returns a pointer to the <public> DRBG instance. + +RAND_DRBG_get0_private() returns a pointer to the <private> DRBG instance. + + +=head1 NOTES + +It is not thread-safe to access the <master> DRBG instance. +The <public> and <private> DRBG instance can be accessed safely, because +they are thread-local. Note however, that changes to these two instances +apply only to the current thread. + +For that reason it is recommended not to change the settings of these +three instances directly. +Instead, an application should change the default settings for new DRBG instances +at initialization time, before creating additional threads. + +During initialization, it is possible to change the reseed interval +and reseed time interval. +It is also possible to exchange the reseeding callbacks entirely. + + +=head1 HISTORY + +The RAND_DRBG functions were added in OpenSSL 1.1.1. + +=head1 SEE ALSO + +L<RAND_DRBG_set_callbacks(3)>, +L<RAND_DRBG_set_reseed_defaults(3)>, +L<RAND_DRBG_set_reseed_interval(3)>, +L<RAND_DRBG_set_reseed_time_interval(3)>, +L<RAND_DRBG_set_callbacks(3)>, +L<RAND_DRBG_generate(3)>, +L<RAND_DRBG(7)> + +=head1 COPYRIGHT + +Copyright 2017-2018 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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/RAND_DRBG_new.pod b/doc/man3/RAND_DRBG_new.pod new file mode 100644 index 0000000000..dcd7a94419 --- /dev/null +++ b/doc/man3/RAND_DRBG_new.pod @@ -0,0 +1,127 @@ +=pod + +=head1 NAME + +RAND_DRBG_new, +RAND_DRBG_secure_new, +RAND_DRBG_set, +RAND_DRBG_set_defaults, +RAND_DRBG_instantiate, +RAND_DRBG_uninstantiate, +RAND_DRBG_free +- initialize and cleanup a RAND_DRBG instance + +=head1 SYNOPSIS + + #include <openssl/rand_drbg.h> + + + RAND_DRBG *RAND_DRBG_new(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(RAND_DRBG *drbg, + int type, unsigned int flags); + + int RAND_DRBG_set_defaults(int type, unsigned int flags); + + int RAND_DRBG_instantiate(RAND_DRBG *drbg, + const unsigned char *pers, size_t perslen); + + int RAND_DRBG_uninstantiate(RAND_DRBG *drbg); + + void RAND_DRBG_free(RAND_DRBG *drbg); + + +=head1 DESCRIPTION + +RAND_DRBG_new() and RAND_DRBG_secure_new() +create a new DRBG instance of the given B<type>, allocated from the heap resp. +the secure heap +(using OPENSSL_zalloc() resp. OPENSSL_secure_zalloc()). + +RAND_DRBG_set() initializes the B<drbg> with the given B<type> and B<flags>. + +RAND_DRBG_set_defaults() sets the default B<type> and B<flags> for new DRBG +instances. + +Currently, all DRBG types are based on AES-CTR, so B<type> can be one of the +following values: NID_aes_128_ctr, NID_aes_192_ctr, NID_aes_256_ctr. +Before the DRBG can be used to generate random bits, it is necessary to set +its type and to instantiate it. + +The optional B<flags> argument specifies a set of bit flags which can be +joined using the | operator. Currently, the only flag is +RAND_DRBG_FLAG_CTR_NO_DF, which disables the use of a the derivation function +ctr_df. For an explanation, see [NIST SP 800-90A Rev. 1]. + +If a B<parent> instance is specified then this will be used instead of +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 +specified. +To omit the personalization string, set B<pers>=NULL and B<perslen>=0; + +RAND_DRBG_uninstantiate() +clears the internal state of the B<drbg> and puts it back in the +uninstantiated state. + +=head1 RETURN VALUES + + +RAND_DRBG_new() and RAND_DRBG_secure_new() return a pointer to a DRBG +instance allocated on the heap, resp. secure heap. + +RAND_DRBG_set(), +RAND_DRBG_instantiate(), and +RAND_DRBG_uninstantiate() +return 1 on success, and 0 on failure. + +RAND_DRBG_free() does not return a value. + +=head1 NOTES + +The DRBG design supports I<chaining>, which means that a DRBG instance can +use another B<parent> DRBG instance instead of the default entropy source +to obtain fresh random input for reseeding, provided that B<parent> DRBG +instance was properly instantiated, either from a trusted entropy source, +or from yet another parent DRBG instance. +For a detailed description of the reseeding process, see L<RAND_DRBG(7)>. + +The default DRBG type and flags are applied only during creation of a DRBG +instance. +To ensure that they are applied to the global and thread-local DRBG instances +(<master>, resp. <public> and <private>), it is necessary to call +RAND_DRBG_set_defaults() before creating any thread and before calling any +cryptographic routines that obtain random data directly or indirectly. + +=head1 HISTORY + +The RAND_DRBG functions were added in OpenSSL 1.1.1. + +=head1 SEE ALSO + +L<OPENSSL_zalloc(3)>, +L<OPENSSL_secure_zalloc(3)>, +L<RAND_DRBG_generate(3)>, +L<RAND_DRBG(7)> + +=head1 COPYRIGHT + +Copyright 2017-2018 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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/RAND_DRBG_reseed.pod b/doc/man3/RAND_DRBG_reseed.pod new file mode 100644 index 0000000000..da3a40be44 --- /dev/null +++ b/doc/man3/RAND_DRBG_reseed.pod @@ -0,0 +1,111 @@ +=pod + +=head1 NAME + +RAND_DRBG_reseed, +RAND_DRBG_set_reseed_interval, +RAND_DRBG_set_reseed_time_interval, +RAND_DRBG_set_reseed_defaults +- reseed a RAND_DRBG instance + +=head1 SYNOPSIS + + #include <openssl/rand_drbg.h> + + int RAND_DRBG_reseed(RAND_DRBG *drbg, + const unsigned char *adin, size_t adinlen); + + int RAND_DRBG_set_reseed_interval(RAND_DRBG *drbg, + unsigned int interval); + + int RAND_DRBG_set_reseed_time_interval(RAND_DRBG *drbg, + time_t interval); + + int RAND_DRBG_set_reseed_defaults( + unsigned int master_reseed_interval, + unsigned int slave_reseed_interval, + time_t master_reseed_time_interval, + time_t slave_reseed_time_interval + ); + + +=head1 DESCRIPTION + +RAND_DRBG_reseed() +reseeds the given B<drbg>, obtaining entropy input from its entropy source +and mixing in the specified additional data provided in the buffer B<adin> +of length B<adinlen>. +The additional data can be omitted by setting B<adin> to NULL and B<adinlen> +to 0. + +RAND_DRBG_set_reseed_interval() +sets the reseed interval of the B<drbg>, which is the maximum allowed number +of generate requests between consecutive reseedings. +If B<interval> > 0, then the B<drbg> will reseed automatically whenever the +number of generate requests since its last seeding exceeds the given reseed +interval. +If B<interval> == 0, then this feature is disabled. + + +RAND_DRBG_set_reseed_time_interval() +sets the reseed time interval of the B<drbg>, which is the maximum allowed +number of seconds between consecutive reseedings. +If B<interval> > 0, then the B<drbg> will reseed automatically whenever the +elapsed time since its last reseeding exceeds the given reseed time interval. +If B<interval> == 0, then this feature is disabled. + +RAND_DRBG_set_reseed_defaults() sets the default values for the reseed interval +(B<master_reseed_interval> and B<slave_reseed_interval>) +and the reseed time interval +(B<master_reseed_time_interval> and B<slave_reseed_tme_interval>) +of DRBG instances. +The default values are set independently for master DRBG instances (which don't +have a parent) and slave DRBG instances (which are chained to a parent DRBG). + +=head1 RETURN VALUES + +RAND_DRBG_reseed(), +RAND_DRBG_set_reseed_interval(), and +RAND_DRBG_set_reseed_time_interval(), +return 1 on success, 0 on failure. + + +=head1 NOTES + +The default OpenSSL random generator is already set up for automatic reseeding, +so in general it is not necessary to reseed it explicitly, or to modify +its reseeding thresholds. + +Normally, the entropy input for seeding a DRBG is either obtained from a +trusted os entropy source or from a parent DRBG instance, which was seeded +(directly or indirectly) from a trusted os entropy source. +In exceptional cases it is possible to replace the reseeding mechanism entirely +by providing application defined callbacks using RAND_DRBG_set_callbacks(). |