1*e7be843bSPierre Pronchery=pod 2*e7be843bSPierre Pronchery 3*e7be843bSPierre Pronchery=head1 NAME 4*e7be843bSPierre Pronchery 5*e7be843bSPierre ProncheryEVP_RAND-JITTER - The randomness seed source EVP_RAND implementation 6*e7be843bSPierre Pronchery 7*e7be843bSPierre Pronchery=head1 DESCRIPTION 8*e7be843bSPierre Pronchery 9*e7be843bSPierre ProncherySupport for deterministic random number generator seeding through the 10*e7be843bSPierre ProncheryB<EVP_RAND> API. 11*e7be843bSPierre Pronchery 12*e7be843bSPierre ProncheryThis software seed source produces randomness based on tiny CPU 13*e7be843bSPierre Pronchery"jitter" fluctuations. 14*e7be843bSPierre Pronchery 15*e7be843bSPierre ProncheryIt is available when OpenSSL is compiled with B<enable-jitter> 16*e7be843bSPierre Proncheryoption. When available it is listed in B<openssl list 17*e7be843bSPierre Pronchery-random-generators> and B<openssl info -seeds>. 18*e7be843bSPierre Pronchery 19*e7be843bSPierre Pronchery=head2 Identity 20*e7be843bSPierre Pronchery 21*e7be843bSPierre Pronchery"JITTER" is the name for this implementation; it can be used with the 22*e7be843bSPierre ProncheryEVP_RAND_fetch() function. 23*e7be843bSPierre Pronchery 24*e7be843bSPierre Pronchery=head2 Supported parameters 25*e7be843bSPierre Pronchery 26*e7be843bSPierre ProncheryThe supported parameters are: 27*e7be843bSPierre Pronchery 28*e7be843bSPierre Pronchery=over 4 29*e7be843bSPierre Pronchery 30*e7be843bSPierre Pronchery=item "state" (B<OSSL_RAND_PARAM_STATE>) <integer> 31*e7be843bSPierre Pronchery 32*e7be843bSPierre Pronchery=item "strength" (B<OSSL_RAND_PARAM_STRENGTH>) <unsigned integer> 33*e7be843bSPierre Pronchery 34*e7be843bSPierre Pronchery=item "max_request" (B<OSSL_RAND_PARAM_MAX_REQUEST>) <unsigned integer> 35*e7be843bSPierre Pronchery 36*e7be843bSPierre ProncheryThese parameters work as described in L<EVP_RAND(3)/PARAMETERS>. 37*e7be843bSPierre Pronchery 38*e7be843bSPierre Pronchery=back 39*e7be843bSPierre Pronchery 40*e7be843bSPierre Pronchery=head1 NOTES 41*e7be843bSPierre Pronchery 42*e7be843bSPierre ProncheryA context for the seed source can be obtained by calling: 43*e7be843bSPierre Pronchery 44*e7be843bSPierre Pronchery EVP_RAND *rand = EVP_RAND_fetch(NULL, "JITTER", NULL); 45*e7be843bSPierre Pronchery EVP_RAND_CTX *rctx = EVP_RAND_CTX_new(rand, NULL); 46*e7be843bSPierre Pronchery 47*e7be843bSPierre ProncheryThe B<enable-jitter> option was added in OpenSSL 3.4. 48*e7be843bSPierre Pronchery 49*e7be843bSPierre ProncheryBy specifying the B<enable-fips-jitter> configuration option, the FIPS 50*e7be843bSPierre Proncheryprovider will use an internal jitter source for its entropy. Enabling 51*e7be843bSPierre Proncherythis option will cause the FIPS provider to operate in a non-compliant 52*e7be843bSPierre Proncherymode unless an entropy assessment 53*e7be843bSPierre ProncheryL<ESV|https://csrc.nist.gov/Projects/cryptographic-module-validation-program/entropy-validations> 54*e7be843bSPierre Proncheryand validation through the 55*e7be843bSPierre ProncheryL<CMVP|https://csrc.nist.gov/projects/cryptographic-module-validation-program> 56*e7be843bSPierre Proncheryare additionally conducted. This option was added in OpenSSL 3.5. 57*e7be843bSPierre Pronchery 58*e7be843bSPierre Pronchery=head1 EXAMPLES 59*e7be843bSPierre Pronchery 60*e7be843bSPierre Pronchery EVP_RAND *rand; 61*e7be843bSPierre Pronchery EVP_RAND_CTX *seed, *rctx; 62*e7be843bSPierre Pronchery unsigned char bytes[100]; 63*e7be843bSPierre Pronchery OSSL_PARAM params[2], *p = params; 64*e7be843bSPierre Pronchery unsigned int strength = 128; 65*e7be843bSPierre Pronchery 66*e7be843bSPierre Pronchery /* Create and instantiate a seed source */ 67*e7be843bSPierre Pronchery rand = EVP_RAND_fetch(NULL, "JITTER", NULL); 68*e7be843bSPierre Pronchery seed = EVP_RAND_CTX_new(rand, NULL); 69*e7be843bSPierre Pronchery EVP_RAND_instantiate(seed, strength, 0, NULL, 0, NULL); 70*e7be843bSPierre Pronchery EVP_RAND_free(rand); 71*e7be843bSPierre Pronchery 72*e7be843bSPierre Pronchery /* Feed this into a DRBG */ 73*e7be843bSPierre Pronchery rand = EVP_RAND_fetch(NULL, "CTR-DRBG", NULL); 74*e7be843bSPierre Pronchery rctx = EVP_RAND_CTX_new(rand, seed); 75*e7be843bSPierre Pronchery EVP_RAND_free(rand); 76*e7be843bSPierre Pronchery 77*e7be843bSPierre Pronchery /* Configure the DRBG */ 78*e7be843bSPierre Pronchery *p++ = OSSL_PARAM_construct_utf8_string(OSSL_DRBG_PARAM_CIPHER, 79*e7be843bSPierre Pronchery SN_aes_256_ctr, 0); 80*e7be843bSPierre Pronchery *p = OSSL_PARAM_construct_end(); 81*e7be843bSPierre Pronchery EVP_RAND_instantiate(rctx, strength, 0, NULL, 0, params); 82*e7be843bSPierre Pronchery 83*e7be843bSPierre Pronchery EVP_RAND_generate(rctx, bytes, sizeof(bytes), strength, 0, NULL, 0); 84*e7be843bSPierre Pronchery 85*e7be843bSPierre Pronchery EVP_RAND_CTX_free(rctx); 86*e7be843bSPierre Pronchery EVP_RAND_CTX_free(seed); 87*e7be843bSPierre Pronchery 88*e7be843bSPierre Pronchery=head1 SEE ALSO 89*e7be843bSPierre Pronchery 90*e7be843bSPierre ProncheryL<EVP_RAND(3)>, 91*e7be843bSPierre ProncheryL<EVP_RAND(3)/PARAMETERS> 92*e7be843bSPierre Pronchery 93*e7be843bSPierre Pronchery=head1 COPYRIGHT 94*e7be843bSPierre Pronchery 95*e7be843bSPierre ProncheryCopyright 2024 The OpenSSL Project Authors. All Rights Reserved. 96*e7be843bSPierre Pronchery 97*e7be843bSPierre ProncheryLicensed under the Apache License 2.0 (the "License"). You may not use 98*e7be843bSPierre Proncherythis file except in compliance with the License. You can obtain a copy 99*e7be843bSPierre Proncheryin the file LICENSE in the source distribution or at 100*e7be843bSPierre ProncheryL<https://www.openssl.org/source/license.html>. 101*e7be843bSPierre Pronchery 102*e7be843bSPierre Pronchery=cut 103