doc/man3/EVP_RAND.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 EVP_RAND, EVP_RAND_fetch, EVP_RAND_free, EVP_RAND_up_ref, EVP_RAND_CTX,
   6 EVP_RAND_CTX_new, EVP_RAND_CTX_free, EVP_RAND_instantiate,
   7 EVP_RAND_uninstantiate, EVP_RAND_generate, EVP_RAND_reseed,
   8 EVP_RAND_nonce, EVP_RAND_enable_locking,
   9 EVP_RAND_verify_zeroization, EVP_RAND_strength, EVP_RAND_state,
  10 EVP_RAND_provider, EVP_RAND_CTX_rand, EVP_RAND_is_a, EVP_RAND_number,
  11 EVP_RAND_name, EVP_RAND_names_do_all, EVP_RAND_get_ctx_params,
  12 EVP_RAND_set_ctx_params, EVP_RAND_do_all_provided, EVP_RAND_get_params,
  13 EVP_RAND_gettable_ctx_params, EVP_RAND_settable_ctx_params,
  14 EVP_RAND_gettable_params, EVP_RAND_STATE_UNINITIALISED, EVP_RAND_STATE_READY,
  15 EVP_RAND_STATE_ERROR - EVP RAND routines
  16
  17 =head1 SYNOPSIS
  18
  19  #include <openssl/evp.h>
  20
  21  typedef struct evp_rand_st EVP_RAND;
  22  typedef struct evp_rand_ctx_st EVP_RAND_CTX;
  23
  24  EVP_RAND *EVP_RAND_fetch(OPENSSL_CTX *libctx, const char *algorithm,
  25                         const char *properties);
  26  int EVP_RAND_up_ref(EVP_RAND *rand);
  27  void EVP_RAND_free(EVP_RAND *rand);
  28  EVP_RAND_CTX *EVP_RAND_CTX_new(EVP_RAND *rand, EVP_RAND_CTX *parent);
  29  void EVP_RAND_CTX_free(EVP_RAND_CTX *ctx);
  30  EVP_RAND *EVP_RAND_CTX_rand(EVP_RAND_CTX *ctx);
  31  int EVP_RAND_get_params(EVP_RAND *rand, OSSL_PARAM params[]);
  32  int EVP_RAND_get_ctx_params(EVP_RAND_CTX *ctx, OSSL_PARAM params[]);
  33  int EVP_RAND_set_ctx_params(EVP_RAND_CTX *ctx, const OSSL_PARAM params[]);
  34  const OSSL_PARAM *EVP_RAND_gettable_params(const EVP_RAND *rand);
  35  const OSSL_PARAM *EVP_RAND_gettable_ctx_params(const EVP_RAND *rand);
  36  const OSSL_PARAM *EVP_RAND_settable_ctx_params(const EVP_RAND *rand);
  37  int EVP_RAND_number(const EVP_RAND *rand);
  38  const char *EVP_RAND_name(const EVP_RAND *rand);
  39  int EVP_RAND_is_a(const EVP_RAND *rand, const char *name);
  40  const OSSL_PROVIDER *EVP_RAND_provider(const EVP_RAND *rand);
  41  void EVP_RAND_do_all_provided(OPENSSL_CTX *libctx,
  42                                void (*fn)(EVP_RAND *rand, void *arg),
  43                                void *arg);
  44  void EVP_RAND_names_do_all(const EVP_RAND *rand,
  45                             void (*fn)(const char *name, void *data),
  46                             void *data);
  47
  48  int EVP_RAND_instantiate(EVP_RAND_CTX *ctx, unsigned int strength,
  49                           int prediction_resistance,
  50                           const unsigned char *pstr, size_t pstr_len);
  51  int EVP_RAND_uninstantiate(EVP_RAND_CTX *ctx);
  52  int EVP_RAND_generate(EVP_RAND_CTX *ctx, unsigned char *out, size_t outlen,
  53                        unsigned int strength, int prediction_resistance,
  54                        const unsigned char *addin, size_t addin_len);
  55  int EVP_RAND_reseed(EVP_RAND_CTX *ctx, int prediction_resistance,
  56                      const unsigned char *ent, size_t ent_len,
  57                      const unsigned char *addin, size_t addin_len);
  58  int EVP_RAND_nonce(EVP_RAND_CTX *ctx, unsigned char *out, size_t outlen);
  59  int EVP_RAND_enable_locking(EVP_RAND_CTX *ctx);
  60  int EVP_RAND_verify_zeroization(EVP_RAND_CTX *ctx);
  61  unsigned int EVP_RAND_strength(EVP_RAND_CTX *ctx);
  62  int EVP_RAND_state(EVP_RAND_CTX *ctx);
  63
  64  #define EVP_RAND_STATE_UNINITIALISED    0
  65  #define EVP_RAND_STATE_READY            1
  66  #define EVP_RAND_STATE_ERROR            2
  67
  68 =head1 DESCRIPTION
  69
  70 The EVP RAND routines are a high-level interface to random number generators
  71 both deterministic and not.
  72 If you just want to generate random bytes then you don't need to use
  73 these functions: just call RAND_bytes() or RAND_priv_bytes().
  74 If you want to do more, these calls should be used instead of the older
  75 RAND and RAND_DRBG functions.
  76
  77 After creating a B<EVP_RAND_CTX> for the required algorithm using
  78 EVP_RAND_CTX_new(), inputs to the algorithm are supplied
  79 using calls to EVP_RAND_set_ctx_params() before
  80 calling EVP_RAND_instantiate() and then EVP_RAND_generate() to produce
  81 cryptographically secure random bytes.
  82
  83 =head2 Types
  84
  85 B<EVP_RAND> is a type that holds the implementation of a RAND.
  86
  87 B<EVP_RAND_CTX> is a context type that holds the algorithm inputs.
  88 B<EVP_RAND_CTX> structures are reference counted.
  89
  90 =head2 Algorithm implementation fetching
  91
  92 EVP_RAND_fetch() fetches an implementation of a RAND I<algorithm>, given
  93 a library context I<libctx> and a set of I<properties>.
  94 See L<provider(7)/Fetching algorithms> for further information.
  95
  96 The returned value must eventually be freed with
  97 L<EVP_RAND_free(3)>.
  98
  99 EVP_RAND_up_ref() increments the reference count of an already fetched
 100 RAND.
 101
 102 EVP_RAND_free() frees a fetched algorithm.
 103 NULL is a valid parameter, for which this function is a no-op.
 104
 105 =head2 Context manipulation functions
 106
 107 EVP_RAND_CTX_new() creates a new context for the RAND implementation I<rand>.
 108 If not NULL, I<parent> specifies the seed source for this implementation.
 109 Not all random number generators need to have a seed source specified.
 110 If a parent is required, a NULL I<parent> will utilise the operating
 111 system entropy sources.
 112 It is recommended to minimise the number of random number generators that
 113 rely on the operating system for their randomness because this is often scarce.
 114
 115 EVP_RAND_CTX_free() frees up the context I<ctx>.  If I<ctx> is NULL, nothing
 116 is done.
 117
 118 EVP_RAND_CTX_rand() returns the B<EVP_RAND> associated with the context
 119 I<ctx>.
 120
 121 =head2 Random Number Generator Functions
 122
 123 EVP_RAND_instantiate() instantiates the RAND I<ctx> with a minimum security
 124 strength of <strength> and personalisation string I<pstr> of length <pstr_len>.
 125 If I<prediction_resistance> is specified, fresh entropy from a live source
 126 will be sought.  This call operates as per NIST SP 800-90A and SP 800-90C.
 127
 128 EVP_RAND_uninstantiate() uninstantiates the RAND I<ctx> as per
 129 NIST SP 800-90A and SP 800-90C.  Subsequent to this call, the RAND cannot
 130 be used to generate bytes.  It can only be freed or instantiated again.
 131
 132 EVP_RAND_generate() produces random bytes from the RAND I<ctx> with the
 133 additional input I<addin> of length I<addin_len>.  The bytes
 134 produced will meet the security I<strength>.
 135 If I<prediction_resistance> is specified, fresh entropy from a live source
 136 will be sought.  This call operates as per NIST SP 800-90A and SP 800-90C.
 137
 138 EVP_RAND_reseed() reseeds the RAND with new entropy.
 139 Entropy I<ent> of length I<ent_len> bytes can be supplied as can additional
 140 input I<addin> of length I<addin_len> bytes.  In the FIPS provider, both are
 141 treated as additional input as per NIST SP-800-90Ar1, Sections 9.1 and 9.2.
 142 Additional seed material is also drawn from the RAND's parent or the
 143 operating system.  If I<prediction_resistance> is specified, fresh entropy
 144 from a live source will be sought.  This call operates as per NIST SP 800-90A
 145 and SP 800-90C.
 146
 147 EVP_RAND_nonce() creates a nonce in I<out> of maximum length I<outlen>
 148 bytes from the RAND I<ctx>. The function returns the length of the generated
 149 nonce. If I<out> is NULL, the length is still returned but no generation
 150 takes place. This allows a caller to dynamically allocate a buffer of the
 151 appropriate size.
 152
 153 EVP_RAND_enable_locking() enables locking for the RAND I<ctx> and all of
 154 its parents.  After this I<ctx> will operate in a thread safe manner, albeit
 155 more slowly.
 156
 157 EVP_RAND_get_params() retrieves details about the implementation
 158 I<rand>.
 159 The set of parameters given with I<params> determine exactly what
 160 parameters should be retrieved.
 161 Note that a parameter that is unknown in the underlying context is
 162 simply ignored.
 163
 164 EVP_RAND_get_ctx_params() retrieves chosen parameters, given the
 165 context I<ctx> and its underlying context.
 166 The set of parameters given with I<params> determine exactly what
 167 parameters should be retrieved.
 168 Note that a parameter that is unknown in the underlying context is
 169 simply ignored.
 170
 171 EVP_RAND_set_ctx_params() passes chosen parameters to the underlying
 172 context, given a context I<ctx>.
 173 The set of parameters given with I<params> determine exactly what
 174 parameters are passed down.
 175 Note that a parameter that is unknown in the underlying context is
 176 simply ignored.
 177 Also, what happens when a needed parameter isn't passed down is
 178 defined by the implementation.
 179
 180 EVP_RAND_gettable_params(), EVP_RAND_gettable_ctx_params() and
 181 EVP_RAND_settable_ctx_params() get a constant B<OSSL_PARAM> array that
 182 describes the retrievable and settable parameters, i.e. parameters that
 183 can be used with EVP_RAND_get_params(), EVP_RAND_get_ctx_params()
 184 and EVP_RAND_set_ctx_params(), respectively.
 185 See L<OSSL_PARAM(3)> for the use of B<OSSL_PARAM> as parameter descriptor.
 186
 187 =head2 Information functions
 188
 189 EVP_RAND_strength() returns the security strength of the RAND I<ctx>.
 190
 191 EVP_RAND_state() returns the current state of the RAND I<ctx>.
 192 States defined by the OpenSSL RNGs are:
 193
 194 =over 4
 195
 196 =item *
 197
 198 EVP_RAND_STATE_UNINITIALISED: this RNG is currently uninitialised.
 199 The instantiate call will change this to the ready state.
 200
 201 =item *
 202
 203 EVP_RAND_STATE_READY: this RNG is currently ready to generate output.
 204
 205 =item *
 206
 207 EVP_RAND_STATE_ERROR: this RNG is in an error state.
 208
 209 =back
 210
 211 EVP_RAND_is_a() returns 1 if I<rand> is an implementation of an
 212 algorithm that's identifiable with I<name>, otherwise 0.
 213
 214 EVP_RAND_provider() returns the provider that holds the implementation
 215 of the given I<rand>.
 216
 217 EVP_RAND_do_all_provided() traverses all RAND implemented by all activated
 218 providers in the given library context I<libctx>, and for each of the
 219 implementations, calls the given function I<fn> with the implementation method
 220 and the given I<arg> as argument.
 221
 222 EVP_RAND_number() returns the internal dynamic number assigned to
 223 I<rand>.
 224
 225 EVP_RAND_name() returns the canonical name of I<rand>.
 226
 227 EVP_RAND_names_do_all() traverses all names for I<rand>, and calls
 228 I<fn> with each name and I<data>.
 229
 230 EVP_RAND_verify_zeroization() confirms if the internal DRBG state is
 231 currently zeroed.  This is used by the FIPS provider to support the mandatory
 232 self tests.
 233
 234 =head1 PARAMETERS
 235
 236 The standard parameter names are:
 237
 238 =over 4
 239
 240 =item "state" (B<OSSL_RAND_PARAM_STATE>) <integer>
 241
 242 Returns the state of the random number generator.
 243
 244 =item "strength" (B<OSSL_RAND_PARAM_STRENGTH>) <unsigned integer>
 245
 246 Returns the bit strength of the random number generator.
 247
 248 =back
 249
 250 For rands that are also deterministic random bit generators (DRBGs), these
 251 additional parameters are recognised. Not all
 252 parameters are relevant to, or are understood by all DRBG rands:
 253
 254 =over 4
 255
 256 =item "reseed_requests" (B<OSSL_DRBG_PARAM_RESEED_REQUESTS>) <unsigned integer>
 257
 258 Reads or set the number of generate requests before reseeding the
 259 associated RAND ctx.
 260
 261 =item "reseed_time_interval" (B<OSSL_DRBG_PARAM_RESEED_TIME_INTERVAL>) <integer>
 262
 263 Reads or set the number of elapsed seconds before reseeding the
 264 associated RAND ctx.
 265
 266 =item "max_request" (B<OSSL_DRBG_PARAM_RESEED_REQUESTS>) <unsigned integer>
 267
 268 Specifies the maximum number of bytes that can be generated in a single
 269 call to OSSL_FUNC_rand_generate.
 270
 271 =item "min_entropylen" (B<OSSL_DRBG_PARAM_MIN_ENTROPYLEN>) <unsigned integer>
 272
 273 =item "max_entropylen" (B<OSSL_DRBG_PARAM_MAX_ENTROPYLEN>) <unsigned integer>
 274
 275 Specify the minimum and maximum number of bytes of random material that
 276 can be used to seed the DRBG.
 277
 278 =item "min_noncelen" (B<OSSL_DRBG_PARAM_MIN_NONCELEN>) <unsigned integer>
 279
 280 =item "max_noncelen" (B<OSSL_DRBG_PARAM_MAX_NONCELEN>) <unsigned integer>
 281
 282 Specify the minimum and maximum number of bytes of nonce that can be used to
 283 seed the DRBG.
 284
 285 =item "max_perslen" (B<OSSL_DRBG_PARAM_MAX_PERSLEN>) <unsigned integer>
 286
 287 =item "max_adinlen" (B<OSSL_DRBG_PARAM_MAX_ADINLEN>) <unsigned integer>
 288
 289 Specify the minimum and maximum number of bytes of personalisation string
 290 that can be used with the DRBG.
 291
 292 =item "reseed_counter" (B<OSSL_DRBG_PARAM_RESEED_COUNTER>) <unsigned integer>
 293
 294 Specifies the number of times the DRBG has been seeded or reseeded.
 295
 296 =item "properties" (B<OSSL_RAND_PARAM_PROPERTIES>) <UTF8 string>
 297
 298 =item "mac" (B<OSSL_RAND_PARAM_MAC>) <UTF8 string>
 299
 300 =item "digest" (B<OSSL_RAND_PARAM_DIGEST>) <UTF8 string>
 301
 302 =item "cipher" (B<OSSL_RAND_PARAM_CIPHER>) <UTF8 string>
 303
 304 For RAND implementations that use an underlying computation MAC, digest or
 305 cipher, these parameters set what the algorithm should be.
 306
 307 The value is always the name of the intended algorithm,
 308 or the properties in the case of B<OSSL_RAND_PARAM_PROPERTIES>.
 309
 310 =back
 311
 312 =head1 RETURN VALUES
 313
 314 EVP_RAND_fetch() returns a pointer to a newly fetched B<EVP_RAND>, or
 315 NULL if allocation failed.
 316
 317 EVP_RAND_provider() returns a pointer to the provider for the RAND, or
 318 NULL on error.
 319
 320 EVP_RAND_CTX_rand() returns a pointer to the B<EVP_RAND> associated with the
 321 context.
 322
 323 EVP_RAND_name() returns the name of the random number generation algorithm.
 324
 325 EVP_RAND_number() returns the provider specific identification number
 326 for the specified algorithm.
 327
 328 EVP_RAND_up_ref() returns 1 on success, 0 on error.
 329
 330 EVP_RAND_CTX_new() returns either the newly allocated
 331 B<EVP_RAND_CTX> structure or NULL if an error occurred.
 332
 333 EVP_RAND_CTX_free() does not return a value.
 334
 335 EVP_RAND_nonce() returns the length of the nonce.
 336
 337 EVP_RAND_strength() returns the strength of the random number generator in bits.
 338
 339 EVP_RAND_gettable_params(), EVP_RAND_gettable_ctx_params() and
 340 EVP_RAND_settable_ctx_params() return an array of OSSL_PARAMs.
 341
 342 EVP_RAND_verify_zeroization() returns 1 if the internal DRBG state is
 343 currently zeroed, and 0 if not.
 344
 345 The remaining functions return 1 for success and 0 or a negative value for
 346 failure.
 347
 348 =head1 SEE ALSO
 349
 350 L<RAND_bytes(3)>,
 351 L<EVP_RAND-CTR-DRBG(7)>,
 352 L<EVP_RAND-HASH-DRBG(7)>,
 353 L<EVP_RAND-HMAC-DRBG(7)>,
 354 L<EVP_RAND-TEST-RAND(7)>,
 355 L<provider-rand(7)>
 356
 357 =head1 HISTORY
 358
 359 This functionality was added to OpenSSL 3.0.
 360
 361 =head1 COPYRIGHT
 362
 363 Copyright 2020 The OpenSSL Project Authors. All Rights Reserved.
 364
 365 Licensed under the Apache License 2.0 (the "License").  You may not use
 366 this file except in compliance with the License.  You can obtain a copy
 367 in the file LICENSE in the source distribution or at
 368 L<https://www.openssl.org/source/license.html>.
 369
 370 =cut