EVP_RAND.3ossl 21 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452
  1. .\" -*- mode: troff; coding: utf-8 -*-
  2. .\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
  3. .\"
  4. .\" Standard preamble:
  5. .\" ========================================================================
  6. .de Sp \" Vertical space (when we can't use .PP)
  7. .if t .sp .5v
  8. .if n .sp
  9. ..
  10. .de Vb \" Begin verbatim text
  11. .ft CW
  12. .nf
  13. .ne \\$1
  14. ..
  15. .de Ve \" End verbatim text
  16. .ft R
  17. .fi
  18. ..
  19. .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
  20. .ie n \{\
  21. . ds C` ""
  22. . ds C' ""
  23. 'br\}
  24. .el\{\
  25. . ds C`
  26. . ds C'
  27. 'br\}
  28. .\"
  29. .\" Escape single quotes in literal strings from groff's Unicode transform.
  30. .ie \n(.g .ds Aq \(aq
  31. .el .ds Aq '
  32. .\"
  33. .\" If the F register is >0, we'll generate index entries on stderr for
  34. .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
  35. .\" entries marked with X<> in POD. Of course, you'll have to process the
  36. .\" output yourself in some meaningful fashion.
  37. .\"
  38. .\" Avoid warning from groff about undefined register 'F'.
  39. .de IX
  40. ..
  41. .nr rF 0
  42. .if \n(.g .if rF .nr rF 1
  43. .if (\n(rF:(\n(.g==0)) \{\
  44. . if \nF \{\
  45. . de IX
  46. . tm Index:\\$1\t\\n%\t"\\$2"
  47. ..
  48. . if !\nF==2 \{\
  49. . nr % 0
  50. . nr F 2
  51. . \}
  52. . \}
  53. .\}
  54. .rr rF
  55. .\" ========================================================================
  56. .\"
  57. .IX Title "EVP_RAND 3ossl"
  58. .TH EVP_RAND 3ossl 2025-01-17 3.4.0 OpenSSL
  59. .\" For nroff, turn off justification. Always turn off hyphenation; it makes
  60. .\" way too many mistakes in technical documents.
  61. .if n .ad l
  62. .nh
  63. .SH NAME
  64. EVP_RAND, EVP_RAND_fetch, EVP_RAND_free, EVP_RAND_up_ref, EVP_RAND_CTX,
  65. EVP_RAND_CTX_new, EVP_RAND_CTX_free, EVP_RAND_CTX_up_ref, EVP_RAND_instantiate,
  66. EVP_RAND_uninstantiate, EVP_RAND_generate, EVP_RAND_reseed, EVP_RAND_nonce,
  67. EVP_RAND_enable_locking, EVP_RAND_verify_zeroization, EVP_RAND_get_strength,
  68. EVP_RAND_get_state,
  69. EVP_RAND_get0_provider, EVP_RAND_CTX_get0_rand, EVP_RAND_is_a,
  70. EVP_RAND_get0_name, EVP_RAND_names_do_all,
  71. EVP_RAND_get0_description,
  72. EVP_RAND_CTX_get_params,
  73. EVP_RAND_CTX_set_params, EVP_RAND_do_all_provided, EVP_RAND_get_params,
  74. EVP_RAND_gettable_ctx_params, EVP_RAND_settable_ctx_params,
  75. EVP_RAND_CTX_gettable_params, EVP_RAND_CTX_settable_params,
  76. EVP_RAND_gettable_params, EVP_RAND_STATE_UNINITIALISED, EVP_RAND_STATE_READY,
  77. EVP_RAND_STATE_ERROR \- EVP RAND routines
  78. .SH SYNOPSIS
  79. .IX Header "SYNOPSIS"
  80. .Vb 1
  81. \& #include <openssl/evp.h>
  82. \&
  83. \& typedef struct evp_rand_st EVP_RAND;
  84. \& typedef struct evp_rand_ctx_st EVP_RAND_CTX;
  85. \&
  86. \& EVP_RAND *EVP_RAND_fetch(OSSL_LIB_CTX *libctx, const char *algorithm,
  87. \& const char *properties);
  88. \& int EVP_RAND_up_ref(EVP_RAND *rand);
  89. \& void EVP_RAND_free(EVP_RAND *rand);
  90. \& EVP_RAND_CTX *EVP_RAND_CTX_new(EVP_RAND *rand, EVP_RAND_CTX *parent);
  91. \& void EVP_RAND_CTX_free(EVP_RAND_CTX *ctx);
  92. \& int EVP_RAND_CTX_up_ref(EVP_RAND_CTX *ctx);
  93. \& EVP_RAND *EVP_RAND_CTX_get0_rand(EVP_RAND_CTX *ctx);
  94. \& int EVP_RAND_get_params(EVP_RAND *rand, OSSL_PARAM params[]);
  95. \& int EVP_RAND_CTX_get_params(EVP_RAND_CTX *ctx, OSSL_PARAM params[]);
  96. \& int EVP_RAND_CTX_set_params(EVP_RAND_CTX *ctx, const OSSL_PARAM params[]);
  97. \& const OSSL_PARAM *EVP_RAND_gettable_params(const EVP_RAND *rand);
  98. \& const OSSL_PARAM *EVP_RAND_gettable_ctx_params(const EVP_RAND *rand);
  99. \& const OSSL_PARAM *EVP_RAND_settable_ctx_params(const EVP_RAND *rand);
  100. \& const OSSL_PARAM *EVP_RAND_CTX_gettable_params(EVP_RAND_CTX *ctx);
  101. \& const OSSL_PARAM *EVP_RAND_CTX_settable_params(EVP_RAND_CTX *ctx);
  102. \& const char *EVP_RAND_get0_name(const EVP_RAND *rand);
  103. \& const char *EVP_RAND_get0_description(const EVP_RAND *rand);
  104. \& int EVP_RAND_is_a(const EVP_RAND *rand, const char *name);
  105. \& const OSSL_PROVIDER *EVP_RAND_get0_provider(const EVP_RAND *rand);
  106. \& void EVP_RAND_do_all_provided(OSSL_LIB_CTX *libctx,
  107. \& void (*fn)(EVP_RAND *rand, void *arg),
  108. \& void *arg);
  109. \& int EVP_RAND_names_do_all(const EVP_RAND *rand,
  110. \& void (*fn)(const char *name, void *data),
  111. \& void *data);
  112. \&
  113. \& int EVP_RAND_instantiate(EVP_RAND_CTX *ctx, unsigned int strength,
  114. \& int prediction_resistance,
  115. \& const unsigned char *pstr, size_t pstr_len,
  116. \& const OSSL_PARAM params[]);
  117. \& int EVP_RAND_uninstantiate(EVP_RAND_CTX *ctx);
  118. \& int EVP_RAND_generate(EVP_RAND_CTX *ctx, unsigned char *out, size_t outlen,
  119. \& unsigned int strength, int prediction_resistance,
  120. \& const unsigned char *addin, size_t addin_len);
  121. \& int EVP_RAND_reseed(EVP_RAND_CTX *ctx, int prediction_resistance,
  122. \& const unsigned char *ent, size_t ent_len,
  123. \& const unsigned char *addin, size_t addin_len);
  124. \& int EVP_RAND_nonce(EVP_RAND_CTX *ctx, unsigned char *out, size_t outlen);
  125. \& int EVP_RAND_enable_locking(EVP_RAND_CTX *ctx);
  126. \& int EVP_RAND_verify_zeroization(EVP_RAND_CTX *ctx);
  127. \& unsigned int EVP_RAND_get_strength(EVP_RAND_CTX *ctx);
  128. \& int EVP_RAND_get_state(EVP_RAND_CTX *ctx);
  129. \&
  130. \& #define EVP_RAND_STATE_UNINITIALISED 0
  131. \& #define EVP_RAND_STATE_READY 1
  132. \& #define EVP_RAND_STATE_ERROR 2
  133. .Ve
  134. .SH DESCRIPTION
  135. .IX Header "DESCRIPTION"
  136. The EVP RAND routines are a high-level interface to random number generators
  137. both deterministic and not.
  138. If you just want to generate random bytes then you don't need to use
  139. these functions: just call \fBRAND_bytes()\fR or \fBRAND_priv_bytes()\fR.
  140. If you want to do more, these calls should be used instead of the older
  141. RAND and RAND_DRBG functions.
  142. .PP
  143. After creating a \fBEVP_RAND_CTX\fR for the required algorithm using
  144. \&\fBEVP_RAND_CTX_new()\fR, inputs to the algorithm are supplied either by
  145. passing them as part of the \fBEVP_RAND_instantiate()\fR call or using calls to
  146. \&\fBEVP_RAND_CTX_set_params()\fR before calling \fBEVP_RAND_instantiate()\fR. Finally,
  147. call \fBEVP_RAND_generate()\fR to produce cryptographically secure random bytes.
  148. .SS Types
  149. .IX Subsection "Types"
  150. \&\fBEVP_RAND\fR is a type that holds the implementation of a RAND.
  151. .PP
  152. \&\fBEVP_RAND_CTX\fR is a context type that holds the algorithm inputs.
  153. \&\fBEVP_RAND_CTX\fR structures are reference counted.
  154. .SS "Algorithm implementation fetching"
  155. .IX Subsection "Algorithm implementation fetching"
  156. \&\fBEVP_RAND_fetch()\fR fetches an implementation of a RAND \fIalgorithm\fR, given
  157. a library context \fIlibctx\fR and a set of \fIproperties\fR.
  158. See "ALGORITHM FETCHING" in \fBcrypto\fR\|(7) for further information.
  159. .PP
  160. The returned value must eventually be freed with
  161. \&\fBEVP_RAND_free\fR\|(3).
  162. .PP
  163. \&\fBEVP_RAND_up_ref()\fR increments the reference count of an already fetched
  164. RAND.
  165. .PP
  166. \&\fBEVP_RAND_free()\fR frees a fetched algorithm.
  167. NULL is a valid parameter, for which this function is a no-op.
  168. .SS "Context manipulation functions"
  169. .IX Subsection "Context manipulation functions"
  170. \&\fBEVP_RAND_CTX_new()\fR creates a new context for the RAND implementation \fIrand\fR.
  171. If not NULL, \fIparent\fR specifies the seed source for this implementation.
  172. Not all random number generators need to have a seed source specified.
  173. If a parent is required, a NULL \fIparent\fR will utilise the operating
  174. system entropy sources.
  175. It is recommended to minimise the number of random number generators that
  176. rely on the operating system for their randomness because this is often scarce.
  177. .PP
  178. \&\fBEVP_RAND_CTX_free()\fR frees up the context \fIctx\fR. If \fIctx\fR is NULL, nothing
  179. is done.
  180. .PP
  181. \&\fBEVP_RAND_CTX_get0_rand()\fR returns the \fBEVP_RAND\fR associated with the context
  182. \&\fIctx\fR.
  183. .SS "Random Number Generator Functions"
  184. .IX Subsection "Random Number Generator Functions"
  185. \&\fBEVP_RAND_instantiate()\fR processes any parameters in \fIparams\fR and
  186. then instantiates the RAND \fIctx\fR with a minimum security strength
  187. of <strength> and personalisation string \fIpstr\fR of length <pstr_len>.
  188. If \fIprediction_resistance\fR is specified, fresh entropy from a live source
  189. will be sought. This call operates as per NIST SP 800\-90A and SP 800\-90C.
  190. .PP
  191. \&\fBEVP_RAND_uninstantiate()\fR uninstantiates the RAND \fIctx\fR as per
  192. NIST SP 800\-90A and SP 800\-90C. Subsequent to this call, the RAND cannot
  193. be used to generate bytes. It can only be freed or instantiated again.
  194. .PP
  195. \&\fBEVP_RAND_generate()\fR produces random bytes from the RAND \fIctx\fR with the
  196. additional input \fIaddin\fR of length \fIaddin_len\fR. The bytes
  197. produced will meet the security \fIstrength\fR.
  198. If \fIprediction_resistance\fR is specified, fresh entropy from a live source
  199. will be sought. This call operates as per NIST SP 800\-90A and SP 800\-90C.
  200. .PP
  201. \&\fBEVP_RAND_reseed()\fR reseeds the RAND with new entropy.
  202. Entropy \fIent\fR of length \fIent_len\fR bytes can be supplied as can additional
  203. input \fIaddin\fR of length \fIaddin_len\fR bytes. In the FIPS provider, both are
  204. treated as additional input as per NIST SP\-800\-90Ar1, Sections 9.1 and 9.2.
  205. Additional seed material is also drawn from the RAND's parent or the
  206. operating system. If \fIprediction_resistance\fR is specified, fresh entropy
  207. from a live source will be sought. This call operates as per NIST SP 800\-90A
  208. and SP 800\-90C.
  209. .PP
  210. \&\fBEVP_RAND_nonce()\fR creates a nonce in \fIout\fR of maximum length \fIoutlen\fR
  211. bytes from the RAND \fIctx\fR. The function returns the length of the generated
  212. nonce. If \fIout\fR is NULL, the length is still returned but no generation
  213. takes place. This allows a caller to dynamically allocate a buffer of the
  214. appropriate size.
  215. .PP
  216. \&\fBEVP_RAND_enable_locking()\fR enables locking for the RAND \fIctx\fR and all of
  217. its parents. After this \fIctx\fR will operate in a thread safe manner, albeit
  218. more slowly. This function is not itself thread safe if called with the same
  219. \&\fIctx\fR from multiple threads. Typically locking should be enabled before a
  220. \&\fIctx\fR is shared across multiple threads.
  221. .PP
  222. \&\fBEVP_RAND_get_params()\fR retrieves details about the implementation
  223. \&\fIrand\fR.
  224. The set of parameters given with \fIparams\fR determine exactly what
  225. parameters should be retrieved.
  226. Note that a parameter that is unknown in the underlying context is
  227. simply ignored.
  228. .PP
  229. \&\fBEVP_RAND_CTX_get_params()\fR retrieves chosen parameters, given the
  230. context \fIctx\fR and its underlying context.
  231. The set of parameters given with \fIparams\fR determine exactly what
  232. parameters should be retrieved.
  233. Note that a parameter that is unknown in the underlying context is
  234. simply ignored.
  235. .PP
  236. \&\fBEVP_RAND_CTX_set_params()\fR passes chosen parameters to the underlying
  237. context, given a context \fIctx\fR.
  238. The set of parameters given with \fIparams\fR determine exactly what
  239. parameters are passed down.
  240. Note that a parameter that is unknown in the underlying context is
  241. simply ignored.
  242. Also, what happens when a needed parameter isn't passed down is
  243. defined by the implementation.
  244. .PP
  245. \&\fBEVP_RAND_gettable_params()\fR returns an \fBOSSL_PARAM\fR\|(3) array that describes
  246. the retrievable and settable parameters. \fBEVP_RAND_gettable_params()\fR returns
  247. parameters that can be used with \fBEVP_RAND_get_params()\fR.
  248. .PP
  249. \&\fBEVP_RAND_gettable_ctx_params()\fR and \fBEVP_RAND_CTX_gettable_params()\fR return
  250. constant \fBOSSL_PARAM\fR\|(3) arrays that describe the retrievable parameters that
  251. can be used with \fBEVP_RAND_CTX_get_params()\fR. \fBEVP_RAND_gettable_ctx_params()\fR
  252. returns the parameters that can be retrieved from the algorithm, whereas
  253. \&\fBEVP_RAND_CTX_gettable_params()\fR returns the parameters that can be retrieved
  254. in the context's current state.
  255. .PP
  256. \&\fBEVP_RAND_settable_ctx_params()\fR and \fBEVP_RAND_CTX_settable_params()\fR return
  257. constant \fBOSSL_PARAM\fR\|(3) arrays that describe the settable parameters that
  258. can be used with \fBEVP_RAND_CTX_set_params()\fR. \fBEVP_RAND_settable_ctx_params()\fR
  259. returns the parameters that can be retrieved from the algorithm, whereas
  260. \&\fBEVP_RAND_CTX_settable_params()\fR returns the parameters that can be retrieved
  261. in the context's current state.
  262. .SS "Information functions"
  263. .IX Subsection "Information functions"
  264. \&\fBEVP_RAND_get_strength()\fR returns the security strength of the RAND \fIctx\fR.
  265. .PP
  266. \&\fBEVP_RAND_get_state()\fR returns the current state of the RAND \fIctx\fR.
  267. States defined by the OpenSSL RNGs are:
  268. .IP \(bu 4
  269. EVP_RAND_STATE_UNINITIALISED: this RNG is currently uninitialised.
  270. The instantiate call will change this to the ready state.
  271. .IP \(bu 4
  272. EVP_RAND_STATE_READY: this RNG is currently ready to generate output.
  273. .IP \(bu 4
  274. EVP_RAND_STATE_ERROR: this RNG is in an error state.
  275. .PP
  276. \&\fBEVP_RAND_is_a()\fR returns 1 if \fIrand\fR is an implementation of an
  277. algorithm that's identifiable with \fIname\fR, otherwise 0.
  278. .PP
  279. \&\fBEVP_RAND_get0_provider()\fR returns the provider that holds the implementation
  280. of the given \fIrand\fR.
  281. .PP
  282. \&\fBEVP_RAND_do_all_provided()\fR traverses all RAND implemented by all activated
  283. providers in the given library context \fIlibctx\fR, and for each of the
  284. implementations, calls the given function \fIfn\fR with the implementation method
  285. and the given \fIarg\fR as argument.
  286. .PP
  287. \&\fBEVP_RAND_get0_name()\fR returns the canonical name of \fIrand\fR.
  288. .PP
  289. \&\fBEVP_RAND_names_do_all()\fR traverses all names for \fIrand\fR, and calls
  290. \&\fIfn\fR with each name and \fIdata\fR.
  291. .PP
  292. \&\fBEVP_RAND_get0_description()\fR returns a description of the rand, meant for
  293. display and human consumption. The description is at the discretion of
  294. the rand implementation.
  295. .PP
  296. \&\fBEVP_RAND_verify_zeroization()\fR confirms if the internal DRBG state is
  297. currently zeroed. This is used by the FIPS provider to support the mandatory
  298. self tests.
  299. .SH PARAMETERS
  300. .IX Header "PARAMETERS"
  301. The standard parameter names are:
  302. .IP """state"" (\fBOSSL_RAND_PARAM_STATE\fR) <integer>" 4
  303. .IX Item """state"" (OSSL_RAND_PARAM_STATE) <integer>"
  304. Returns the state of the random number generator.
  305. .IP """strength"" (\fBOSSL_RAND_PARAM_STRENGTH\fR) <unsigned integer>" 4
  306. .IX Item """strength"" (OSSL_RAND_PARAM_STRENGTH) <unsigned integer>"
  307. Returns the bit strength of the random number generator.
  308. .IP """fips-indicator"" (\fBOSSL_RAND_PARAM_FIPS_APPROVED_INDICATOR\fR) <integer>" 4
  309. .IX Item """fips-indicator"" (OSSL_RAND_PARAM_FIPS_APPROVED_INDICATOR) <integer>"
  310. A getter that returns 1 if the operation is FIPS approved, or 0 otherwise.
  311. This option is used by the OpenSSL FIPS provider and is not supported
  312. by all EVP_RAND sources.
  313. .PP
  314. For rands that are also deterministic random bit generators (DRBGs), these
  315. additional parameters are recognised. Not all
  316. parameters are relevant to, or are understood by all DRBG rands:
  317. .IP """reseed_requests"" (\fBOSSL_DRBG_PARAM_RESEED_REQUESTS\fR) <unsigned integer>" 4
  318. .IX Item """reseed_requests"" (OSSL_DRBG_PARAM_RESEED_REQUESTS) <unsigned integer>"
  319. Reads or set the number of generate requests before reseeding the
  320. associated RAND ctx.
  321. .IP """reseed_time_interval"" (\fBOSSL_DRBG_PARAM_RESEED_TIME_INTERVAL\fR) <integer>" 4
  322. .IX Item """reseed_time_interval"" (OSSL_DRBG_PARAM_RESEED_TIME_INTERVAL) <integer>"
  323. Reads or set the number of elapsed seconds before reseeding the
  324. associated RAND ctx.
  325. .IP """max_request"" (\fBOSSL_RAND_PARAM_MAX_REQUEST\fR) <unsigned integer>" 4
  326. .IX Item """max_request"" (OSSL_RAND_PARAM_MAX_REQUEST) <unsigned integer>"
  327. Specifies the maximum number of bytes that can be generated in a single
  328. call to OSSL_FUNC_rand_generate.
  329. .IP """min_entropylen"" (\fBOSSL_DRBG_PARAM_MIN_ENTROPYLEN\fR) <unsigned integer>" 4
  330. .IX Item """min_entropylen"" (OSSL_DRBG_PARAM_MIN_ENTROPYLEN) <unsigned integer>"
  331. .PD 0
  332. .IP """max_entropylen"" (\fBOSSL_DRBG_PARAM_MAX_ENTROPYLEN\fR) <unsigned integer>" 4
  333. .IX Item """max_entropylen"" (OSSL_DRBG_PARAM_MAX_ENTROPYLEN) <unsigned integer>"
  334. .PD
  335. Specify the minimum and maximum number of bytes of random material that
  336. can be used to seed the DRBG.
  337. .IP """min_noncelen"" (\fBOSSL_DRBG_PARAM_MIN_NONCELEN\fR) <unsigned integer>" 4
  338. .IX Item """min_noncelen"" (OSSL_DRBG_PARAM_MIN_NONCELEN) <unsigned integer>"
  339. .PD 0
  340. .IP """max_noncelen"" (\fBOSSL_DRBG_PARAM_MAX_NONCELEN\fR) <unsigned integer>" 4
  341. .IX Item """max_noncelen"" (OSSL_DRBG_PARAM_MAX_NONCELEN) <unsigned integer>"
  342. .PD
  343. Specify the minimum and maximum number of bytes of nonce that can be used to
  344. seed the DRBG.
  345. .IP """max_perslen"" (\fBOSSL_DRBG_PARAM_MAX_PERSLEN\fR) <unsigned integer>" 4
  346. .IX Item """max_perslen"" (OSSL_DRBG_PARAM_MAX_PERSLEN) <unsigned integer>"
  347. .PD 0
  348. .IP """max_adinlen"" (\fBOSSL_DRBG_PARAM_MAX_ADINLEN\fR) <unsigned integer>" 4
  349. .IX Item """max_adinlen"" (OSSL_DRBG_PARAM_MAX_ADINLEN) <unsigned integer>"
  350. .PD
  351. Specify the minimum and maximum number of bytes of personalisation string
  352. that can be used with the DRBG.
  353. .IP """reseed_counter"" (\fBOSSL_DRBG_PARAM_RESEED_COUNTER\fR) <unsigned integer>" 4
  354. .IX Item """reseed_counter"" (OSSL_DRBG_PARAM_RESEED_COUNTER) <unsigned integer>"
  355. Specifies the number of times the DRBG has been seeded or reseeded.
  356. .IP """properties"" (\fBOSSL_RAND_PARAM_PROPERTIES\fR) <UTF8 string>" 4
  357. .IX Item """properties"" (OSSL_RAND_PARAM_PROPERTIES) <UTF8 string>"
  358. .PD 0
  359. .IP """mac"" (\fBOSSL_RAND_PARAM_MAC\fR) <UTF8 string>" 4
  360. .IX Item """mac"" (OSSL_RAND_PARAM_MAC) <UTF8 string>"
  361. .IP """digest"" (\fBOSSL_RAND_PARAM_DIGEST\fR) <UTF8 string>" 4
  362. .IX Item """digest"" (OSSL_RAND_PARAM_DIGEST) <UTF8 string>"
  363. .IP """cipher"" (\fBOSSL_RAND_PARAM_CIPHER\fR) <UTF8 string>" 4
  364. .IX Item """cipher"" (OSSL_RAND_PARAM_CIPHER) <UTF8 string>"
  365. .PD
  366. For RAND implementations that use an underlying computation MAC, digest or
  367. cipher, these parameters set what the algorithm should be.
  368. .Sp
  369. The value is always the name of the intended algorithm,
  370. or the properties in the case of \fBOSSL_RAND_PARAM_PROPERTIES\fR.
  371. .SH NOTES
  372. .IX Header "NOTES"
  373. The use of a nonzero value for the \fIprediction_resistance\fR argument to
  374. \&\fBEVP_RAND_instantiate()\fR, \fBEVP_RAND_generate()\fR or \fBEVP_RAND_reseed()\fR should
  375. be used sparingly. In the default setup, this will cause all public and
  376. private DRBGs to be reseeded on next use. Since, by default, public and
  377. private DRBGs are allocated on a per thread basis, this can result in
  378. significant overhead for highly multi-threaded applications. For normal
  379. use-cases, the default "reseed_requests" and "reseed_time_interval"
  380. thresholds ensure sufficient prediction resistance over time and you
  381. can reduce those values if you think they are too high. Explicitly
  382. requesting prediction resistance is intended for more special use-cases
  383. like generating long-term secrets.
  384. .PP
  385. An \fBEVP_RAND_CTX\fR needs to have locking enabled if it acts as the parent of
  386. more than one child and the children can be accessed concurrently. This must
  387. be done by explicitly calling \fBEVP_RAND_enable_locking()\fR.
  388. .PP
  389. The RAND life-cycle is described in \fBlife_cycle\-rand\fR\|(7). In the future,
  390. the transitions described there will be enforced. When this is done, it will
  391. not be considered a breaking change to the API.
  392. .SH "RETURN VALUES"
  393. .IX Header "RETURN VALUES"
  394. \&\fBEVP_RAND_fetch()\fR returns a pointer to a newly fetched \fBEVP_RAND\fR, or
  395. NULL if allocation failed.
  396. .PP
  397. \&\fBEVP_RAND_get0_provider()\fR returns a pointer to the provider for the RAND, or
  398. NULL on error.
  399. .PP
  400. \&\fBEVP_RAND_CTX_get0_rand()\fR returns a pointer to the \fBEVP_RAND\fR associated
  401. with the context.
  402. .PP
  403. \&\fBEVP_RAND_get0_name()\fR returns the name of the random number generation
  404. algorithm.
  405. .PP
  406. \&\fBEVP_RAND_up_ref()\fR returns 1 on success, 0 on error.
  407. .PP
  408. \&\fBEVP_RAND_names_do_all()\fR returns 1 if the callback was called for all names. A
  409. return value of 0 means that the callback was not called for any names.
  410. .PP
  411. \&\fBEVP_RAND_CTX_new()\fR returns either the newly allocated
  412. \&\fBEVP_RAND_CTX\fR structure or NULL if an error occurred.
  413. .PP
  414. \&\fBEVP_RAND_CTX_free()\fR does not return a value.
  415. .PP
  416. \&\fBEVP_RAND_CTX_up_ref()\fR returns 1 on success, 0 on error.
  417. .PP
  418. \&\fBEVP_RAND_nonce()\fR returns the length of the nonce.
  419. .PP
  420. \&\fBEVP_RAND_get_strength()\fR returns the strength of the random number generator
  421. in bits.
  422. .PP
  423. \&\fBEVP_RAND_gettable_params()\fR, \fBEVP_RAND_gettable_ctx_params()\fR and
  424. \&\fBEVP_RAND_settable_ctx_params()\fR return an array of OSSL_PARAMs.
  425. .PP
  426. \&\fBEVP_RAND_verify_zeroization()\fR returns 1 if the internal DRBG state is
  427. currently zeroed, and 0 if not.
  428. .PP
  429. The remaining functions return 1 for success and 0 or a negative value for
  430. failure.
  431. .SH "SEE ALSO"
  432. .IX Header "SEE ALSO"
  433. \&\fBRAND_bytes\fR\|(3),
  434. \&\fBEVP_RAND\-CTR\-DRBG\fR\|(7),
  435. \&\fBEVP_RAND\-HASH\-DRBG\fR\|(7),
  436. \&\fBEVP_RAND\-HMAC\-DRBG\fR\|(7),
  437. \&\fBEVP_RAND\-TEST\-RAND\fR\|(7),
  438. \&\fBprovider\-rand\fR\|(7),
  439. \&\fBlife_cycle\-rand\fR\|(7)
  440. .SH HISTORY
  441. .IX Header "HISTORY"
  442. \&\fBEVP_RAND_CTX_up_ref()\fR was added in OpenSSL 3.1.
  443. .PP
  444. The remaining functions were added in OpenSSL 3.0.
  445. .SH COPYRIGHT
  446. .IX Header "COPYRIGHT"
  447. Copyright 2020\-2024 The OpenSSL Project Authors. All Rights Reserved.
  448. .PP
  449. Licensed under the Apache License 2.0 (the "License"). You may not use
  450. this file except in compliance with the License. You can obtain a copy
  451. in the file LICENSE in the source distribution or at
  452. <https://www.openssl.org/source/license.html>.