{ "content": [ { "type": "text", "text": "# provider-rand (man)\n\n## NAME\n\nprovider-rand - The random number generation library <-> provider functions\n\n## SYNOPSIS\n\n#include \n#include \n/*\n* None of these are actual functions, but are displayed like this for\n* the function signatures for functions that are offered as function\n* pointers in OSSLDISPATCH arrays.\n*/\n/* Context management */\nvoid *OSSLFUNCrandnewctx(void *provctx, void *parent,\nconst OSSLDISPATCH *parentcalls);\nvoid OSSLFUNCrandfreectx(void *ctx);\n/* Random number generator functions: NIST */\nint OSSLFUNCrandinstantiate(void *ctx, unsigned int strength,\nint predictionresistance,\nconst unsigned char *pstr, sizet pstrlen,\nconst OSSLPARAM params[]);\nint OSSLFUNCranduninstantiate(void *ctx);\nint OSSLFUNCrandgenerate(void *ctx, unsigned char *out, sizet outlen,\nunsigned int strength, int predictionresistance,\nconst unsigned char *addin, sizet addinlen);\nint OSSLFUNCrandreseed(void *ctx, int predictionresistance,\nconst unsigned char *ent, sizet entlen,\nconst unsigned char *addin, sizet addinlen);\n/* Random number generator functions: additional */\nsizet OSSLFUNCrandnonce(void *ctx, unsigned char *out, sizet outlen,\nint strength, sizet minnoncelen,\nsizet maxnoncelen);\nsizet OSSLFUNCrandgetseed(void *ctx, unsigned char buffer,\nint entropy, sizet minlen, sizet maxlen,\nint predictionresistance,\nconst unsigned char *adin, sizet adinlen);\nvoid OSSLFUNCrandclearseed(void *ctx, unsigned char *buffer, sizet blen);\nint OSSLFUNCrandverifyzeroization(void *ctx);\n/* Context Locking */\nint OSSLFUNCrandenablelocking(void *ctx);\nint OSSLFUNCrandlock(void *ctx);\nvoid OSSLFUNCrandunlock(void *ctx);\n/* RAND parameter descriptors */\nconst OSSLPARAM *OSSLFUNCrandgettableparams(void *provctx);\nconst OSSLPARAM *OSSLFUNCrandgettablectxparams(void *ctx, void *provctx);\nconst OSSLPARAM *OSSLFUNCrandsettablectxparams(void *ctx, void *provctx);\n/* RAND parameters */\nint OSSLFUNCrandgetparams(OSSLPARAM params[]);\nint OSSLFUNCrandgetctxparams(void *ctx, OSSLPARAM params[]);\nint OSSLFUNCrandsetctxparams(void *ctx, const OSSLPARAM params[]);\n\n## DESCRIPTION\n\nThis documentation is primarily aimed at provider authors. See provider(7) for further\ninformation.\n\n## Sections\n\n- **NAME**\n- **SYNOPSIS**\n- **DESCRIPTION** (5 subsections)\n- **RETURN VALUES**\n- **NOTES**\n- **SEE ALSO**\n- **HISTORY**\n- **COPYRIGHT**\n\nUse structuredContent.sections for detailed options, examples, and full documentation.\n" } ], "structuredContent": { "command": "provider-rand", "section": "", "mode": "man", "summary": "provider-rand - The random number generation library <-> provider functions", "synopsis": "#include \n#include \n/*\n* None of these are actual functions, but are displayed like this for\n* the function signatures for functions that are offered as function\n* pointers in OSSLDISPATCH arrays.\n*/\n/* Context management */\nvoid *OSSLFUNCrandnewctx(void *provctx, void *parent,\nconst OSSLDISPATCH *parentcalls);\nvoid OSSLFUNCrandfreectx(void *ctx);\n/* Random number generator functions: NIST */\nint OSSLFUNCrandinstantiate(void *ctx, unsigned int strength,\nint predictionresistance,\nconst unsigned char *pstr, sizet pstrlen,\nconst OSSLPARAM params[]);\nint OSSLFUNCranduninstantiate(void *ctx);\nint OSSLFUNCrandgenerate(void *ctx, unsigned char *out, sizet outlen,\nunsigned int strength, int predictionresistance,\nconst unsigned char *addin, sizet addinlen);\nint OSSLFUNCrandreseed(void *ctx, int predictionresistance,\nconst unsigned char *ent, sizet entlen,\nconst unsigned char *addin, sizet addinlen);\n/* Random number generator functions: additional */\nsizet OSSLFUNCrandnonce(void *ctx, unsigned char *out, sizet outlen,\nint strength, sizet minnoncelen,\nsizet maxnoncelen);\nsizet OSSLFUNCrandgetseed(void *ctx, unsigned char buffer,\nint entropy, sizet minlen, sizet maxlen,\nint predictionresistance,\nconst unsigned char *adin, sizet adinlen);\nvoid OSSLFUNCrandclearseed(void *ctx, unsigned char *buffer, sizet blen);\nint OSSLFUNCrandverifyzeroization(void *ctx);\n/* Context Locking */\nint OSSLFUNCrandenablelocking(void *ctx);\nint OSSLFUNCrandlock(void *ctx);\nvoid OSSLFUNCrandunlock(void *ctx);\n/* RAND parameter descriptors */\nconst OSSLPARAM *OSSLFUNCrandgettableparams(void *provctx);\nconst OSSLPARAM *OSSLFUNCrandgettablectxparams(void *ctx, void *provctx);\nconst OSSLPARAM *OSSLFUNCrandsettablectxparams(void *ctx, void *provctx);\n/* RAND parameters */\nint OSSLFUNCrandgetparams(OSSLPARAM params[]);\nint OSSLFUNCrandgetctxparams(void *ctx, OSSLPARAM params[]);\nint OSSLFUNCrandsetctxparams(void *ctx, const OSSLPARAM params[]);", "tldr_summary": null, "tldr_examples": [], "tldr_source": null, "flags": [], "examples": [], "see_also": [ { "name": "provider", "section": "7", "url": "https://www.chedong.com/phpMan.php/man/provider/7/json" }, { "name": "RAND", "section": "7", "url": "https://www.chedong.com/phpMan.php/man/RAND/7/json" }, { "name": "EVPRAND", "section": "7", "url": "https://www.chedong.com/phpMan.php/man/EVPRAND/7/json" }, { "name": "lifecycle-rand", "section": "7", "url": "https://www.chedong.com/phpMan.php/man/lifecycle-rand/7/json" }, { "name": "EVPRAND", "section": "3", "url": "https://www.chedong.com/phpMan.php/man/EVPRAND/3/json" } ], "section_outline": [ { "name": "NAME", "lines": 2, "subsections": [] }, { "name": "SYNOPSIS", "lines": 53, "subsections": [] }, { "name": "DESCRIPTION", "lines": 7, "subsections": [ { "name": "Context Management Functions", "lines": 13 }, { "name": "Random Number Generator Functions: NIST", "lines": 16 }, { "name": "Random Number Generator Functions: Additional", "lines": 19 }, { "name": "Context Locking", "lines": 10 }, { "name": "Rand Parameters", "lines": 73 } ] }, { "name": "RETURN VALUES", "lines": 13, "subsections": [] }, { "name": "NOTES", "lines": 4, "subsections": [] }, { "name": "SEE ALSO", "lines": 2, "subsections": [] }, { "name": "HISTORY", "lines": 2, "subsections": [] }, { "name": "COPYRIGHT", "lines": 9, "subsections": [] } ], "sections": { "NAME": { "content": "provider-rand - The random number generation library <-> provider functions\n", "subsections": [] }, "SYNOPSIS": { "content": "#include \n#include \n\n/*\n* None of these are actual functions, but are displayed like this for\n* the function signatures for functions that are offered as function\n* pointers in OSSLDISPATCH arrays.\n*/\n\n/* Context management */\nvoid *OSSLFUNCrandnewctx(void *provctx, void *parent,\nconst OSSLDISPATCH *parentcalls);\nvoid OSSLFUNCrandfreectx(void *ctx);\n\n/* Random number generator functions: NIST */\nint OSSLFUNCrandinstantiate(void *ctx, unsigned int strength,\nint predictionresistance,\nconst unsigned char *pstr, sizet pstrlen,\nconst OSSLPARAM params[]);\nint OSSLFUNCranduninstantiate(void *ctx);\nint OSSLFUNCrandgenerate(void *ctx, unsigned char *out, sizet outlen,\nunsigned int strength, int predictionresistance,\nconst unsigned char *addin, sizet addinlen);\nint OSSLFUNCrandreseed(void *ctx, int predictionresistance,\nconst unsigned char *ent, sizet entlen,\nconst unsigned char *addin, sizet addinlen);\n\n/* Random number generator functions: additional */\nsizet OSSLFUNCrandnonce(void *ctx, unsigned char *out, sizet outlen,\nint strength, sizet minnoncelen,\nsizet maxnoncelen);\nsizet OSSLFUNCrandgetseed(void *ctx, unsigned char buffer,\nint entropy, sizet minlen, sizet maxlen,\nint predictionresistance,\nconst unsigned char *adin, sizet adinlen);\nvoid OSSLFUNCrandclearseed(void *ctx, unsigned char *buffer, sizet blen);\nint OSSLFUNCrandverifyzeroization(void *ctx);\n\n/* Context Locking */\nint OSSLFUNCrandenablelocking(void *ctx);\nint OSSLFUNCrandlock(void *ctx);\nvoid OSSLFUNCrandunlock(void *ctx);\n\n/* RAND parameter descriptors */\nconst OSSLPARAM *OSSLFUNCrandgettableparams(void *provctx);\nconst OSSLPARAM *OSSLFUNCrandgettablectxparams(void *ctx, void *provctx);\nconst OSSLPARAM *OSSLFUNCrandsettablectxparams(void *ctx, void *provctx);\n\n/* RAND parameters */\nint OSSLFUNCrandgetparams(OSSLPARAM params[]);\nint OSSLFUNCrandgetctxparams(void *ctx, OSSLPARAM params[]);\nint OSSLFUNCrandsetctxparams(void *ctx, const OSSLPARAM params[]);\n", "subsections": [] }, "DESCRIPTION": { "content": "This documentation is primarily aimed at provider authors. See provider(7) for further\ninformation.\n\nThe RAND operation enables providers to implement random number generation algorithms and\nrandom number sources and make them available to applications via the API function\nEVPRAND(3).\n", "subsections": [ { "name": "Context Management Functions", "content": "OSSLFUNCrandnewctx() should create and return a pointer to a provider side structure for\nholding context information during a rand operation. A pointer to this context will be\npassed back in a number of the other rand operation function calls. The parameter provctx is\nthe provider context generated during provider initialisation (see provider(7)). The\nparameter parent specifies another rand instance to be used for seeding purposes. If NULL\nand the specific instance supports it, the operating system will be used for seeding. The\nparameter parentcalls points to the dispatch table for parent. Thus, the parent need not be\nfrom the same provider as the new instance.\n\nOSSLFUNCrandfreectx() is passed a pointer to the provider side rand context in the mctx\nparameter. If it receives NULL as ctx value, it should not do anything other than return.\nThis function should free any resources associated with that context.\n" }, { "name": "Random Number Generator Functions: NIST", "content": "These functions correspond to those defined in NIST SP 800-90A and SP 800-90C.\n\nOSSLFUNCrandinstantiate() is used to instantiate the DRBG ctx at a requested security\nstrength. In addition, predictionresistance can be requested. Additional input addin of\nlength addinlen bytes can optionally be provided. The parameters specified in params\nconfigure the DRBG and these should be processed before instantiation.\n\nOSSLFUNCranduninstantiate() is used to uninstantiate the DRBG ctx. After being\nuninstantiated, a DRBG is unable to produce output until it is instantiated anew.\n\nOSSLFUNCrandgenerate() is used to generate random bytes from the DRBG ctx. It will\ngenerate outlen bytes placing them into the buffer pointed to by out. The generated bytes\nwill meet the specified security strength and, if predictionresistance is true, the bytes\nwill be produced after reseeding from a live entropy source. Additional input addin of\nlength addinlen bytes can optionally be provided.\n" }, { "name": "Random Number Generator Functions: Additional", "content": "OSSLFUNCrandnonce() is used to generate a nonce of the given strength with a length from\nminnoncelen to maxnoncelen. If the output buffer out is NULL, the length of the nonce\nshould be returned.\n\nOSSLFUNCrandgetseed() is used by deterministic generators to obtain their seeding\nmaterial from their parent. The seed bytes will meet the specified security level of entropy\nbits and there will be between minlen and maxlen inclusive bytes in total. If\npredictionresistance is true, the bytes will be produced from a live entropy source.\nAdditional input addin of length addinlen bytes can optionally be provided. A pointer to\nthe seed material is returned in *buffer and this must be freed by a later call to\nOSSLFUNCrandclearseed().\n\nOSSLFUNCrandclearseed() frees a seed buffer of length blen bytes which was previously\nallocated by OSSLFUNCrandgetseed().\n\nOSSLFUNCrandverifyzeroization() is used to determine if the internal state of the DRBG is\nzero. This capability is mandated by NIST as part of the self tests, it is unlikely to be\nuseful in other circumstances.\n" }, { "name": "Context Locking", "content": "When DRBGs are used by multiple threads, there must be locking employed to ensure their\nproper operation. Because locking introduces an overhead, it is disabled by default.\n\nOSSLFUNCrandenablelocking() allows locking to be turned on for a DRBG and all of its\nparent DRBGs. From this call onwards, the DRBG can be used in a thread safe manner.\n\nOSSLFUNCrandlock() is used to lock a DRBG. Once locked, exclusive access is guaranteed.\n\nOSSLFUNCrandunlock() is used to unlock a DRBG.\n" }, { "name": "Rand Parameters", "content": "See OSSLPARAM(3) for further details on the parameters structure used by these functions.\n\nOSSLFUNCrandgetparams() gets details of parameter values associated with the provider\nalgorithm and stores them in params.\n\nOSSLFUNCrandsetctxparams() sets rand parameters associated with the given provider side\nrand context ctx to params. Any parameter settings are additional to any that were\npreviously set. Passing NULL for params should return true.\n\nOSSLFUNCrandgetctxparams() gets details of currently set parameter values associated\nwith the given provider side rand context ctx and stores them in params. Passing NULL for\nparams should return true.\n\nOSSLFUNCrandgettableparams(), OSSLFUNCrandgettablectxparams(), and\nOSSLFUNCrandsettablectxparams() all return constant OSSLPARAM arrays as descriptors of\nthe parameters that OSSLFUNCrandgetparams(), OSSLFUNCrandgetctxparams(), and\nOSSLFUNCrandsetctxparams() can handle, respectively.\nOSSLFUNCrandgettablectxparams() and OSSLFUNCrandsettablectxparams() will return the\nparameters associated with the provider side context ctx in its current state if it is not\nNULL. Otherwise, they return the parameters associated with the provider side algorithm\nprovctx.\n\nParameters currently recognised by built-in rands are as follows. Not all parameters are\nrelevant to, or are understood by all rands:\n\n\"state\" (OSSLRANDPARAMSTATE) \nReturns the state of the random number generator.\n\n\"strength\" (OSSLRANDPARAMSTRENGTH) \nReturns the bit strength of the random number generator.\n\nFor rands that are also deterministic random bit generators (DRBGs), these additional\nparameters are recognised. Not all parameters are relevant to, or are understood by all DRBG\nrands:\n\n\"reseedrequests\" (OSSLDRBGPARAMRESEEDREQUESTS) \nReads or set the number of generate requests before reseeding the associated RAND ctx.\n\n\"reseedtimeinterval\" (OSSLDRBGPARAMRESEEDTIMEINTERVAL) \nReads or set the number of elapsed seconds before reseeding the associated RAND ctx.\n\n\"maxrequest\" (OSSLDRBGPARAMRESEEDREQUESTS) \nSpecifies the maximum number of bytes that can be generated in a single call to\nOSSLFUNCrandgenerate.\n\n\"minentropylen\" (OSSLDRBGPARAMMINENTROPYLEN) \n\"maxentropylen\" (OSSLDRBGPARAMMAXENTROPYLEN) \nSpecify the minimum and maximum number of bytes of random material that can be used to\nseed the DRBG.\n\n\"minnoncelen\" (OSSLDRBGPARAMMINNONCELEN) \n\"maxnoncelen\" (OSSLDRBGPARAMMAXNONCELEN) \nSpecify the minimum and maximum number of bytes of nonce that can be used to instantiate\nthe DRBG.\n\n\"maxperslen\" (OSSLDRBGPARAMMAXPERSLEN) \n\"maxadinlen\" (OSSLDRBGPARAMMAXADINLEN) \nSpecify the minimum and maximum number of bytes of personalisation string that can be\nused with the DRBG.\n\n\"reseedcounter\" (OSSLDRBGPARAMRESEEDCOUNTER) \nSpecifies the number of times the DRBG has been seeded or reseeded.\n\n\"digest\" (OSSLDRBGPARAMDIGEST) \n\"cipher\" (OSSLDRBGPARAMCIPHER) \n\"mac\" (OSSLDRBGPARAMMAC) \nSets the name of the underlying cipher, digest or MAC to be used. It must name a\nsuitable algorithm for the DRBG that's being used.\n\n\"properties\" (OSSLDRBGPARAMPROPERTIES) \nSets the properties to be queried when trying to fetch an underlying algorithm. This\nmust be given together with the algorithm naming parameter to be considered valid.\n" } ] }, "RETURN VALUES": { "content": "OSSLFUNCrandnewctx() should return the newly created provider side rand context, or NULL\non failure.\n\nOSSLFUNCrandgettableparams(), OSSLFUNCrandgettablectxparams() and\nOSSLFUNCrandsettablectxparams() should return a constant OSSLPARAM array, or NULL if\nnone is offered.\n\nOSSLFUNCrandnonce() returns the size of the generated nonce, or 0 on error.\n\nOSSLFUNCrandgetseed() returns the size of the generated seed, or 0 on error.\n\nAll of the remaining functions should return 1 for success or 0 on error.\n", "subsections": [] }, "NOTES": { "content": "The RAND life-cycle is described in lifecycle-rand(7). Providers should ensure that the\nvarious transitions listed there are supported. At some point the EVP layer will begin\nenforcing the listed transitions.\n", "subsections": [] }, "SEE ALSO": { "content": "provider(7), RAND(7), EVPRAND(7), lifecycle-rand(7), EVPRAND(3)\n", "subsections": [] }, "HISTORY": { "content": "The provider RAND interface was introduced in OpenSSL 3.0.\n", "subsections": [] }, "COPYRIGHT": { "content": "Copyright 2020-2021 The OpenSSL Project Authors. All Rights Reserved.\n\nLicensed under the Apache License 2.0 (the \"License\"). You may not use this file except in\ncompliance with the License. You can obtain a copy in the file LICENSE in the source\ndistribution or at .\n\n\n\n3.0.2 2026-06-02 PROVIDER-RAND(7SSL)", "subsections": [] } } } }