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(OSSL_LIB_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(OSSL_LIB_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. This function is not itself thread safe if called with the same
 156 I<ctx> from multiple threads. Typically locking should be enabled before a
 157 I<ctx> is shared across multiple threads.
 158
 159 EVP_RAND_get_params() retrieves details about the implementation
 160 I<rand>.
 161 The set of parameters given with I<params> determine exactly what
 162 parameters should be retrieved.
 163 Note that a parameter that is unknown in the underlying context is
 164 simply ignored.
 165
 166 EVP_RAND_get_ctx_params() retrieves chosen parameters, given the
 167 context I<ctx> and its underlying context.
 168 The set of parameters given with I<params> determine exactly what
 169 parameters should be retrieved.
 170 Note that a parameter that is unknown in the underlying context is
 171 simply ignored.
 172
 173 EVP_RAND_set_ctx_params() passes chosen parameters to the underlying
 174 context, given a context I<ctx>.
 175 The set of parameters given with I<params> determine exactly what
 176 parameters are passed down.
 177 Note that a parameter that is unknown in the underlying context is
 178 simply ignored.
 179 Also, what happens when a needed parameter isn't passed down is
 180 defined by the implementation.
 181
 182 EVP_RAND_gettable_params(), EVP_RAND_gettable_ctx_params() and
 183 EVP_RAND_settable_ctx_params() get a constant B<OSSL_PARAM> array that
 184 describes the retrievable and settable parameters, i.e. parameters that
 185 can be used with EVP_RAND_get_params(), EVP_RAND_get_ctx_params()
 186 and EVP_RAND_set_ctx_params(), respectively.
 187 See L<OSSL_PARAM(3)> for the use of B<OSSL_PARAM> as parameter descriptor.
 188
 189 =head2 Information functions
 190
 191 EVP_RAND_strength() returns the security strength of the RAND I<ctx>.
 192
 193 EVP_RAND_state() returns the current state of the RAND I<ctx>.
 194 States defined by the OpenSSL RNGs are:
 195
 196 =over 4
 197
 198 =item *
 199
 200 EVP_RAND_STATE_UNINITIALISED: this RNG is currently uninitialised.
 201 The instantiate call will change this to the ready state.
 202
 203 =item *
 204
 205 EVP_RAND_STATE_READY: this RNG is currently ready to generate output.
 206
 207 =item *
 208
 209 EVP_RAND_STATE_ERROR: this RNG is in an error state.
 210
 211 =back
 212
 213 EVP_RAND_is_a() returns 1 if I<rand> is an implementation of an
 214 algorithm that's identifiable with I<name>, otherwise 0.
 215
 216 EVP_RAND_provider() returns the provider that holds the implementation
 217 of the given I<rand>.
 218
 219 EVP_RAND_do_all_provided() traverses all RAND implemented by all activated
 220 providers in the given library context I<libctx>, and for each of the
 221 implementations, calls the given function I<fn> with the implementation method
 222 and the given I<arg> as argument.
 223
 224 EVP_RAND_number() returns the internal dynamic number assigned to
 225 I<rand>.
 226
 227 EVP_RAND_name() returns the canonical name of I<rand>.
 228
 229 EVP_RAND_names_do_all() traverses all names for I<rand>, and calls
 230 I<fn> with each name and I<data>.
 231
 232 EVP_RAND_verify_zeroization() confirms if the internal DRBG state is
 233 currently zeroed.  This is used by the FIPS provider to support the mandatory
 234 self tests.
 235
 236 =head1 PARAMETERS
 237
 238 The standard parameter names are:
 239
 240 =over 4
 241
 242 =item "state" (B<OSSL_RAND_PARAM_STATE>) <integer>
 243
 244 Returns the state of the random number generator.
 245
 246 =item "strength" (B<OSSL_RAND_PARAM_STRENGTH>) <unsigned integer>
 247
 248 Returns the bit strength of the random number generator.
 249
 250 =back
 251
 252 For rands that are also deterministic random bit generators (DRBGs), these
 253 additional parameters are recognised. Not all
 254 parameters are relevant to, or are understood by all DRBG rands:
 255
 256 =over 4
 257
 258 =item "reseed_requests" (B<OSSL_DRBG_PARAM_RESEED_REQUESTS>) <unsigned integer>
 259
 260 Reads or set the number of generate requests before reseeding the
 261 associated RAND ctx.
 262
 263 =item "reseed_time_interval" (B<OSSL_DRBG_PARAM_RESEED_TIME_INTERVAL>) <integer>
 264
 265 Reads or set the number of elapsed seconds before reseeding the
 266 associated RAND ctx.
 267
 268 =item "max_request" (B<OSSL_DRBG_PARAM_RESEED_REQUESTS>) <unsigned integer>
 269
 270 Specifies the maximum number of bytes that can be generated in a single
 271 call to OSSL_FUNC_rand_generate.
 272
 273 =item "min_entropylen" (B<OSSL_DRBG_PARAM_MIN_ENTROPYLEN>) <unsigned integer>
 274
 275 =item "max_entropylen" (B<OSSL_DRBG_PARAM_MAX_ENTROPYLEN>) <unsigned integer>
 276
 277 Specify the minimum and maximum number of bytes of random material that
 278 can be used to seed the DRBG.
 279
 280 =item "min_noncelen" (B<OSSL_DRBG_PARAM_MIN_NONCELEN>) <unsigned integer>
 281
 282 =item "max_noncelen" (B<OSSL_DRBG_PARAM_MAX_NONCELEN>) <unsigned integer>
 283
 284 Specify the minimum and maximum number of bytes of nonce that can be used to
 285 seed the DRBG.
 286
 287 =item "max_perslen" (B<OSSL_DRBG_PARAM_MAX_PERSLEN>) <unsigned integer>
 288
 289 =item "max_adinlen" (B<OSSL_DRBG_PARAM_MAX_ADINLEN>) <unsigned integer>
 290
 291 Specify the minimum and maximum number of bytes of personalisation string
 292 that can be used with the DRBG.
 293
 294 =item "reseed_counter" (B<OSSL_DRBG_PARAM_RESEED_COUNTER>) <unsigned integer>
 295
 296 Specifies the number of times the DRBG has been seeded or reseeded.
 297
 298 =item "properties" (B<OSSL_RAND_PARAM_PROPERTIES>) <UTF8 string>
 299
 300 =item "mac" (B<OSSL_RAND_PARAM_MAC>) <UTF8 string>
 301
 302 =item "digest" (B<OSSL_RAND_PARAM_DIGEST>) <UTF8 string>
 303
 304 =item "cipher" (B<OSSL_RAND_PARAM_CIPHER>) <UTF8 string>
 305
 306 For RAND implementations that use an underlying computation MAC, digest or
 307 cipher, these parameters set what the algorithm should be.
 308
 309 The value is always the name of the intended algorithm,
 310 or the properties in the case of B<OSSL_RAND_PARAM_PROPERTIES>.
 311
 312 =back
 313
 314 =head1 NOTES
 315
 316 An B<EVP_RAND_CTX> needs to have locking enabled if it acts as the parent of
 317 more than one child and the children can be accessed concurrently.  This must
 318 be done by explicitly calling EVP_RAND_enable_locking().
 319
 320 =head1 RETURN VALUES
 321
 322 EVP_RAND_fetch() returns a pointer to a newly fetched B<EVP_RAND>, or
 323 NULL if allocation failed.
 324
 325 EVP_RAND_provider() returns a pointer to the provider for the RAND, or
 326 NULL on error.
 327
 328 EVP_RAND_CTX_rand() returns a pointer to the B<EVP_RAND> associated with the
 329 context.
 330
 331 EVP_RAND_name() returns the name of the random number generation algorithm.
 332
 333 EVP_RAND_number() returns the provider specific identification number
 334 for the specified algorithm.
 335
 336 EVP_RAND_up_ref() returns 1 on success, 0 on error.
 337
 338 EVP_RAND_CTX_new() returns either the newly allocated
 339 B<EVP_RAND_CTX> structure or NULL if an error occurred.
 340
 341 EVP_RAND_CTX_free() does not return a value.
 342
 343 EVP_RAND_nonce() returns the length of the nonce.
 344
 345 EVP_RAND_strength() returns the strength of the random number generator in bits.
 346
 347 EVP_RAND_gettable_params(), EVP_RAND_gettable_ctx_params() and
 348 EVP_RAND_settable_ctx_params() return an array of OSSL_PARAMs.
 349
 350 EVP_RAND_verify_zeroization() returns 1 if the internal DRBG state is
 351 currently zeroed, and 0 if not.
 352
 353 The remaining functions return 1 for success and 0 or a negative value for
 354 failure.
 355
 356 =head1 SEE ALSO
 357
 358 L<RAND_bytes(3)>,
 359 L<EVP_RAND-CTR-DRBG(7)>,
 360 L<EVP_RAND-HASH-DRBG(7)>,
 361 L<EVP_RAND-HMAC-DRBG(7)>,
 362 L<EVP_RAND-TEST-RAND(7)>,
 363 L<provider-rand(7)>
 364
 365 =head1 HISTORY
 366
 367 This functionality was added to OpenSSL 3.0.
 368
 369 =head1 COPYRIGHT
 370
 371 Copyright 2020-2021 The OpenSSL Project Authors. All Rights Reserved.
 372
 373 Licensed under the Apache License 2.0 (the "License").  You may not use
 374 this file except in compliance with the License.  You can obtain a copy
 375 in the file LICENSE in the source distribution or at
 376 L<https://www.openssl.org/source/license.html>.
 377
 378 =cut