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

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

  • Статья

Функция 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 в качестве последней ошибки.

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

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

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

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

Комментарии

Перед вызовом NCryptKeyDerivation можно использовать следующие идентификаторы алгоритма в функции NCryptCreatePersistedKey:

  • BCRYPT_CAPI_KDF_ALGORITHM
  • BCRYPT_SP800108_CTR_HMAC_ALGORITHM
  • BCRYPT_SP80056A_CONCAT_ALGORITHM
  • BCRYPT_PBKDF2_ALGORITHM

Требования

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

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

BCryptKeyDerivation

NCryptDeriveKey