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