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