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

Статья
08/25/2023

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

Синтаксис

SECURITY_STATUS NCryptKeyDerivation(
  [in]  NCRYPT_KEY_HANDLE hKey,
  [in]  NCryptBufferDesc  *pParameterList,
  [out] PUCHAR            pbDerivedKey,
  [in]  DWORD             cbDerivedKey,
  [out] DWORD             *pcbResult,
  [in]  ULONG             dwFlags
);

Параметры

[in] hKey

Дескриптор ключа функции производной функции (KDF).

[in] pParameterList

Адрес структуры NCryptBufferDesc , содержащей параметры KDF. Параметры могут быть характерными для KDF или универсальными. В следующей таблице показаны обязательные и необязательные параметры для конкретных KDF, реализованных поставщиком хранилища ключей программного обеспечения Майкрософт.

KDF	Параметр	Обязательно
SP800-108 HMAC в режиме счетчика	KDF_LABEL	да
	KDF_CONTEXT	да
	KDF_HASH_ALGORITHM	да
SP800-56A	KDF_ALGORITHMID	да
	KDF_PARTYUINFO	да
	KDF_PARTYVINFO	да
	KDF_HASH_ALGORITHM	да
	KDF_SUPPPUBINFO	нет
	KDF_SUPPPRIVINFO	нет
PBKDF2	KDF_HASH_ALGORITHM	да
	KDF_SALT	да
	KDF_ITERATION_COUNT	нет
CAPI_KDF	KDF_HASH_ALGORITHM	да

Можно использовать следующий универсальный параметр:

KDF_GENERIC_PARAMETER

Универсальные параметры сопоставляют с конкретными параметрами KDF следующим образом:

SP800-108 HMAC в режиме счетчика:

KDF_GENERIC_PARAMETER = KDF_LABEL||0x00||KDF_CONTEXT

SP800-56A

KDF_GENERIC_PARAMETER = KDF_ALGORITHMID || KDF_PARTYUINFO || KDF_PARTYVINFO {|| KDF_SUPPPUBINFO } {|| KDF_SUPPPRIVINFO }

PBKDF2

KDF_GENERIC_PARAMETER = KDF_SALT
KDF_ITERATION_COUNT — по умолчанию — 10000

CAPI_KDF

KDF_GENERIC_PARAMETER = не используется

[out] pbDerivedKey

Адрес буфера, получающего ключ. Параметр cbDerivedKey содержит размер буфера ключей в байтах.

[in] cbDerivedKey

Размер (в байтах) буфера, на который указывает параметр pbDerivedKey .

[out] pcbResult

Указатель на DWORD , который получает количество байтов, скопированных в буфер, на который указывает параметр pbDerivedKey .

[in] dwFlags

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

Значение	Значение
BCRYPT_CAPI_AES_FLAG	Указывает, что целевым алгоритмом является AES и поэтому ключ должен быть развернут дважды. Этот флаг действителен только с алгоритмом CAPI_KDF.
NCRYPT_SILENT_FLAG	Запрашивает, чтобы поставщик служб ключей (KSP) не отображал пользовательский интерфейс. Если поставщик должен отобразить пользовательский интерфейс для работы, вызов завершается ошибкой и KSP должен задать код ошибки NTE_SILENT_CONTEXT в качестве последней ошибки.

Значение

BCRYPT_CAPI_AES_FLAG

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

NCRYPT_SILENT_FLAG

Запрашивает, чтобы поставщик служб ключей (KSP) не отображал пользовательский интерфейс. Если поставщик должен отобразить пользовательский интерфейс для работы, вызов завершается ошибкой и KSP должен задать код ошибки NTE_SILENT_CONTEXT в качестве последней ошибки.

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

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

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

Код возврата	Описание
ERROR_SUCCESS	Функция выполнена успешно.
NTE_INVALID_HANDLE	Недопустимые дескрипторы hProvider или hKey .
NTE_INVALID_PARAMETER	Параметры pwszDerivedKeyAlg и pParameterList не могут иметь значение NULL.
NTE_NO_MEMORY	Недостаточно памяти для создания ключа.
NTE_NOT_SUPPORTED	Эта функция не поддерживается поставщиком хранилища ключей.

Требования

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

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

BCryptKeyDerivation

NCryptDeriveKey

Share via