/docs/man3.3/man7/provider-rand.html

provider-rand

名称

provider-rand - 随机数生成库 <-> 提供者函数

概要

#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[]);

描述

此文档主要针对提供者作者。有关更多信息，请参见 provider(7)。

RAND 操作允许提供者实现随机数生成算法和随机数源，并通过 API 函数 EVP_RAND(3) 使其可供应用程序使用。

上下文管理函数

OSSL_FUNC_rand_newctx() 应创建并返回指向提供者端结构的指针，用于在 rand 操作期间保存上下文信息。指向此上下文的指针将在许多其他 rand 操作函数调用中传递回来。参数 provctx 是在提供者初始化期间生成的提供者上下文（请参见 provider(7)）。参数 parent 指定另一个 rand 实例，用于播种目的。如果为 NULL 并且特定实例支持它，则将使用操作系统进行播种。参数 parent_calls 指向 parent 的调度表。因此，父级不必与新实例来自同一个提供者。

OSSL_FUNC_rand_freectx() 在 mctx 参数中传递指向提供者端 rand 上下文的指针。如果它收到 NULL 作为 ctx 值，则除了返回之外不应执行任何操作。此函数应释放与该上下文关联的任何资源。

随机数生成器函数：NIST

这些函数对应于 NIST SP 800-90A 和 SP 800-90C 中定义的函数。

OSSL_FUNC_rand_instantiate() 用于在请求的安全 strength 下实例化 DRBG ctx。此外，可以请求 prediction_resistance。可以可选地提供长度为 addin_len 字节的额外输入 addin。params 中指定的参数配置 DRBG，这些参数应在实例化之前进行处理。

OSSL_FUNC_rand_uninstantiate() 用于取消实例化 DRBG ctx。在取消实例化后，DRBG 无法产生输出，直到它被重新实例化。

OSSL_FUNC_rand_generate() 用于从 DRBG ctx 生成随机字节。它将生成 outlen 字节，并将它们放置到 out 指向的缓冲区中。生成的字节将满足指定的安全 strength，如果 prediction_resistance 为真，则这些字节将在从实时熵源重新播种后产生。可以可选地提供长度为 addin_len 字节的额外输入 addin。

随机数生成器函数：其他

OSSL_FUNC_rand_nonce() 用于生成具有给定 strength 的随机数，其长度从 min_noncelen 到 max_noncelen。如果输出缓冲区 out 为 NULL，则应返回随机数的长度。

OSSL_FUNC_rand_get_seed() 用于由确定性生成器从其父级获取其播种材料。种子字节将满足指定的 entropy 位的安全级别，总共有 min_len 到 max_len（含）个字节。如果 prediction_resistance 为真，则这些字节将从实时熵源生成。可以可选地提供长度为 addin_len 字节的额外输入 addin。指向种子材料的指针将返回到 *buffer 中，并且必须通过以后对 OSSL_FUNC_rand_clear_seed() 的调用来释放。

OSSL_FUNC_rand_clear_seed() 释放先前由 OSSL_FUNC_rand_get_seed() 分配的长度为 b_len 字节的种子 buffer。

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(3)。

OSSL_FUNC_rand_get_params() 获取与提供者算法关联的参数值的详细信息，并将它们存储在 params 中。

OSSL_FUNC_rand_set_ctx_params() 将与给定提供者端 rand 上下文 ctx 关联的 rand 参数设置为 params。任何参数设置都是对先前设置的任何参数的补充。将 NULL 传递给 params 应返回 true。

OSSL_FUNC_rand_get_ctx_params() 获取与给定提供者端 rand 上下文 ctx 关联的当前设置的参数值的详细信息，并将它们存储在 params 中。将 NULL 传递给 params 应返回 true。

OSSL_FUNC_rand_gettable_params()、OSSL_FUNC_rand_gettable_ctx_params() 和 OSSL_FUNC_rand_settable_ctx_params() 都返回常量 OSSL_PARAM(3) 数组，作为 OSSL_FUNC_rand_get_params()、OSSL_FUNC_rand_get_ctx_params() 和 OSSL_FUNC_rand_set_ctx_params() 可以处理的参数的描述符。如果 ctx 不为 NULL，则 OSSL_FUNC_rand_gettable_ctx_params() 和 OSSL_FUNC_rand_settable_ctx_params() 将返回与其当前状态关联的提供者端上下文 ctx 的参数。否则，它们返回与提供者端算法 provctx 关联的参数。

内置 rand 当前识别的参数如下。并非所有参数都与所有 rand 相关或被所有 rand 理解。

"state" (OSSL_RAND_PARAM_STATE) <整数>: 返回随机数生成器的状态。
"strength" (OSSL_RAND_PARAM_STRENGTH) <无符号整数>: 返回随机数生成器的位强度。

对于也是确定性随机位生成器 (DRBG) 的 rand，这些附加参数被识别。并非所有参数都与所有 DRBG rand 相关或被所有 DRBG rand 理解。

"reseed_requests" (OSSL_DRBG_PARAM_RESEED_REQUESTS) <无符号整数>: 读取或设置在重新播种关联的 RAND ctx 之前生成的请求数量。
"reseed_time_interval" (OSSL_DRBG_PARAM_RESEED_TIME_INTERVAL) <整数>: 读取或设置在重新播种关联的 RAND ctx 之前经过的秒数。
"max_request" (OSSL_DRBG_PARAM_RESEED_REQUESTS) <无符号整数>: 指定一次调用 OSSL_FUNC_rand_generate() 可以生成的字节的最大数量。
"min_entropylen" (OSSL_DRBG_PARAM_MIN_ENTROPYLEN) <无符号整数>
"max_entropylen" (OSSL_DRBG_PARAM_MAX_ENTROPYLEN) <无符号整数>: 指定用于播种 DRBG 的随机材料的字节数的最小值和最大值。
"min_noncelen" (OSSL_DRBG_PARAM_MIN_NONCELEN) <无符号整数>
"max_noncelen" (OSSL_DRBG_PARAM_MAX_NONCELEN) <无符号整数>: 指定用于实例化 DRBG 的随机数的字节数的最小值和最大值。
"max_perslen" (OSSL_DRBG_PARAM_MAX_PERSLEN) <无符号整数>
"max_adinlen" (OSSL_DRBG_PARAM_MAX_ADINLEN) <无符号整数>: 指定可与 DRBG 一起使用的个性化字符串的字节数的最小值和最大值。
"reseed_counter" (OSSL_DRBG_PARAM_RESEED_COUNTER) <无符号整数>: 指定 DRBG 已播种或重新播种的次数。
"digest" (OSSL_DRBG_PARAM_DIGEST) <UTF8 字符串>
"cipher" (OSSL_DRBG_PARAM_CIPHER) <UTF8 字符串>
"mac" (OSSL_DRBG_PARAM_MAC) <UTF8 字符串>: 设置要使用的底层密码、摘要或 MAC 的名称。它必须为正在使用的 DRBG 指定合适的算法名称。
"properties" (OSSL_DRBG_PARAM_PROPERTIES) <UTF8 字符串>: 设置尝试获取底层算法时要查询的属性。这必须与算法命名参数一起给出才能被视为有效。

返回值

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(3) 数组，或在没有提供时返回 NULL。

OSSL_FUNC_rand_nonce() 返回生成的随机数的大小，或在错误时返回 0。

OSSL_FUNC_rand_get_seed() 返回生成的种子的大小，或在错误时返回 0。

所有其余函数在成功时应返回 1，在错误时返回 0。

注意

RAND 生命周期在 life_cycle-rand(7) 中进行了描述。提供者应确保支持那里列出的各种转换。在某个时候，EVP 层将开始强制执行列出的转换。

参见

provider(7)，RAND(7)，EVP_RAND(7)，life_cycle-rand(7)，EVP_RAND(3)

历史

提供者 RAND 接口在 OpenSSL 3.0 中引入。

版权

根据 Apache 许可证 2.0（“许可证”）许可。您不得使用此文件，除非符合许可证。您可以在源代码分发中的 LICENSE 文件或 https://www.openssl.org/source/license.html 中获取副本。