diff options
author | Pauli <paul.dale@oracle.com> | 2020-12-10 12:04:27 +1000 |
---|---|---|
committer | Pauli <ppzgs1@gmail.com> | 2021-02-23 23:24:13 +1000 |
commit | ac60c84fc4551761743e087e2f51343181eb8e85 (patch) | |
tree | 28b1b4cffff298bf8b2216a6b80abbb729beff0d | |
parent | f5b00834dd11d766b9232e89e40884db8f3cd7ec (diff) |
RAND_METHOD deprecation: documentation
Reviewed-by: Tim Hudson <tjh@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/13652)
-rw-r--r-- | doc/man3/RAND_get0_primary.pod | 1 | ||||
-rw-r--r-- | doc/man3/RAND_set_DRBG_type.pod | 64 | ||||
-rw-r--r-- | doc/man3/RAND_set_rand_method.pod | 14 | ||||
-rw-r--r-- | doc/man7/RAND.pod | 10 | ||||
-rw-r--r-- | fuzz/rand.inc | 40 |
5 files changed, 80 insertions, 49 deletions
diff --git a/doc/man3/RAND_get0_primary.pod b/doc/man3/RAND_get0_primary.pod index 5d84b330ab..cf0fae95f7 100644 --- a/doc/man3/RAND_get0_primary.pod +++ b/doc/man3/RAND_get0_primary.pod @@ -15,7 +15,6 @@ RAND_get0_private EVP_RAND_CTX *RAND_get0_public(OSSL_LIB_CTX *ctx); EVP_RAND_CTX *RAND_get0_private(OSSL_LIB_CTX *ctx); - =head1 DESCRIPTION The default RAND API implementation (RAND_OpenSSL()) utilizes three diff --git a/doc/man3/RAND_set_DRBG_type.pod b/doc/man3/RAND_set_DRBG_type.pod new file mode 100644 index 0000000000..f78c15ff45 --- /dev/null +++ b/doc/man3/RAND_set_DRBG_type.pod @@ -0,0 +1,64 @@ +=pod + +=head1 NAME + +RAND_set_DRBG_type, +RAND_set_seed_source_type +- specify the global random number generator types + +=head1 SYNOPSIS + + #include <openssl/rand.h> + + int RAND_set_DRBG_type(OSSL_LIB_CTX *ctx, const char *drbg, const char *propq, + const char *cipher, const char *digest); + int RAND_set_seed_source_type(OSSL_LIB_CTX *ctx, const char *seed, + const char *propq); + +=head1 DESCRIPTION + +RAND_set_DRBG_type() specifies the random bit generator that will be +used within the library context I<ctx>. A generator of name I<drbg> +with properties I<propq> will be fetched. It will be instantiated with +either I<cipher> or I<digest> as its underlying cryptographic algorithm. +This specifies the type that will be used for the primary, public and +private random instances. + +RAND_set_seed_source_type() specifies the seed source that will be used +within the library context I<ctx>. The seed source of name I<seed> +with properties I<propq> will be fetched and used to seed the primary +random big generator. + +=head1 RETURN VALUES + +These function return 1 on success and 0 on failure. + +=head1 NOTES + +These functions must be called before the random bit generators are first +created in the library context. They will return an error if the call +is made too late. + +The default DRBG is "CTR-DRBG" using the "AES-256-CTR" cipher. + +The default seed source is "SEED-SRC". + +=head1 SEE ALSO + +L<EVP_RAND(3)>, +L<RAND_get0_primary(3)> + +=head1 HISTORY + +These functions were added in OpenSSL 3.0. + +=head1 COPYRIGHT + +Copyright 2021 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/RAND_set_rand_method.pod b/doc/man3/RAND_set_rand_method.pod index a989c1c9b4..755e25dde1 100644 --- a/doc/man3/RAND_set_rand_method.pod +++ b/doc/man3/RAND_set_rand_method.pod @@ -8,6 +8,10 @@ RAND_set_rand_method, RAND_get_rand_method, RAND_OpenSSL - select RAND method #include <openssl/rand.h> +Deprecated since OpenSSL 3.0, can be hidden entirely by defining +B<OPENSSL_API_COMPAT> with a suitable version value, see +L<openssl_user_macros(7)>: + RAND_METHOD *RAND_OpenSSL(void); int RAND_set_rand_method(const RAND_METHOD *meth); @@ -16,6 +20,10 @@ RAND_set_rand_method, RAND_get_rand_method, RAND_OpenSSL - select RAND method =head1 DESCRIPTION +All of the functions described on this page are deprecated. +Applications should instead use L<RAND_set_DRBG_type(3)>, +L<EVP_RAND(3)> and L<EVP_RAND(7)>. + A B<RAND_METHOD> specifies the functions that OpenSSL uses for random number generation. @@ -55,14 +63,16 @@ methods. =head1 SEE ALSO +L<EVP_RAND(3)>, +L<RAND_set_DRBG_type(3)>, L<RAND_bytes(3)>, L<ENGINE_by_id(3)>, +L<EVP_RAND(7)>, L<RAND(7)> =head1 HISTORY -The ability for an B<ENGINE> to replace the RAND API was deprecated in -OpenSSL 3.0. +All of these functions were deprecated in OpenSSL 3.0. =head1 COPYRIGHT diff --git a/doc/man7/RAND.pod b/doc/man7/RAND.pod index 7bad23a0ca..8ae55ccac8 100644 --- a/doc/man7/RAND.pod +++ b/doc/man7/RAND.pod @@ -46,8 +46,8 @@ possible about its internal state, and that a compromise of the "public" CSPRNG instance will not affect the secrecy of these private values. In the rare case where the default implementation does not satisfy your special -requirements, the default RAND method can be replaced by your own RAND -method using L<RAND_set_rand_method(3)>. +requirements, the default RAND internals can be replaced by your own +L<EVP_RAND(3)> objects. Changing the default random generator should be necessary only in exceptional cases and is not recommended, unless you have a profound @@ -66,11 +66,9 @@ number generator (CSPRNG), which is described in [NIST SP 800-90A Rev. 1]. L<RAND_bytes(3)>, L<RAND_priv_bytes(3)>, -L<RAND_get_rand_method(3)>, -L<RAND_set_rand_method(3)>, -L<RAND_OpenSSL(3)>, L<EVP_RAND(3)>, -L<RAND_get0_primary(3)> +L<RAND_get0_primary(3)>, +L<EVP_RAND(7)> =head1 COPYRIGHT diff --git a/fuzz/rand.inc b/fuzz/rand.inc deleted file mode 100644 index d0eebff896..0000000000 --- a/fuzz/rand.inc +++ /dev/null @@ -1,40 +0,0 @@ -/* - * Copyright 2016 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 may obtain a copy of the License at - * https://www.openssl.org/source/license.html - * or in the file LICENSE in the source distribution. - */ -#include <openssl/rand.h> - -static int fuzz_bytes(unsigned char *buf, int num) -{ - unsigned char val = 1; - - while (--num >= 0) - *buf++ = val++; - return 1; -} - -static int fuzz_status(void) -{ - return 1; -} - -static RAND_METHOD fuzz_rand_method = { - NULL, - fuzz_bytes, - NULL, - NULL, - fuzz_bytes, - fuzz_status -}; - -void FuzzerSetRand(void) -{ - RAND_set_rand_method(&fuzz_rand_method); -} - - |