Функция NCryptDeriveKey (ncrypt.h)

Статья
08/25/2023

Функция NCryptDeriveKey наследует ключ из значения соглашения секрета. Эта функция предназначена для использования в рамках процедуры секретного соглашения с использованием сохраненных ключей секретного соглашения. Чтобы получить материал ключа с помощью сохраненного секрета, используйте функцию NCryptKeyDerivation .

Синтаксис

SECURITY_STATUS NCryptDeriveKey(
  [in]            NCRYPT_SECRET_HANDLE hSharedSecret,
  [in]            LPCWSTR              pwszKDF,
  [in, optional]  NCryptBufferDesc     *pParameterList,
  [out, optional] PBYTE                pbDerivedKey,
  [in]            DWORD                cbDerivedKey,
  [out]           DWORD                *pcbResult,
  [in]            ULONG                dwFlags
);

Параметры

[in] hSharedSecret

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

[in] pwszKDF

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

BCRYPT_KDF_HASH (L"HASH")

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

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

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

Параметр	Описание	Обязательный или необязательный
KDF_HASH_ALGORITHM	Строка Юникода, завершающаяся нулевым значением, идентифицирующая используемый хэш-алгоритм. Это может быть один из стандартных идентификаторов хэш-алгоритма из идентификаторов алгоритма 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	Строка Юникода, завершающаяся нулевым значением, идентифицирующая используемый хэш-алгоритм. Это может быть один из стандартных идентификаторов хэш-алгоритма из идентификаторов алгоритма 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 выполняется, как показано в следующем псевдокоде.

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: Это значение не поддерживается.

[in, optional] pParameterList

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

[out, optional] pbDerivedKey

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

[in] cbDerivedKey

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

[out] pcbResult

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

[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 .

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

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

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

Код возврата	Описание
ERROR_SUCCESS	Функция выполнена успешно.
NTE_INVALID_HANDLE	Недопустимый параметр hSharedSecret .
NTE_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

Служба не должна вызывать эту функцию из функции StartService. Если служба вызывает эту функцию из функции StartService, может возникнуть взаимоблокировка, и служба может перестать отвечать.

Требования

Требование	Значение
Минимальная версия клиента	Windows Vista [классические приложения \| Приложения UWP]
Минимальная версия сервера	Windows Server 2008 [классические приложения \| Приложения UWP]
Целевая платформа	Windows
Header	ncrypt.h
Библиотека	Ncrypt.lib
DLL	Ncrypt.dll

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

NCryptBufferDesc

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

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

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

Комментарии

Требования

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

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

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