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