Функция BCryptDeriveKey (bcrypt.h)

Статья
07/16/2024

Функция BCryptDeriveKey получает ключ из значения секретного соглашения.

Сведения о производных ключах от заданного секрета см. в BCryptKeyDerivation.

Синтаксис

NTSTATUS BCryptDeriveKey(
  [in]            BCRYPT_SECRET_HANDLE hSharedSecret,
  [in]            LPCWSTR              pwszKDF,
  [in, optional]  BCryptBufferDesc     *pParameterList,
  [out, optional] PUCHAR               pbDerivedKey,
  [in]            ULONG                cbDerivedKey,
  [out]           ULONG                *pcbResult,
  [in]            ULONG                dwFlags
);

Параметры

[in] hSharedSecret

Дескриптор секретного соглашения для создания ключа из. Этот дескриптор получен из функции BCryptSecretAgreement.

[in] pwszKDF

Указатель на строку Юникода, завершающую значение NULL, которая идентифицирует функцию извлечения ключа (KDF), используемую для получения ключа. Это может быть одна из следующих строк.

BCRYPT_KDF_HASH (L"HASH")

Используйте функцию производного ключа хэша.

Если параметр cbDerivedKey меньше размера производного ключа, эта функция будет копировать только указанное число байтов в буфер pbDerivedKey. Если параметр cbDerivedKey больше размера производного ключа, эта функция скопировать ключ в буфер pbDerivedKey и задать переменную, на которую указывает pcbResult фактическое число байтов.

Параметры, определенные параметром pParameterList, могут или должны содержать следующие параметры, как указано в столбце "Обязательный" или "необязательный".

Параметр	Описание	Обязательный или необязательный
KDF_HASH_ALGORITHM	Строка Юникода, завершающаяся значением NULL, идентифицирующая используемый хэш-алгоритм. Это может быть один из стандартных идентификаторов хэш-алгоритма из идентификаторов алгоритма CNG или идентификатор другого зарегистрированного хэш-алгоритма. Если этот параметр не указан, используется хэш-алгоритм SHA1.	Необязательный
KDF_SECRET_PREPEND	Значение для добавления в начало входных данных сообщения в хэш-функцию. Дополнительные сведения см. в разделе "Примечания".	Необязательный
KDF_SECRET_APPEND	Значение, добавляемое в конец входных данных сообщения в хэш-функцию. Дополнительные сведения см. в разделе "Примечания".	Необязательный

Вызов KDF выполняется, как показано в следующем псевдокоде.

KDF-Prepend = KDF_SECRET_PREPEND[0] + 
    KDF_SECRET_PREPEND[1] + 
    ... +
    KDF_SECRET_PREPEND[n]

KDF-Append = KDF_SECRET_APPEND[0] + 
    KDF_SECRET_APPEND[1] + 
    ... + 
    KDF_SECRET_APPEND[n]

KDF-Output = Hash(
    KDF-Prepend + 
    hSharedSecret + 
    KDF-Append)

BCRYPT_KDF_HMAC (L"HMAC")

Используйте функцию на основе ключа Hash-Based код проверки подлинности сообщений (HMAC).

Параметр	Описание	Обязательный или необязательный
KDF_HASH_ALGORITHM	Строка Юникода, завершающаяся значением NULL, идентифицирующая используемый хэш-алгоритм. Это может быть один из стандартных идентификаторов хэш-алгоритма из идентификаторов алгоритма CNG или идентификатор другого зарегистрированного хэш-алгоритма. Если этот параметр не указан, используется хэш-алгоритм SHA1.	Необязательный
KDF_HMAC_KEY	Ключ, используемый для псевдослучайной функции (PRF).	Необязательный
KDF_SECRET_PREPEND	Значение для добавления в начало входных данных сообщения в хэш-функцию. Дополнительные сведения см. в разделе "Примечания".	Необязательный
KDF_SECRET_APPEND	Значение, добавляемое в конец входных данных сообщения в хэш-функцию. Дополнительные сведения см. в разделе "Примечания".	Необязательный

Вызов KDF выполняется, как показано в следующем псевдокоде.

KDF-Prepend = KDF_SECRET_PREPEND[0] + 
    KDF_SECRET_PREPEND[1] + 
    ... +
    KDF_SECRET_PREPEND[n]

KDF-Append = KDF_SECRET_APPEND[0] + 
    KDF_SECRET_APPEND[1] + 
    ... + 
    KDF_SECRET_APPEND[n]

KDF-Output = HMAC-Hash(
    KDF_HMAC_KEY,
    KDF-Prepend + 
    hSharedSecret + 
    KDF-Append)

BCRYPT_KDF_TLS_PRF (L"TLS_PRF")

Используйте функци ю безопасности транспортного уровня (TLS) псевдослучайную функцию ключа (PRF). Размер производного ключа всегда равен 48 байтам, поэтому параметр cbDerivedKey должен иметь значение 48.

Параметр	Описание	Обязательный или необязательный
KDF_TLS_PRF_LABEL	Строка ANSI, содержащая метку PRF.	Обязательно
KDF_TLS_PRF_SEED	Начальное значение PRF. Начальное значение должно иметь длину 64 байтов.	Обязательно
KDF_TLS_PRF_PROTOCOL	Значение DWORD, указывающее версию протокола TLS, алгоритм PRF которой используется. Допустимые значения: SSL2_PROTOCOL_VERSION (0x0002) SSL3_PROTOCOL_VERSION (0x0300) TLS1_PROTOCOL_VERSION (0x0301) TLS1_0_PROTOCOL_VERSION (0x0301) TLS1_1_PROTOCOL_VERSION (0x0302) TLS1_2_PROTOCOL_VERSION (0x0303) DTLS1_0_PROTOCOL_VERSION (0xfeff) Windows Server 2008 и Windows Vista: TLS1_1_PROTOCOL_VERSION, TLS1_2_PROTOCOL_VERSION и DTLS1_0_PROTOCOL_VERSION не поддерживаются. Windows Server 2008 R2, Windows 7, Windows Server 2008 и Windows Vista: DTLS1_0_PROTOCOL_VERSION не поддерживается.	Необязательный
KDF_HASH_ALGORITHM	Идентификатор алгоритма CNG хэша, используемого с HMAC в PRF, для версии протокола TLS 1.2. Допустимые варианты: SHA-256 и SHA-384. Если не указано, используется SHA-256.	Необязательный

Вызов KDF выполняется, как показано в следующем псевдокоде.

KDF-Output = PRF(
    hSharedSecret, 
    KDF_TLS_PRF_LABEL, 
    KDF_TLS_PRF_SEED)

BCRYPT_KDF_SP80056A_CONCAT (L"SP800_56A_CONCAT")

Используйте функцию производных ключей SP800-56A.

Параметры, определенные параметром pParameterList, могут или должны содержать следующие параметры, как указано в столбце "Обязательный" или "необязательный". Все значения параметров обрабатываются как непрозрачные массивы байтов.

Параметр	Описание	Обязательный или необязательный
KDF_ALGORITHMID	Задает подфилд AlgorithmID поля OtherInfo в функции производного ключа SP800-56A. Указывает предназначенную цель производного ключа.	Обязательно
KDF_PARTYUINFO	Задает подфилд PartyUInfo в поле OtherInfo в функции производного ключа SP800-56A. Поле содержит общедоступную информацию, предоставленную инициатором.	Обязательно
KDF_PARTYVINFO	Указывает подфилд PartyVInfo поля OtherInfo в функции производного ключа SP800-56A. Поле содержит общедоступную информацию, предоставленную ответчиком.	Обязательно
KDF_SUPPPUBINFO	Указывает подфилд SuppPubInfo поля OtherInfo в функции производного ключа SP800-56A. Поле содержит общедоступную информацию, известную как инициатору, так и ответчику.	Необязательный
KDF_SUPPPRIVINFO	Указывает подфилд SuppPrivInfo поля OtherInfo в функции производного ключа SP800-56A. Он содержит частную информацию, известную как инициатору, так и ответчику, например общему секрету.	Необязательный

Вызов KDF выполняется, как показано в следующем псевдокоде.

KDF-Output = SP_800-56A_KDF(
	   hSharedSecret,
	   KDF_ALGORITHMID,
	   KDF_PARTYUINFO,
	   KDF_PARTYVINFO,
	   KDF_SUPPPUBINFO,
	   KDF_SUPPPRIVINFO)

Windows Server 2008, Windows Vista, Windows Server 2003 и Windows XP: Это значение не поддерживается.

BCRYPT_KDF_RAW_SECRET (L"TRUNCATE")

Возвращает небольшое представление необработанного секрета без каких-либо изменений.

Windows 8, Windows Server 2008, Windows Vista, Windows Server 2003 и Windows XP: Это значение не поддерживается.

[in, optional] pParameterList

Адрес структуры BCryptBufferDe sc , содержащей параметры KDF. Этот параметр является необязательным и может быть null, если он не нужен.

[out, optional] pbDerivedKey

Адрес буфера, получающего ключ. Параметр cbDerivedKey содержит размер этого буфера. Если этот параметр NULL, эта функция будет размещать необходимый размер в байтах в ULONG, на которую указывает параметр pcbResult.

[in] cbDerivedKey

Размер в байтах буфера pbDerivedKey.

[out] pcbResult

Указатель на ULONG, получающий количество байтов, скопированных в буфер pbDerivedKey. Если параметр pbDerivedKeyNULL, эта функция будет размещать требуемый размер в байтах в ULONG, на которую указывает этот параметр.

[in] dwFlags

Набор флагов, изменяющих поведение этой функции. Это может быть ноль или следующее значение.

Ценность	Значение
KDF_USE_SECRET_AS_HMAC_KEY_FLAG	Значение секретного соглашения также будет служить ключом HMAC. Если этот флаг указан, параметр KDF_HMAC_KEY не должен быть включен в набор параметров в параметре pParameterList. Этот флаг используется только функцией вывода ключей BCRYPT_KDF_HMAC.

Ценность

Значение

KDF_USE_SECRET_AS_HMAC_KEY_FLAG

Значение секретного соглашения также будет служить ключом HMAC. Если этот флаг указан, параметр KDF_HMAC_KEY не должен быть включен в набор параметров в параметре pParameterList. Этот флаг используется только функцией вывода ключей BCRYPT_KDF_HMAC.

Возвращаемое значение

Возвращает код состояния, указывающий на успешность или сбой функции.

Возможные коды возврата включают в себя, но не ограничиваются следующими.

Возвращаемый код	Описание
STATUS_SUCCESS	Функция была успешной.
STATUS_INTERNAL_ERROR	Произошла внутренняя ошибка.
STATUS_INVALID_HANDLE	Недопустимый дескриптор в параметре hSharedSecret.
STATUS_INVALID_PARAMETER	Один или несколько параметров недопустимы.

Замечания

Структура BCryptBufferDesc в параметре pParameterList может содержать несколько параметров KDF_SECRET_PREPEND и KDF_SECRET_APPEND. Если задано несколько этих параметров, значения параметров объединяются в порядке, в котором они содержатся в массиве перед вызовом KDF. Например, предположим, что указаны следующие значения параметров.

BYTE pbValue0[1] = {0x01};
BYTE pbValue1[2] = {0x04, 0x05};
BYTE pbValue2[3] = {0x10, 0x11, 0x12};
BYTE pbValue3[4] = {0x20, 0x21, 0x22, 0x23};

Parameter[0].type = KDF_SECRET_APPEND
Parameter[0].value = pbValue0;
Parameter[0].length = sizeof  (pbValue0);
Parameter[1].type = KDF_SECRET_PREPEND
Parameter[1].value = pbValue1;
Parameter[1].length = sizeof (pbValue1);
Parameter[2].type = KDF_SECRET_APPEND
Parameter[2].value = pbValue2;
Parameter[2].length = sizeof (pbValue2);
Parameter[3].type = KDF_SECRET_PREPEND
Parameter[3].value = pbValue3;
Parameter[3].length = sizeof (pbValue3);

Если указаны указанные выше значения параметров, то сцепленные значения с фактическим KDF приведены следующим образом.

Type: KDF_SECRET_PREPEND
Value: {0x04, 0x05, 0x20, 0x21, 0x22, 0x23}, length 6

Type: KDF_SECRET_APPEND
Value: {0x01, 0x10, 0x11, 0x12}, length 4

Если параметр pwszKDF имеет значение BCRYPT_KDF_RAW_SECRET, возвращенный секрет (в отличие от других значений pwszKDF) будет закодирован в малоконечном формате. Важно учитывать это при использовании необработанного секрета в любых других функциях CNG, так как большинство из них принимают в кодированные входные данные в большом коде.

В зависимости от того, какие режимы процессора поддерживает поставщик, BCryptDeriveKey можно вызывать из пользовательского режима или режима ядра. Вызывающие серверы режима ядра могут выполняться в PASSIVE_LEVELIRQL или DISPATCH_LEVEL IRQL. Если текущий уровень IRQL DISPATCH_LEVEL, дескриптор, предоставленный в параметре hSharedSecret, должен находиться в непакованной памяти (или заблокированной) памяти и должен быть производным от дескриптора алгоритма, возвращенного поставщиком, который был открыт с помощью флага BCRYPT_PROV_DISPATCH.

Чтобы вызвать эту функцию в режиме ядра, используйте Cng.lib, которая входит в состав пакета средств разработки драйверов (DDK). Windows Server 2008 и Windows Vista: для вызова этой функции в режиме ядра используйте Ksecdd.lib.

Требования

Требование	Ценность
минимальные поддерживаемые клиентские	Windows Vista [классические приложения \| Приложения UWP]
минимальный поддерживаемый сервер	Windows Server 2008 [классические приложения \| Приложения UWP]
целевая платформа	Виндоус
заголовка	bcrypt.h
библиотеки	Bcrypt.lib
DLL	Bcrypt.dll

См. также

BCryptSecretAgreement

Поделиться через

Функция BCryptDeriveKey (bcrypt.h)

Синтаксис

Параметры

BCRYPT_KDF_HASH (L"HASH")

BCRYPT_KDF_HMAC (L"HMAC")

BCRYPT_KDF_TLS_PRF (L"TLS_PRF")

BCRYPT_KDF_SP80056A_CONCAT (L"SP800_56A_CONCAT")

BCRYPT_KDF_RAW_SECRET (L"TRUNCATE")

Возвращаемое значение

Замечания

Требования

См. также

Обратная связь

Дополнительные ресурсы