/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 的分派表。因此，parent 不需要與新實例來自同一個提供者。

OSSL_FUNC_rand_freectx() 會在 mctx 參數中傳遞一個指標，指向提供者端的 rand 內容。如果它接收到 NULL 作為 ctx 值，它不應執行任何動作，除了傳回之外。此函式應釋放與該內容相關的所有資源。

亂數產生器函式：NIST

這些函式對應於 NIST SP 800-90A 和 SP 800-90C 中定義的函式。

OSSL_FUNC_rand_instantiate() 用於在請求的安全強度下實例化 DRBG ctx。此外，可以請求 預測阻抗。長度為 addin_len 位元的附加輸入 addin 可以選擇性地提供。params 中指定的參數會設定 DRBG，這些參數應在實例化之前處理。

OSSL_FUNC_rand_uninstantiate() 用於取消實例化 DRBG ctx。取消實例化後，DRBG 無法產生輸出，直到它重新實例化為止。

OSSL_FUNC_rand_generate() 用於從 DRBG ctx 產生亂數位元組。它將產生 outlen 位元組，並將它們放置在 out 指向的緩衝區中。產生的位元組將符合指定的安全性強度，如果 prediction_resistance 為 true，則會從即時熵來源重新播種後產生位元組。長度為 addin_len 位元的附加輸入 addin 可以選擇性地提供。

亂數產生器函式：其他

OSSL_FUNC_rand_nonce() 用於產生一個給定強度的隨機數，長度從 min_noncelen 到 max_noncelen。如果輸出緩衝區 out 為 NULL，則應傳回隨機數的長度。

OSSL_FUNC_rand_get_seed() 由確定性產生器使用，以從其父項取得其播種材料。種子位元組將符合指定的熵位元安全等級，且總共將有介於 min_len 和 max_len（包含）之間的位元組。如果 prediction_resistance 為 true，則位元組將從即時熵來源產生。可以選擇性地提供長度為 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。

隨機參數

請參閱 OSSL_PARAM(3) 以進一步了解這些函式使用的參數結構。

OSSL_FUNC_rand_get_params() 取得與提供者演算法相關聯的參數值的詳細資料，並將其儲存在 params 中。

OSSL_FUNC_rand_set_ctx_params() 將與給定的提供者端隨機內容 ctx 相關聯的隨機參數設定為 params。任何參數設定都會新增到先前設定的任何設定。將 NULL 傳遞給 params 應傳回 true。

OSSL_FUNC_rand_get_ctx_params() 取得與給定的提供者端隨機內容 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() 將傳回與提供者端內容在其目前狀態下相關聯的參數。否則，它們將傳回與提供者端演算法 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 License 2.0（「授權」）授權。您不得使用此檔案，除非符合授權。您可以在原始程式碼散佈中的 LICENSE 檔案或 https://www.openssl.org/source/license.html 取得一份副本。

開放SSL

密碼學和 SSL/TLS 工具組