文章目录
🌵概要
#include <openssl/core_dispatch.h>
#include <openssl/core_names.h>
/*
* None of these are actual functions, but are displayed like this for
* the function signatures for functions that are offered as function
* pointers in OSSL_DISPATCH arrays.
*/
/* Context management */
void *OSSL_FUNC_rand_newctx(void *provctx, void *parent,
const OSSL_DISPATCH *parent_calls);
void OSSL_FUNC_rand_freectx(void *ctx);
/* Random number generator functions: NIST */
int OSSL_FUNC_rand_instantiate(void *ctx, unsigned int strength,
int prediction_resistance,
const unsigned char *pstr, size_t pstr_len,
const OSSL_PARAM params[]);
int OSSL_FUNC_rand_uninstantiate(void *ctx);
int OSSL_FUNC_rand_generate(void *ctx, unsigned char *out, size_t outlen,
unsigned int strength, int prediction_resistance,
const unsigned char *addin, size_t addin_len);
int OSSL_FUNC_rand_reseed(void *ctx, int prediction_resistance,
const unsigned char *ent, size_t ent_len,
const unsigned char *addin, size_t addin_len);
/* Random number generator functions: additional */
size_t OSSL_FUNC_rand_nonce(void *ctx, unsigned char *out, size_t outlen,
int strength, size_t min_noncelen,
size_t max_noncelen);
size_t OSSL_FUNC_rand_get_seed(void *ctx, unsigned char **buffer,
int entropy, size_t min_len, size_t max_len,
int prediction_resistance,
const unsigned char *adin, size_t adin_len);
void OSSL_FUNC_rand_clear_seed(void *ctx, unsigned char *buffer, size_t b_len);
int OSSL_FUNC_rand_verify_zeroization(void *ctx);
/* Context Locking */
int OSSL_FUNC_rand_enable_locking(void *ctx);
int OSSL_FUNC_rand_lock(void *ctx);
void OSSL_FUNC_rand_unlock(void *ctx);
/* RAND parameter descriptors */
const OSSL_PARAM *OSSL_FUNC_rand_gettable_params(void *provctx);
const OSSL_PARAM *OSSL_FUNC_rand_gettable_ctx_params(void *ctx, void *provctx);
const OSSL_PARAM *OSSL_FUNC_rand_settable_ctx_params(void *ctx, void *provctx);
/* RAND parameters */
int OSSL_FUNC_rand_get_params(OSSL_PARAM params[]);
int OSSL_FUNC_rand_get_ctx_params(void *ctx, OSSL_PARAM params[]);
int OSSL_FUNC_rand_set_ctx_params(void *ctx, const OSSL_PARAM params[]);
🎄描述
RAND 操作使提供商能够实现随机数生成算法和随机数源，并通过 API 函数 EVP_RAND 将它们提供给应用程序。
🌲上下文管理功能
OSSL_FUNC_rand_newctx（） 应创建并返回指向提供者端结构的指针，以便在兰特操作期间保存上下文信息。指向此上下文的指针将在许多其他 rand 操作函数调用中传递回去。参数 provctx 是在提供程序初始化期间生成的提供程序上下文。参数 parent 指定要用于种子设定目的的另一个 rand 实例。如果 NULL 且特定实例支持它，则操作系统将用于种子设定。参数parent_calls指向父级的调度表。因此，父实例不必与新实例来自同一提供程序。
OSSL_FUNC_rand_freectx（） 在 mctx 参数中传递一个指向提供程序端 rand 上下文的指针。如果它接收 NULL 作为 ctx 值，则除了返回之外，它不应执行任何其他操作。此函数应释放与该上下文关联的任何资源。
🌳随机数生成器函数： NIST
这些函数对应于 NIST SP 800-90A 和 SP 800-90C 中定义的函数。
OSSL_FUNC_rand_instantiate（） 用于以请求的安全强度实例化 DRBG ctx。此外，酒店还可应要求提供prediction_resistance。可以选择提供长度addin_len字节的额外输入加法。参数中指定的参数配置 DRBG，这些参数应在实例化之前进行处理。
OSSL_FUNC_rand_uninstantiate（） 用于取消验证 DRBG ctx。未经验证后，DRBG 将无法生成输出，直到重新实例化。
OSSL_FUNC_rand_generate（） 用于从 DRBG ctx 生成随机字节。它将生成 outlen 字节，将它们放入 out 所指向的缓冲区中。生成的字节将满足指定的安全强度，如果prediction_resistance为 true，则将从实时熵源重新设定种子后生成字节。可以选择提供长度addin_len字节的额外输入加法。
🌴随机数生成器函数：附加
OSSL_FUNC_rand_nonce（） 用于生成长度从 min_noncelen 到 max_noncelen 的给定强度的随机数。如果输出缓冲区输出为 NULL，则应返回随机数的长度。
OSSL_FUNC_rand_get_seed（） 由确定性生成器用于从其父级获取其播种材料。种子字节将满足熵位的指定安全级别，并且总共将存在 min_len 个字节和 max_len 个（含）字节。如果prediction_resistance为真，则字节将从实时熵源生成。可以选择提供长度addin_len字节的额外输入加法。指向种子材料的指针在 *buffer 中返回，并且必须通过稍后调用 OSSL_FUNC_rand_clear_seed（） 来释放该指针。
OSSL_FUNC_rand_clear_seed（） 释放先前由 OSSL_FUNC_rand_get_seed（） 分配的长度为 b_len 字节的种子缓冲区。
OSSL_FUNC_rand_verify_zeroization（） 用于确定 DRBG 的内部状态是否为零。此功能由NIST强制要求作为自检的一部分，在其他情况下不太可能有用。
🌱上下文锁定
当 DRBG 由多个线程使用时，必须采用锁定来确保其正常运行。由于锁定会带来开销，因此默认情况下处于禁用状态。
OSSL_FUNC_rand_enable_locking（） 允许为 DRBG 及其所有父 DRBG 打开锁定。从此调用开始，DRBG 可以以线程安全的方式使用。
OSSL_FUNC_rand_lock（） 用于锁定 DRBG。锁定后，将保证独占访问。
OSSL_FUNC_rand_unlock（） 用于解锁 DRBG。
🌿Rand参数
有关这些函数使用的参数结构的更多详细信息，请参见 OSSL_PARAM。
OSSL_FUNC_rand_get_params（） 获取与提供程序算法关联的参数值的详细信息，并将其存储在params.中。
OSSL_FUNC_rand_set_ctx_params（） 将与给定提供者端rand上下文 ctx 关联的rand参数设置为params.。任何参数设置都是对以前设置的任何参数设置的附加设置。为params.传递 NULL 应返回 true。
OSSL_FUNC_rand_get_ctx_params（） 获取与给定提供者端 rand 上下文 ctx 关联的当前设置参数值的详细信息，并将它们存储在params.中。为params.传递 NULL 应返回 true。
OSSL_FUNC_rand_gettable_params（）、OSSL_FUNC_rand_gettable_ctx_params（） 和 OSSL_FUNC_rand_settable_ctx_params（） 都返回常量OSSL_PARAM数组，作为分别OSSL_FUNC_rand_get_params（）、OSSL_FUNC_rand_get_ctx_params（） 和 OSSL_FUNC_rand_set_ctx_params（） 可以处理的参数的描述符。OSSL_FUNC_rand_gettable_ctx_params（） 和 OSSL_FUNC_rand_settable_ctx_params（） 将返回与当前状态的提供程序端上下文 ctx 关联的参数（如果它不是 NULL）。否则，它们将返回与提供程序端算法 provctx 关联的参数。
内置rand当前识别的参数如下。并非所有参数都与所有rand相关，或者所有rand都能理解：
-
“state” (OSSL_RAND_PARAM_STATE) < integer >
返回随机数生成器的状态。 -
“strength” (OSSL_RAND_PARAM_STRENGTH) < unsigned integer >
返回随机数生成器的位强度。
对于同时也是确定性随机位生成器 （DRBG） 的rand，可以识别这些附加参数。并非所有参数都与所有 DRBG rand 相关，或被所有 DRBG rands 理解：
-
“reseed_requests” (OSSL_DRBG_PARAM_RESEED_REQUESTS) < unsigned integer >
在重新设定关联 RAND ctx 种子之前读取或设置生成请求的数量。 -
“reseed_time_interval” (OSSL_DRBG_PARAM_RESEED_TIME_INTERVAL) < integer >
读取或设置在重新设定关联的 RAND ctx 种子之前经过的秒数。 -
“max_request” (OSSL_DRBG_PARAM_RESEED_REQUESTS) < unsigned integer >
指定在单个调用中可以生成的最大字节数，以OSSL_FUNC_rand_generate。 -
“min_entropylen” (OSSL_DRBG_PARAM_MIN_ENTROPYLEN) < unsigned integer >
“max_entropylen” (OSSL_DRBG_PARAM_MAX_ENTROPYLEN) < unsigned integer >
指定可用于种子设定 DRBG 的随机材料的最小和最大字节数。 -
“min_noncelen” (OSSL_DRBG_PARAM_MIN_NONCELEN) < unsigned integer >
“max_noncelen” (OSSL_DRBG_PARAM_MAX_NONCELEN) < unsigned integer >
指定可用于实例化 DRBG 的随机数的最小和最大字节数。 -
“max_perslen” (OSSL_DRBG_PARAM_MAX_PERSLEN) < unsigned integer >
“max_adinlen” (OSSL_DRBG_PARAM_MAX_ADINLEN) < unsigned integer >
指定可与 DRBG 一起使用的个性化字符串的最小和最大字节数。 -
“reseed_counter” (OSSL_DRBG_PARAM_RESEED_COUNTER) < unsigned integer >
指定 DRBG 播种或重新设定种子的次数。 -
“digest” (OSSL_DRBG_PARAM_DIGEST) < UTF8 string >
“cipher” (OSSL_DRBG_PARAM_CIPHER) < UTF8 string >
“mac” (OSSL_DRBG_PARAM_MAC) < UTF8 string >
设置要使用的基础密码、摘要或 MAC 的名称。它必须为正在使用的 DRBG 命名合适的算法。 -
“properties” (OSSL_DRBG_PARAM_PROPERTIES) < UTF8 string >
设置在尝试获取基础算法时要查询的属性。这必须与算法命名参数一起给出，才能被视为有效。
☘️返回值
OSSL_FUNC_rand_newctx（） 应返回新创建的提供程序端 rand 上下文，或在失败时返回 NULL。
OSSL_FUNC_rand_gettable_params（）、OSSL_FUNC_rand_gettable_ctx_params（） 和 OSSL_FUNC_rand_settable_ctx_params（） 应返回常量OSSL_PARAM数组，如果未提供，则返回 NULL。
OSSL_FUNC_rand_nonce（） 返回生成的随机数的大小，或在出错时返回 0。
OSSL_FUNC_rand_get_seed（） 返回生成的种子的大小，或在出错时返回 0。
所有其余函数都应返回 1 表示成功，或在错误时返回 0。
