EVP_RAND.pod 14 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370
  1. =pod
  2. =head1 NAME
  3. EVP_RAND, EVP_RAND_fetch, EVP_RAND_free, EVP_RAND_up_ref, EVP_RAND_CTX,
  4. EVP_RAND_CTX_new, EVP_RAND_CTX_free, EVP_RAND_instantiate,
  5. EVP_RAND_uninstantiate, EVP_RAND_generate, EVP_RAND_reseed,
  6. EVP_RAND_nonce, EVP_RAND_enable_locking,
  7. EVP_RAND_verify_zeroization, EVP_RAND_strength, EVP_RAND_state,
  8. EVP_RAND_provider, EVP_RAND_CTX_rand, EVP_RAND_is_a, EVP_RAND_number,
  9. EVP_RAND_name, EVP_RAND_names_do_all, EVP_RAND_get_ctx_params,
  10. EVP_RAND_set_ctx_params, EVP_RAND_do_all_provided, EVP_RAND_get_params,
  11. EVP_RAND_gettable_ctx_params, EVP_RAND_settable_ctx_params,
  12. EVP_RAND_gettable_params, EVP_RAND_STATE_UNINITIALISED, EVP_RAND_STATE_READY,
  13. EVP_RAND_STATE_ERROR - EVP RAND routines
  14. =head1 SYNOPSIS
  15. #include <openssl/evp.h>
  16. typedef struct evp_rand_st EVP_RAND;
  17. typedef struct evp_rand_ctx_st EVP_RAND_CTX;
  18. EVP_RAND *EVP_RAND_fetch(OPENSSL_CTX *libctx, const char *algorithm,
  19. const char *properties);
  20. int EVP_RAND_up_ref(EVP_RAND *rand);
  21. void EVP_RAND_free(EVP_RAND *rand);
  22. EVP_RAND_CTX *EVP_RAND_CTX_new(EVP_RAND *rand, EVP_RAND_CTX *parent);
  23. void EVP_RAND_CTX_free(EVP_RAND_CTX *ctx);
  24. EVP_RAND *EVP_RAND_CTX_rand(EVP_RAND_CTX *ctx);
  25. int EVP_RAND_get_params(EVP_RAND *rand, OSSL_PARAM params[]);
  26. int EVP_RAND_get_ctx_params(EVP_RAND_CTX *ctx, OSSL_PARAM params[]);
  27. int EVP_RAND_set_ctx_params(EVP_RAND_CTX *ctx, const OSSL_PARAM params[]);
  28. const OSSL_PARAM *EVP_RAND_gettable_params(const EVP_RAND *rand);
  29. const OSSL_PARAM *EVP_RAND_gettable_ctx_params(const EVP_RAND *rand);
  30. const OSSL_PARAM *EVP_RAND_settable_ctx_params(const EVP_RAND *rand);
  31. int EVP_RAND_number(const EVP_RAND *rand);
  32. const char *EVP_RAND_name(const EVP_RAND *rand);
  33. int EVP_RAND_is_a(const EVP_RAND *rand, const char *name);
  34. const OSSL_PROVIDER *EVP_RAND_provider(const EVP_RAND *rand);
  35. void EVP_RAND_do_all_provided(OPENSSL_CTX *libctx,
  36. void (*fn)(EVP_RAND *rand, void *arg),
  37. void *arg);
  38. void EVP_RAND_names_do_all(const EVP_RAND *rand,
  39. void (*fn)(const char *name, void *data),
  40. void *data);
  41. int EVP_RAND_instantiate(EVP_RAND_CTX *ctx, unsigned int strength,
  42. int prediction_resistance,
  43. const unsigned char *pstr, size_t pstr_len);
  44. int EVP_RAND_uninstantiate(EVP_RAND_CTX *ctx);
  45. int EVP_RAND_generate(EVP_RAND_CTX *ctx, unsigned char *out, size_t outlen,
  46. unsigned int strength, int prediction_resistance,
  47. const unsigned char *addin, size_t addin_len);
  48. int EVP_RAND_reseed(EVP_RAND_CTX *ctx, int prediction_resistance,
  49. const unsigned char *ent, size_t ent_len,
  50. const unsigned char *addin, size_t addin_len);
  51. int EVP_RAND_nonce(EVP_RAND_CTX *ctx, unsigned char *out, size_t outlen);
  52. int EVP_RAND_enable_locking(EVP_RAND_CTX *ctx);
  53. int EVP_RAND_verify_zeroization(EVP_RAND_CTX *ctx);
  54. unsigned int EVP_RAND_strength(EVP_RAND_CTX *ctx);
  55. int EVP_RAND_state(EVP_RAND_CTX *ctx);
  56. #define EVP_RAND_STATE_UNINITIALISED 0
  57. #define EVP_RAND_STATE_READY 1
  58. #define EVP_RAND_STATE_ERROR 2
  59. =head1 DESCRIPTION
  60. The EVP RAND routines are a high-level interface to random number generators
  61. both deterministic and not.
  62. If you just want to generate random bytes then you don't need to use
  63. these functions: just call RAND_bytes() or RAND_priv_bytes().
  64. If you want to do more, these calls should be used instead of the older
  65. RAND and RAND_DRBG functions.
  66. After creating a B<EVP_RAND_CTX> for the required algorithm using
  67. EVP_RAND_CTX_new(), inputs to the algorithm are supplied
  68. using calls to EVP_RAND_set_ctx_params() before
  69. calling EVP_RAND_instantiate() and then EVP_RAND_generate() to produce
  70. cryptographically secure random bytes.
  71. =head2 Types
  72. B<EVP_RAND> is a type that holds the implementation of a RAND.
  73. B<EVP_RAND_CTX> is a context type that holds the algorithm inputs.
  74. B<EVP_RAND_CTX> structures are reference counted.
  75. =head2 Algorithm implementation fetching
  76. EVP_RAND_fetch() fetches an implementation of a RAND I<algorithm>, given
  77. a library context I<libctx> and a set of I<properties>.
  78. See L<provider(7)/Fetching algorithms> for further information.
  79. The returned value must eventually be freed with
  80. L<EVP_RAND_free(3)>.
  81. EVP_RAND_up_ref() increments the reference count of an already fetched
  82. RAND.
  83. EVP_RAND_free() frees a fetched algorithm.
  84. NULL is a valid parameter, for which this function is a no-op.
  85. =head2 Context manipulation functions
  86. EVP_RAND_CTX_new() creates a new context for the RAND implementation I<rand>.
  87. If not NULL, I<parent> specifies the seed source for this implementation.
  88. Not all random number generators need to have a seed source specified.
  89. If a parent is required, a NULL I<parent> will utilise the operating
  90. system entropy sources.
  91. It is recommended to minimise the number of random number generators that
  92. rely on the operating system for their randomness because this is often scarce.
  93. EVP_RAND_CTX_free() frees up the context I<ctx>. If I<ctx> is NULL, nothing
  94. is done.
  95. EVP_RAND_CTX_rand() returns the B<EVP_RAND> associated with the context
  96. I<ctx>.
  97. =head2 Random Number Generator Functions
  98. EVP_RAND_instantiate() instantiates the RAND I<ctx> with a minimum security
  99. strength of <strength> and personalisation string I<pstr> of length <pstr_len>.
  100. If I<prediction_resistance> is specified, fresh entropy from a live source
  101. will be sought. This call operates as per NIST SP 800-90A and SP 800-90C.
  102. EVP_RAND_uninstantiate() uninstantiates the RAND I<ctx> as per
  103. NIST SP 800-90A and SP 800-90C. Subsequent to this call, the RAND cannot
  104. be used to generate bytes. It can only be freed or instantiated again.
  105. EVP_RAND_generate() produces random bytes from the RAND I<ctx> with the
  106. additional input I<addin> of length I<addin_len>. The bytes
  107. produced will meet the security I<strength>.
  108. If I<prediction_resistance> is specified, fresh entropy from a live source
  109. will be sought. This call operates as per NIST SP 800-90A and SP 800-90C.
  110. EVP_RAND_reseed() reseeds the RAND with new entropy.
  111. Entropy I<ent> of length I<ent_len> bytes can be supplied as can additional
  112. input I<addin> of length I<addin_len> bytes. In the FIPS provider, both are
  113. treated as additional input as per NIST SP-800-90Ar1, Sections 9.1 and 9.2.
  114. Additional seed material is also drawn from the RAND's parent or the
  115. operating system. If I<prediction_resistance> is specified, fresh entropy
  116. from a live source will be sought. This call operates as per NIST SP 800-90A
  117. and SP 800-90C.
  118. EVP_RAND_nonce() creates a nonce in I<out> of maximum length I<outlen>
  119. bytes from the RAND I<ctx>. The function returns the length of the generated
  120. nonce. If I<out> is NULL, the length is still returned but no generation
  121. takes place. This allows a caller to dynamically allocate a buffer of the
  122. appropriate size.
  123. EVP_RAND_enable_locking() enables locking for the RAND I<ctx> and all of
  124. its parents. After this I<ctx> will operate in a thread safe manner, albeit
  125. more slowly.
  126. EVP_RAND_get_params() retrieves details about the implementation
  127. I<rand>.
  128. The set of parameters given with I<params> determine exactly what
  129. parameters should be retrieved.
  130. Note that a parameter that is unknown in the underlying context is
  131. simply ignored.
  132. EVP_RAND_get_ctx_params() retrieves chosen parameters, given the
  133. context I<ctx> and its underlying context.
  134. The set of parameters given with I<params> determine exactly what
  135. parameters should be retrieved.
  136. Note that a parameter that is unknown in the underlying context is
  137. simply ignored.
  138. EVP_RAND_set_ctx_params() passes chosen parameters to the underlying
  139. context, given a context I<ctx>.
  140. The set of parameters given with I<params> determine exactly what
  141. parameters are passed down.
  142. Note that a parameter that is unknown in the underlying context is
  143. simply ignored.
  144. Also, what happens when a needed parameter isn't passed down is
  145. defined by the implementation.
  146. EVP_RAND_gettable_params(), EVP_RAND_gettable_ctx_params() and
  147. EVP_RAND_settable_ctx_params() get a constant B<OSSL_PARAM> array that
  148. describes the retrievable and settable parameters, i.e. parameters that
  149. can be used with EVP_RAND_get_params(), EVP_RAND_get_ctx_params()
  150. and EVP_RAND_set_ctx_params(), respectively.
  151. See L<OSSL_PARAM(3)> for the use of B<OSSL_PARAM> as parameter descriptor.
  152. =head2 Information functions
  153. EVP_RAND_strength() returns the security strength of the RAND I<ctx>.
  154. EVP_RAND_state() returns the current state of the RAND I<ctx>.
  155. States defined by the OpenSSL RNGs are:
  156. =over 4
  157. =item *
  158. EVP_RAND_STATE_UNINITIALISED: this RNG is currently uninitialised.
  159. The instantiate call will change this to the ready state.
  160. =item *
  161. EVP_RAND_STATE_READY: this RNG is currently ready to generate output.
  162. =item *
  163. EVP_RAND_STATE_ERROR: this RNG is in an error state.
  164. =back
  165. EVP_RAND_is_a() returns 1 if I<rand> is an implementation of an
  166. algorithm that's identifiable with I<name>, otherwise 0.
  167. EVP_RAND_provider() returns the provider that holds the implementation
  168. of the given I<rand>.
  169. EVP_RAND_do_all_provided() traverses all RAND implemented by all activated
  170. providers in the given library context I<libctx>, and for each of the
  171. implementations, calls the given function I<fn> with the implementation method
  172. and the given I<arg> as argument.
  173. EVP_RAND_number() returns the internal dynamic number assigned to
  174. I<rand>.
  175. EVP_RAND_name() returns the canonical name of I<rand>.
  176. EVP_RAND_names_do_all() traverses all names for I<rand>, and calls
  177. I<fn> with each name and I<data>.
  178. EVP_RAND_verify_zeroization() confirms if the internal DRBG state is
  179. currently zeroed. This is used by the FIPS provider to support the mandatory
  180. self tests.
  181. =head1 PARAMETERS
  182. The standard parameter names are:
  183. =over 4
  184. =item "state" (B<OSSL_RAND_PARAM_STATE>) <integer>
  185. Returns the state of the random number generator.
  186. =item "strength" (B<OSSL_RAND_PARAM_STRENGTH>) <unsigned integer>
  187. Returns the bit strength of the random number generator.
  188. =back
  189. For rands that are also deterministic random bit generators (DRBGs), these
  190. additional parameters are recognised. Not all
  191. parameters are relevant to, or are understood by all DRBG rands:
  192. =over 4
  193. =item "reseed_requests" (B<OSSL_DRBG_PARAM_RESEED_REQUESTS>) <unsigned integer>
  194. Reads or set the number of generate requests before reseeding the
  195. associated RAND ctx.
  196. =item "reseed_time_interval" (B<OSSL_DRBG_PARAM_RESEED_TIME_INTERVAL>) <integer>
  197. Reads or set the number of elapsed seconds before reseeding the
  198. associated RAND ctx.
  199. =item "max_request" (B<OSSL_DRBG_PARAM_RESEED_REQUESTS>) <unsigned integer>
  200. Specifies the maximum number of bytes that can be generated in a single
  201. call to OSSL_FUNC_rand_generate.
  202. =item "min_entropylen" (B<OSSL_DRBG_PARAM_MIN_ENTROPYLEN>) <unsigned integer>
  203. =item "max_entropylen" (B<OSSL_DRBG_PARAM_MAX_ENTROPYLEN>) <unsigned integer>
  204. Specify the minimum and maximum number of bytes of random material that
  205. can be used to seed the DRBG.
  206. =item "min_noncelen" (B<OSSL_DRBG_PARAM_MIN_NONCELEN>) <unsigned integer>
  207. =item "max_noncelen" (B<OSSL_DRBG_PARAM_MAX_NONCELEN>) <unsigned integer>
  208. Specify the minimum and maximum number of bytes of nonce that can be used to
  209. seed the DRBG.
  210. =item "max_perslen" (B<OSSL_DRBG_PARAM_MAX_PERSLEN>) <unsigned integer>
  211. =item "max_adinlen" (B<OSSL_DRBG_PARAM_MAX_ADINLEN>) <unsigned integer>
  212. Specify the minimum and maximum number of bytes of personalisation string
  213. that can be used with the DRBG.
  214. =item "reseed_counter" (B<OSSL_DRBG_PARAM_RESEED_COUNTER>) <unsigned integer>
  215. Specifies the number of times the DRBG has been seeded or reseeded.
  216. =item "properties" (B<OSSL_RAND_PARAM_PROPERTIES>) <UTF8 string>
  217. =item "mac" (B<OSSL_RAND_PARAM_MAC>) <UTF8 string>
  218. =item "digest" (B<OSSL_RAND_PARAM_DIGEST>) <UTF8 string>
  219. =item "cipher" (B<OSSL_RAND_PARAM_CIPHER>) <UTF8 string>
  220. For RAND implementations that use an underlying computation MAC, digest or
  221. cipher, these parameters set what the algorithm should be.
  222. The value is always the name of the intended algorithm,
  223. or the properties in the case of B<OSSL_RAND_PARAM_PROPERTIES>.
  224. =back
  225. =head1 RETURN VALUES
  226. EVP_RAND_fetch() returns a pointer to a newly fetched B<EVP_RAND>, or
  227. NULL if allocation failed.
  228. EVP_RAND_provider() returns a pointer to the provider for the RAND, or
  229. NULL on error.
  230. EVP_RAND_CTX_rand() returns a pointer to the B<EVP_RAND> associated with the
  231. context.
  232. EVP_RAND_name() returns the name of the random number generation algorithm.
  233. EVP_RAND_number() returns the provider specific identification number
  234. for the specified algorithm.
  235. EVP_RAND_up_ref() returns 1 on success, 0 on error.
  236. EVP_RAND_CTX_new() returns either the newly allocated
  237. B<EVP_RAND_CTX> structure or NULL if an error occurred.
  238. EVP_RAND_CTX_free() does not return a value.
  239. EVP_RAND_nonce() returns the length of the nonce.
  240. EVP_RAND_strength() returns the strength of the random number generator in bits.
  241. EVP_RAND_gettable_params(), EVP_RAND_gettable_ctx_params() and
  242. EVP_RAND_settable_ctx_params() return an array of OSSL_PARAMs.
  243. EVP_RAND_verify_zeroization() returns 1 if the internal DRBG state is
  244. currently zeroed, and 0 if not.
  245. The remaining functions return 1 for success and 0 or a negative value for
  246. failure.
  247. =head1 SEE ALSO
  248. L<RAND_bytes(3)>,
  249. L<EVP_RAND-CTR-DRBG(7)>,
  250. L<EVP_RAND-HASH-DRBG(7)>,
  251. L<EVP_RAND-HMAC-DRBG(7)>,
  252. L<EVP_RAND-TEST-RAND(7)>,
  253. L<provider-rand(7)>
  254. =head1 HISTORY
  255. This functionality was added to OpenSSL 3.0.
  256. =head1 COPYRIGHT
  257. Copyright 2020 The OpenSSL Project Authors. All Rights Reserved.
  258. Licensed under the Apache License 2.0 (the "License"). You may not use
  259. this file except in compliance with the License. You can obtain a copy
  260. in the file LICENSE in the source distribution or at
  261. L<https://www.openssl.org/source/license.html>.
  262. =cut