/docs/man3.3/man7/EVP_KDF-KB.html - OpenSSL 繁體中文

EVP_KDF-KB

名稱

EVP_KDF-KB - 基於金鑰的 EVP_KDF 實作

說明

EVP_KDF-KB 演算法實作基於金鑰的密鑰衍生函數 (KBKDF)。KBKDF 從重複應用已加密的 MAC 到輸入機密 (和其他選用值) 中衍生出金鑰。

身分

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

支援的參數

支援的參數為

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

模式參數決定要使用哪種 KBKDF - 目前可選擇「計數器」和「回饋」。「計數器」為預設值，且如果未指定，將會使用此值。

「mac」(OSSL_KDF_PARAM_MAC) <UTF8 字串>

值為 CMAC、HMAC、KMAC128 或 KMAC256。

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

「密碼」(OSSL_KDF_PARAM_CIPHER) <UTF8 字串>

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

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

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

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

「種子」(OSSL_KDF_PARAM_SEED) <八位元組字串>

種子參數在計數器模式中未使用。

「使用 L」(OSSL_KDF_PARAM_KBKDF_USE_L) <整數>

設定為 0 以停用選用固定輸入資料「L」(請參閱 SP800-108)。如果未指定，將使用預設值 1。

「使用分隔符號」(OSSL_KDF_PARAM_KBKDF_USE_SEPARATOR) <整數>

設定為 0 以停用選用固定輸入資料「零分隔符號」(請參閱 SP800-108)，此資料會置於標籤和內容之間。如果未指定，將使用預設值 1。

「r」(OSSL_KDF_PARAM_KBKDF_R) <整數>

設定固定值「r」，表示計數器長度（以位元為單位）。

支援的值為 8、16、24 和 32。如果未指定，將使用預設值 32。

根據 mac 是 CMAC 或 HMAC，需要 digest 或 cipher（分別），而另一個則未使用。它們未用於 KMAC128 和 KMAC256。

參數金鑰、鹽、資訊和種子分別對應於 SP800-108 中的 KI、標籤、內容和 IV。與該文件中相同，鹽、資訊和種子為選用，可以省略。

「mac」、「摘要」、「密碼」和「屬性」在「EVP_KDF(3) 中的「參數」中有說明。

備註

可透過呼叫取得 KBKDF 的內容

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

KBKDF 的輸出長度透過 EVP_KDF_derive(3) 函式的 keylen 參數指定。

請注意，目前 OpenSSL 只實作計數器和回饋模式。其他變體可能會在未來支援。

範例

此範例使用 COUNTER-HMAC-SHA256，KI 為「secret」、標籤為「label」，以及內容為「context」衍生 10 個位元組。

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

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

*p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_DIGEST,
                                        "SHA2-256", 0);
*p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_MAC,
                                        "HMAC", 0);
*p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_KEY,
                                         "secret", strlen("secret"));
*p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_SALT,
                                         "label", strlen("label"));
*p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_INFO,
                                         "context", strlen("context"));
*p = OSSL_PARAM_construct_end();
if (EVP_KDF_derive(kctx, out, sizeof(out), params) <= 0)
    error("EVP_KDF_derive");

EVP_KDF_CTX_free(kctx);

此範例使用 FEEDBACK-CMAC-AES256，KI 為「secret」、標籤為「label」，以及 IV 為「sixteen bytes iv」衍生 10 個位元組。

EVP_KDF *kdf;
EVP_KDF_CTX *kctx;
unsigned char out[10];
OSSL_PARAM params[8], *p = params;
unsigned char *iv = "sixteen bytes iv";

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

*p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_CIPHER, "AES256", 0);
*p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_MAC, "CMAC", 0);
*p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_MODE, "FEEDBACK", 0);
*p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_KEY,
                                         "secret", strlen("secret"));
*p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_SALT,
                                         "label", strlen("label"));
*p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_INFO,
                                         "context", strlen("context"));
*p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_SEED,
                                         iv, strlen(iv));
*p = OSSL_PARAM_construct_end();
if (EVP_KDF_derive(kctx, out, sizeof(out), params) <= 0)
    error("EVP_KDF_derive");

EVP_KDF_CTX_free(kctx);

遵循規範

NIST SP800-108、IETF RFC 6803、IETF RFC 8009。

另請參閱

EVP_KDF(3)、EVP_KDF_CTX_free(3)、EVP_KDF_CTX_get_kdf_size(3)、EVP_KDF_derive(3)、EVP_KDF(3) 中的「PARAMETERS」

歷程

此功能於 OpenSSL 3.0 中新增。

對 KMAC 的支援於 OpenSSL 3.1 中新增。

版權

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