doc/man7/EVP_RAND-SEED-SRC.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 EVP_RAND-SEED-SRC - The randomness seed source EVP_RAND implementation
   6
   7 =head1 DESCRIPTION
   8
   9 Support for deterministic random number generator seeding through the
  10 B<EVP_RAND> API.
  11
  12 The seed sources used are specified at the time OpenSSL is configured for
  13 building using the B<--with-rand-seed=> option.  By default, operating system
  14 randomness sources are used.
  15
  16 =head2 Identity
  17
  18 "SEED-SRC" is the name for this implementation; it can be used with the
  19 EVP_RAND_fetch() function.
  20
  21 =head2 Supported parameters
  22
  23 The supported parameters are:
  24
  25 =over 4
  26
  27 =item "state" (B<OSSL_RAND_PARAM_STATE>) <integer>
  28
  29 =item "strength" (B<OSSL_RAND_PARAM_STRENGTH>) <unsigned integer>
  30
  31 =item "max_request" (B<OSSL_RAND_PARAM_MAX_REQUEST>) <unsigned integer>
  32
  33 These parameters work as described in L<EVP_RAND(3)/PARAMETERS>.
  34
  35 =back
  36
  37 =head1 NOTES
  38
  39 A context for the seed source can be obtained by calling:
  40
  41  EVP_RAND *rand = EVP_RAND_fetch(NULL, "SEED-SRC", NULL);
  42  EVP_RAND_CTX *rctx = EVP_RAND_CTX_new(rand);
  43
  44 =head1 EXAMPLES
  45
  46  EVP_RAND *rand;
  47  EVP_RAND_CTX *seed, *rctx;
  48  unsigned char bytes[100];
  49  OSSL_PARAM params[2], *p = params;
  50  unsigned int strength = 128;
  51
  52  /* Create a seed source */
  53  rand = EVP_RAND_fetch(NULL, "SEED-SRC", NULL);
  54  seed = EVP_RAND_CTX_new(rand, NULL);
  55  EVP_RAND_free(rand);
  56
  57  /* Feed this into a DRBG */
  58  rand = EVP_RAND_fetch(NULL, "CTR-DRBG", NULL);
  59  rctx = EVP_RAND_CTX_new(rand, seed);
  60  EVP_RAND_free(rand);
  61
  62  /* Configure the DRBG */
  63  *p++ = OSSL_PARAM_construct_utf8_string(OSSL_DRBG_PARAM_CIPHER,
  64                                          SN_aes_256_ctr, 0);
  65  *p = OSSL_PARAM_construct_end();
  66  EVP_RAND_instantiate(rctx, strength, 0, NULL, 0, params);
  67
  68  EVP_RAND_generate(rctx, bytes, sizeof(bytes), strength, 0, NULL, 0);
  69
  70  EVP_RAND_CTX_free(rctx);
  71  EVP_RAND_CTX_free(seed);
  72
  73 =head1 SEE ALSO
  74
  75 L<EVP_RAND(3)>,
  76 L<EVP_RAND(3)/PARAMETERS>
  77
  78 =head1 COPYRIGHT
  79
  80 Copyright 2020 The OpenSSL Project Authors. All Rights Reserved.
  81
  82 Licensed under the Apache License 2.0 (the "License").  You may not use
  83 this file except in compliance with the License.  You can obtain a copy
  84 in the file LICENSE in the source distribution or at
  85 L<https://www.openssl.org/source/license.html>.
  86
  87 =cut