/docs/man3.3/man7/EVP_KDF-HKDF.html

EVP_KDF-HKDF

名稱

EVP_KDF-HKDF - HKDF EVP_KDF 實作

說明

透過 EVP_KDF API 支援計算 HKDF KDF。

EVP_KDF-HKDF 演算法實作 HKDF 金鑰衍生函數。HKDF 遵循「萃取然後擴充」範例，其中 KDF 在邏輯上包含兩個模組。第一個階段會取得輸入金鑰資料，並從中「萃取」固定長度的偽亂數金鑰 K。第二個階段會將金鑰 K「擴充」成數個額外的偽亂數金鑰 (KDF 的輸出)。

身分

「HKDF」是此實作的名稱；它可用於 EVP_KDF_fetch() 函數。

支援的參數

支援的參數為

「屬性」 (OSSL_KDF_PARAM_PROPERTIES) <UTF8 字串>

「摘要」 (OSSL_KDF_PARAM_DIGEST) <UTF8 字串>

「金鑰」 (OSSL_KDF_PARAM_KEY) <八位元組字串>

「鹽」 (OSSL_KDF_PARAM_SALT) <八位元組字串>

這些參數的運作方式如 EVP_KDF(3) 中的「參數」所述。

「資訊」 (OSSL_KDF_PARAM_INFO) <八位元組字串>

此參數設定資訊值。內容資訊緩衝區的長度不得超過 1024 位元組；這對於任何 HKDF 的正常使用來說應已綽綽有餘。

「模式」 (OSSL_KDF_PARAM_MODE) <UTF8 字串> 或 <整數>

此參數設定 HKDF 作業的模式。目前已定義三種模式

「萃取和擴充」或 EVP_KDF_HKDF_MODE_EXTRACT_AND_EXPAND

這是預設模式。在設定為 HKDF 的 EVP_KDF_CTX 上呼叫 EVP_KDF_derive(3) 會一次執行萃取和擴充作業。傳回的衍生金鑰會是擴充作業後的結果。不會傳回中間固定長度的偽亂數金鑰 K。

在此模式中，必須在衍生金鑰之前設定摘要、金鑰、鹽和資訊值，否則會發生錯誤。

「僅萃取」或 EVP_KDF_HKDF_MODE_EXTRACT_ONLY

在此模式中，呼叫 EVP_KDF_derive(3) 只會執行萃取作業。傳回的值會是中間固定長度的偽亂數金鑰 K。keylen 參數必須與 K 的大小相符，可以在設定模式和摘要後呼叫 EVP_KDF_CTX_get_kdf_size() 來查詢。

在衍生金鑰之前，必須設定摘要、金鑰和鹽值，否則會發生錯誤。

「僅擴充」或 EVP_KDF_HKDF_MODE_EXPAND_ONLY

在此模式中，呼叫 EVP_KDF_derive(3) 將只執行擴充操作。輸入金鑰應設定為從先前萃取操作傳回的中間固定長度偽亂數金鑰 K。

在衍生金鑰之前，必須設定摘要、金鑰和資訊值，否則會發生錯誤。

備註

可透過呼叫取得 HKDF 的內容：

EVP_KDF *kdf = EVP_KDF_fetch(NULL, "HKDF", NULL);
EVP_KDF_CTX *kctx = EVP_KDF_CTX_new(kdf);

HKDF 擴充操作的輸出長度是透過 EVP_KDF_derive(3) 函式的 keylen 參數指定的。在使用 EVP_KDF_HKDF_MODE_EXTRACT_ONLY 時，keylen 參數必須等於中間固定長度偽亂數金鑰的大小，否則會發生錯誤。對於該模式，可以在設定 EVP_KDF_CTX 上的模式和摘要後，透過呼叫 EVP_KDF_CTX_get_kdf_size() 來查詢固定的輸出大小。

範例

此範例使用 SHA-256、機密金鑰「secret」、鹽值「salt」和資訊值「label」衍生 10 個位元組

EVP_KDF *kdf;
EVP_KDF_CTX *kctx;
unsigned char out[10];
OSSL_PARAM params[5], *p = params;

kdf = EVP_KDF_fetch(NULL, "HKDF", NULL);
kctx = EVP_KDF_CTX_new(kdf);
EVP_KDF_free(kdf);

*p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_DIGEST,
                                        SN_sha256, strlen(SN_sha256));
*p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_KEY,
                                         "secret", (size_t)6);
*p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_INFO,
                                         "label", (size_t)5);
*p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_SALT,
                                         "salt", (size_t)4);
*p = OSSL_PARAM_construct_end();
if (EVP_KDF_derive(kctx, out, sizeof(out), params) <= 0) {
    error("EVP_KDF_derive");
}

EVP_KDF_CTX_free(kctx);

遵循規範

RFC 5869

另請參閱

EVP_KDF(3)、EVP_KDF_CTX_new(3)、EVP_KDF_CTX_free(3)、EVP_KDF_CTX_get_kdf_size(3)、EVP_KDF_CTX_set_params(3)、EVP_KDF_derive(3)、EVP_KDF(3) 中的「參數」、EVP_KDF-TLS13_KDF(7)

歷程記錄

此功能已新增至 OpenSSL 3.0。

版權

根據 Apache 授權條款 2.0（「授權條款」）授權。您只能在遵守授權條款的情況下使用此檔案。您可以在原始程式碼散佈中的 LICENSE 檔案中取得副本，或至 https://www.openssl.org/source/license.html 取得副本。