1b077aed3SPierre Pronchery=pod 2b077aed3SPierre Pronchery 3b077aed3SPierre Pronchery=head1 NAME 4b077aed3SPierre Pronchery 5b077aed3SPierre ProncheryEVP_RAND-TEST-RAND - The test EVP_RAND implementation 6b077aed3SPierre Pronchery 7b077aed3SPierre Pronchery=head1 DESCRIPTION 8b077aed3SPierre Pronchery 9b077aed3SPierre ProncherySupport for a test generator through the B<EVP_RAND> API. This generator is 10b077aed3SPierre Proncheryfor test purposes only, it does not generate random numbers. 11b077aed3SPierre Pronchery 12b077aed3SPierre Pronchery=head2 Identity 13b077aed3SPierre Pronchery 14b077aed3SPierre Pronchery"TEST-RAND" is the name for this implementation; it can be used with the 15b077aed3SPierre ProncheryEVP_RAND_fetch() function. 16b077aed3SPierre Pronchery 17b077aed3SPierre Pronchery=head2 Supported parameters 18b077aed3SPierre Pronchery 19b077aed3SPierre ProncheryThe supported parameters are: 20b077aed3SPierre Pronchery 21b077aed3SPierre Pronchery=over 4 22b077aed3SPierre Pronchery 23b077aed3SPierre Pronchery=item "state" (B<OSSL_RAND_PARAM_STATE>) <integer> 24b077aed3SPierre Pronchery 25*e7be843bSPierre Pronchery=item "fips-indicator" (B<OSSL_RAND_PARAM_FIPS_APPROVED_INDICATOR>) <integer> 26*e7be843bSPierre Pronchery 27b077aed3SPierre ProncheryThese parameter works as described in L<EVP_RAND(3)/PARAMETERS>. 28b077aed3SPierre Pronchery 29b077aed3SPierre Pronchery=item "strength" (B<OSSL_RAND_PARAM_STRENGTH>) <unsigned integer> 30b077aed3SPierre Pronchery 31b077aed3SPierre Pronchery=item "reseed_requests" (B<OSSL_DRBG_PARAM_RESEED_REQUESTS>) <unsigned integer> 32b077aed3SPierre Pronchery 33b077aed3SPierre Pronchery=item "reseed_time_interval" (B<OSSL_DRBG_PARAM_RESEED_TIME_INTERVAL>) <integer> 34b077aed3SPierre Pronchery 35b077aed3SPierre Pronchery=item "max_request" (B<OSSL_DRBG_PARAM_RESEED_REQUESTS>) <unsigned integer> 36b077aed3SPierre Pronchery 37b077aed3SPierre Pronchery=item "min_entropylen" (B<OSSL_DRBG_PARAM_MIN_ENTROPYLEN>) <unsigned integer> 38b077aed3SPierre Pronchery 39b077aed3SPierre Pronchery=item "max_entropylen" (B<OSSL_DRBG_PARAM_MAX_ENTROPYLEN>) <unsigned integer> 40b077aed3SPierre Pronchery 41b077aed3SPierre Pronchery=item "min_noncelen" (B<OSSL_DRBG_PARAM_MIN_NONCELEN>) <unsigned integer> 42b077aed3SPierre Pronchery 43b077aed3SPierre Pronchery=item "max_noncelen" (B<OSSL_DRBG_PARAM_MAX_NONCELEN>) <unsigned integer> 44b077aed3SPierre Pronchery 45b077aed3SPierre Pronchery=item "max_perslen" (B<OSSL_DRBG_PARAM_MAX_PERSLEN>) <unsigned integer> 46b077aed3SPierre Pronchery 47b077aed3SPierre Pronchery=item "max_adinlen" (B<OSSL_DRBG_PARAM_MAX_ADINLEN>) <unsigned integer> 48b077aed3SPierre Pronchery 49b077aed3SPierre Pronchery=item "reseed_counter" (B<OSSL_DRBG_PARAM_RESEED_COUNTER>) <unsigned integer> 50b077aed3SPierre Pronchery 51b077aed3SPierre ProncheryThese parameters work as described in L<EVP_RAND(3)/PARAMETERS>, except that 52b077aed3SPierre Proncherythey can all be set as well as read. 53b077aed3SPierre Pronchery 54b077aed3SPierre Pronchery=item "test_entropy" (B<OSSL_RAND_PARAM_TEST_ENTROPY>) <octet string> 55b077aed3SPierre Pronchery 56b077aed3SPierre ProncherySets the bytes returned when the test generator is sent an entropy request. 57b077aed3SPierre ProncheryThe current position is remembered across generate calls. 58b077aed3SPierre ProncheryIf there are insufficient data present to satisfy a call, an error is returned. 59b077aed3SPierre Pronchery 60b077aed3SPierre Pronchery=item "test_nonce" (B<OSSL_RAND_PARAM_TEST_NONCE>) <octet string> 61b077aed3SPierre Pronchery 62b077aed3SPierre ProncherySets the bytes returned when the test generator is sent a nonce request. 63b077aed3SPierre ProncheryEach nonce request will return all of the bytes. 64b077aed3SPierre Pronchery 65*e7be843bSPierre Pronchery=item "generate" (B<OSSL_RAND_PARAM_GENERATE>) <integer> 66*e7be843bSPierre Pronchery 67*e7be843bSPierre ProncheryIf this parameter is zero, it will only emit the nonce and entropy data 68*e7be843bSPierre Proncherysupplied via the aforementioned parameters. Otherwise, low quality 69*e7be843bSPierre Proncherynon-cryptographic pseudorandom output is produced. This parameter defaults 70*e7be843bSPierre Proncheryto zero. 71*e7be843bSPierre Pronchery 72b077aed3SPierre Pronchery=back 73b077aed3SPierre Pronchery 74b077aed3SPierre Pronchery=head1 NOTES 75b077aed3SPierre Pronchery 76b077aed3SPierre ProncheryA context for a test generator can be obtained by calling: 77b077aed3SPierre Pronchery 78b077aed3SPierre Pronchery EVP_RAND *rand = EVP_RAND_fetch(NULL, "TEST-RAND", NULL); 79*e7be843bSPierre Pronchery EVP_RAND_CTX *rctx = EVP_RAND_CTX_new(rand, NULL); 80b077aed3SPierre Pronchery 81b077aed3SPierre Pronchery=head1 EXAMPLES 82b077aed3SPierre Pronchery 83b077aed3SPierre Pronchery EVP_RAND *rand; 84b077aed3SPierre Pronchery EVP_RAND_CTX *rctx; 85b077aed3SPierre Pronchery unsigned char bytes[100]; 86b077aed3SPierre Pronchery OSSL_PARAM params[4], *p = params; 87b077aed3SPierre Pronchery unsigned char entropy[1000] = { ... }; 88b077aed3SPierre Pronchery unsigned char nonce[20] = { ... }; 89b077aed3SPierre Pronchery unsigned int strength = 48; 90b077aed3SPierre Pronchery 91b077aed3SPierre Pronchery rand = EVP_RAND_fetch(NULL, "TEST-RAND", NULL); 92b077aed3SPierre Pronchery rctx = EVP_RAND_CTX_new(rand, NULL); 93b077aed3SPierre Pronchery EVP_RAND_free(rand); 94b077aed3SPierre Pronchery 95b077aed3SPierre Pronchery *p++ = OSSL_PARAM_construct_uint(OSSL_RAND_PARAM_STRENGTH, &strength); 96b077aed3SPierre Pronchery *p++ = OSSL_PARAM_construct_octet_string(OSSL_RAND_PARAM_TEST_ENTROPY, 97b077aed3SPierre Pronchery entropy, sizeof(entropy)); 98b077aed3SPierre Pronchery *p++ = OSSL_PARAM_construct_octet_string(OSSL_RAND_PARAM_TEST_NONCE, 99b077aed3SPierre Pronchery nonce, sizeof(nonce)); 100b077aed3SPierre Pronchery *p = OSSL_PARAM_construct_end(); 101b077aed3SPierre Pronchery EVP_RAND_instantiate(rctx, strength, 0, NULL, 0, params); 102b077aed3SPierre Pronchery 103b077aed3SPierre Pronchery EVP_RAND_generate(rctx, bytes, sizeof(bytes), strength, 0, NULL, 0); 104b077aed3SPierre Pronchery 105b077aed3SPierre Pronchery EVP_RAND_CTX_free(rctx); 106b077aed3SPierre Pronchery 107b077aed3SPierre Pronchery=head1 SEE ALSO 108b077aed3SPierre Pronchery 109b077aed3SPierre ProncheryL<EVP_RAND(3)>, 110b077aed3SPierre ProncheryL<EVP_RAND(3)/PARAMETERS> 111b077aed3SPierre Pronchery 112b077aed3SPierre Pronchery=head1 HISTORY 113b077aed3SPierre Pronchery 114b077aed3SPierre ProncheryThis functionality was added in OpenSSL 3.0. 115b077aed3SPierre Pronchery 116b077aed3SPierre Pronchery=head1 COPYRIGHT 117b077aed3SPierre Pronchery 118*e7be843bSPierre ProncheryCopyright 2020-2024 The OpenSSL Project Authors. All Rights Reserved. 119b077aed3SPierre Pronchery 120b077aed3SPierre ProncheryLicensed under the Apache License 2.0 (the "License"). You may not use 121b077aed3SPierre Proncherythis file except in compliance with the License. You can obtain a copy 122b077aed3SPierre Proncheryin the file LICENSE in the source distribution or at 123b077aed3SPierre ProncheryL<https://www.openssl.org/source/license.html>. 124b077aed3SPierre Pronchery 125b077aed3SPierre Pronchery=cut 126