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

Статья
08/22/2023

Функция 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")

Используйте функцию наследования ключа 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). Размер производного ключа всегда составляет 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

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

[out, optional] pbDerivedKey

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

[in] cbDerivedKey

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

[out] pcbResult

Указатель на ULONG , получающий количество байтов, скопированных в буфер pbDerivedKey . Если параметр pbDerivedKey имеет значение NULL, эта функция поместит требуемый размер в байтах в 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, так как большинство из них принимают входные данные в кодировке big-endian.

В зависимости от того, какие режимы процессора поддерживает поставщик, 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]
Целевая платформа	Windows
Header	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")

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

Комментарии

Требования

См. также раздел

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

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

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