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