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, EVP_RAND_set_callbacks,
   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_set_callbacks(EVP_RAND_CTX *ctx, OSSL_CALLBACK *get_entropy,
  61                             OSSL_CALLBACK *cleanup_entropy,
  62                             OSSL_CALLBACK *get_nonce,
  63                             OSSL_CALLBACK *cleanup_nonce, void *arg);
  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
  83 using calls to EVP_RAND_set_ctx_params() before
  84 calling EVP_RAND_instantiate() and then EVP_RAND_generate() to produce
  85 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
  93 =head2 Algorithm implementation fetching
  94
  95 EVP_RAND_fetch() fetches an implementation of a RAND I<algorithm>, given
  96 a library context I<libctx> and a set of I<properties>.
  97 See L<provider(7)/Fetching algorithms> for further information.
  98
  99 The returned value must eventually be freed with
 100 L<EVP_RAND_free(3)>.
 101
 102 EVP_RAND_up_ref() increments the reference count of an already fetched
 103 RAND.
 104
 105 EVP_RAND_free() frees a fetched algorithm.
 106 NULL is a valid parameter, for which this function is a no-op.
 107
 108 =head2 Context manipulation functions
 109
 110 EVP_RAND_CTX_new() creates a new context for the RAND implementation I<rand>.
 111 If not NULL, I<parent> specifies the seed source for this implementation.
 112 Not all random number generators need to have a seed source specified.
 113 If a parent is required, a NULL I<parent> will utilise the operating
 114 system entropy sources.
 115 It is recommended to minimise the number of random number generators that
 116 rely on the operating system for their randomness because this is often scarce.
 117
 118 EVP_RAND_CTX_free() frees up the context I<ctx>.  If I<ctx> is NULL, nothing
 119 is done.
 120
 121 EVP_RAND_CTX_rand() returns the B<EVP_RAND> associated with the context
 122 I<ctx>.
 123
 124 =head2 Random Number Generator Functions
 125
 126 EVP_RAND_instantiate() instantiates the RAND I<ctx> with a minimum security
 127 strength of <strength> and personalisation string I<pstr> of length <pstr_len>.
 128 If I<prediction_resistance> is specified, fresh entropy from a live source
 129 will be sought.  This call operates as per NIST SP 800-90A and SP 800-90C.
 130
 131 EVP_RAND_uninstantiate() uninstantiates the RAND I<ctx> as per
 132 NIST SP 800-90A and SP 800-90C.  Subsequent to this call, the RAND cannot
 133 be used to generate bytes.  It can only be freed or instantiated again.
 134
 135 EVP_RAND_generate() produces random bytes from the RAND I<ctx> with the
 136 additional input I<addin> of length I<addin_len>.  The bytes
 137 produced will meet the security I<strength>.
 138 If I<prediction_resistance> is specified, fresh entropy from a live source
 139 will be sought.  This call operates as per NIST SP 800-90A and SP 800-90C.
 140
 141 EVP_RAND_reseed() reseeds the RAND with new entropy.
 142 Entropy I<ent> of length I<ent_len> bytes can be supplied as can additional
 143 input I<addin> of length I<addin_len> bytes.  In the FIPS provider, both are
 144 treated as additional input as per NIST SP-800-90Ar1, Sections 9.1 and 9.2.
 145 Additional seed material is also drawn from the RAND's parent or the
 146 operating system.  If I<prediction_resistance> is specified, fresh entropy
 147 from a live source will be sought.  This call operates as per NIST SP 800-90A
 148 and SP 800-90C.
 149
 150 EVP_RAND_nonce() creates a nonce in I<out> of maximum length I<outlen>
 151 bytes from the RAND I<ctx>. The function returns the length of the generated
 152 nonce. If I<out> is NULL, the length is still returned but no generation
 153 takes place. This allows a caller to dynamically allocate a buffer of the
 154 appropriate size.
 155
 156 EVP_RAND_enable_locking() enables locking for the RAND I<ctx> and all of
 157 its parents.  After this I<ctx> will operate in a thread safe manner, albeit
 158 more slowly.
 159
 160 EVP_RAND_set_callbacks() sets callbacks on the RAND I<ctx> to accept
 161 external entropy and nonce input.  The callback I<get_entropy> fills a buffer
 162 with new randomness and the callback I<cleanup_entropy> clears and frees the
 163 buffer.  Likewise for I<get_nonce> and I<cleanup_nonce>.  In all cases the
 164 callbacks are passed I<arg> in addition to an OSSL_PARAM array.
 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_get_ctx_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_set_ctx_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(), EVP_RAND_gettable_ctx_params() and
 190 EVP_RAND_settable_ctx_params() get a constant B<OSSL_PARAM> array that
 191 describes the retrievable and settable parameters, i.e. parameters that
 192 can be used with EVP_RAND_get_params(), EVP_RAND_get_ctx_params()
 193 and EVP_RAND_set_ctx_params(), respectively.
 194 See L<OSSL_PARAM(3)> for the use of B<OSSL_PARAM> as parameter descriptor.
 195
 196 =head2 Information functions
 197
 198 EVP_RAND_strength() returns the security strength of the RAND I<ctx>.
 199
 200 EVP_RAND_state() returns the current state of the RAND I<ctx>.
 201 States defined by the OpenSSL DRBGs are:
 202
 203 =over 4
 204
 205 =item *
 206
 207 EVP_RAND_STATE_UNINITIALISED: this DRBG is currently uninitalised.
 208 The instantiate call will change this to the ready state.
 209
 210 =item *
 211
 212 EVP_RAND_STATE_READY: this DRBG is currently ready to generate output.
 213
 214 =item *
 215
 216 EVP_RAND_STATE_ERROR: this DRBG is in an error state.
 217
 218 =back
 219
 220 EVP_RAND_is_a() returns 1 if I<rand> is an implementation of an
 221 algorithm that's identifiable with I<name>, otherwise 0.
 222
 223 EVP_RAND_provider() returns the provider that holds the implementation
 224 of the given I<rand>.
 225
 226 EVP_RAND_do_all_provided() traverses all RAND implemented by all activated
 227 providers in the given library context I<libctx>, and for each of the
 228 implementations, calls the given function I<fn> with the implementation method
 229 and the given I<arg> as argument.
 230
 231 EVP_RAND_number() returns the internal dynamic number assigned to
 232 I<rand>.
 233
 234 EVP_RAND_name() returns the canonical name of I<rand>.
 235
 236 EVP_RAND_names_do_all() traverses all names for I<rand>, and calls
 237 I<fn> with each name and I<data>.
 238
 239 EVP_RAND_verify_zeroization() confirms if the internal DRBG state is
 240 currently zeroed.  This is used by the FIPS provider to support the mandatory
 241 self tests.
 242
 243 =head1 PARAMETERS
 244
 245 The standard parameter names are:
 246
 247 =over 4
 248
 249 =item "state" (B<OSSL_RAND_PARAM_STATE>) <integer>
 250
 251 Returns the state of the random number generator.
 252
 253 =item "strength" (B<OSSL_RAND_PARAM_STRENGTH>) <unsigned integer>
 254
 255 Returns the bit strength of the random number generator.
 256
 257 =back
 258
 259 For rands that are also deterministic random bit generators (DRBGs), these
 260 additional parameters are recognised. Not all
 261 parameters are relevant to, or are understood by all DRBG rands:
 262
 263 =over 4
 264
 265 =item "reseed_requests" (B<OSSL_DRBG_PARAM_RESEED_REQUESTS>) <unsigned integer>
 266
 267 Reads or set the number of generate requests before reseeding the
 268 associated RAND ctx.
 269
 270 =item "reseed_time_interval" (B<OSSL_DRBG_PARAM_RESEED_TIME_INTERVAL>) <integer>
 271
 272 Reads or set the number of elapsed seconds before reseeding the
 273 associated RAND ctx.
 274
 275 =item "max_request" (B<OSSL_DRBG_PARAM_RESEED_REQUESTS>) <unsigned integer>
 276
 277 Specifies the maximum number of bytes that can be generated in a single
 278 call to OSSL_FUNC_rand_generate.
 279
 280 =item "min_entropylen" (B<OSSL_DRBG_PARAM_MIN_ENTROPYLEN>) <unsigned integer>
 281
 282 =item "max_entropylen" (B<OSSL_DRBG_PARAM_MAX_ENTROPYLEN>) <unsigned integer>
 283
 284 Specify the minimum and maximum number of bytes of random material that
 285 can be used to seed the DRBG.
 286
 287 =item "min_noncelen" (B<OSSL_DRBG_PARAM_MIN_NONCELEN>) <unsigned integer>
 288
 289 =item "max_noncelen" (B<OSSL_DRBG_PARAM_MAX_NONCELEN>) <unsigned integer>
 290
 291 Specify the minimum and maximum number of bytes of nonce that can be used to
 292 seed the DRBG.
 293
 294 =item "max_perslen" (B<OSSL_DRBG_PARAM_MAX_PERSLEN>) <unsigned integer>
 295
 296 =item "max_adinlen" (B<OSSL_DRBG_PARAM_MAX_ADINLEN>) <unsigned integer>
 297
 298 Specify the minimum and maximum number of bytes of personalisation string
 299 that can be used with the DRBG.
 300
 301 =item "reseed_counter" (B<OSSL_DRBG_PARAM_RESEED_CTR>) <unsigned integer>
 302
 303 Specifies the number of times the DRBG has been seeded or reseeded.
 304
 305 =item "properties" (B<OSSL_RAND_PARAM_PROPERTIES>) <UTF8 string>
 306
 307 =item "mac" (B<OSSL_RAND_PARAM_MAC>) <UTF8 string>
 308
 309 =item "digest" (B<OSSL_RAND_PARAM_DIGEST>) <UTF8 string>
 310
 311 =item "cipher" (B<OSSL_RAND_PARAM_CIPHER>) <UTF8 string>
 312
 313 For RAND implementations that use an underlying computation MAC, digest or
 314 cipher, these parameters set what the algorithm should be.
 315
 316 The value is always the name of the intended algorithm,
 317 or the properties in the case of B<OSSL_RAND_PARAM_PROPERTIES>.
 318
 319 =back
 320
 321 =head1 RETURN VALUES
 322
 323 EVP_RAND_fetch() returns a pointer to a newly fetched B<EVP_RAND>, or
 324 NULL if allocation failed.
 325
 326 EVP_RAND_provider() returns a pointer to the provider for the RAND, or
 327 NULL on error.
 328
 329 EVP_RAND_CTX_rand() returns a pointer to the B<EVP_RAND> associated with the
 330 context.
 331
 332 EVP_RAND_name() returns the name of the random number generation algorithm.
 333
 334 EVP_RAND_number() returns the provider specific identification number
 335 for the specified algorithm.
 336
 337 EVP_RAND_up_ref() returns 1 on success, 0 on error.
 338
 339 EVP_RAND_CTX_new() returns either the newly allocated
 340 B<EVP_RAND_CTX> structure or NULL if an error occurred.
 341
 342 EVP_RAND_CTX_free() does not return a value.
 343
 344 EVP_RAND_nonce() returns the length of the nonce.
 345
 346 EVP_RAND_strength() returns the strenght of the random number generator in bits.
 347
 348 EVP_RAND_gettable_params(), EVP_RAND_gettable_ctx_params() and
 349 EVP_RAND_settable_ctx_params() return an array of OSSL_PARAMs.
 350
 351 EVP_RAND_verify_zeroization() returns 1 if the internal DRBG state is
 352 currently zeroed, and 0 if not.
 353
 354 The remaining functions return 1 for success and 0 or a negative value for
 355 failure.
 356
 357 =head1 SEE ALSO
 358
 359 L<RAND_bytes(3)>,
 360 L<EVP_RAND-CTR-DRBG(7)>,
 361 L<EVP_RAND-HASH-DRBG(7)>,
 362 L<EVP_RAND-HMAC-DRBG(7)>,
 363 L<EVP_RAND-TEST-RAND(7)>,
 364 L<provider-rand(7)>
 365
 366 =head1 HISTORY
 367
 368 This functionality was added to OpenSSL 3.0.
 369
 370 =head1 COPYRIGHT
 371
 372 Copyright 2020 The OpenSSL Project Authors. All Rights Reserved.
 373
 374 Licensed under the Apache License 2.0 (the "License").  You may not use
 375 this file except in compliance with the License.  You can obtain a copy
 376 in the file LICENSE in the source distribution or at
 377 L<https://www.openssl.org/source/license.html>.
 378
 379 =cut