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

Статья
02/13/2024

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

Синтаксис

SECURITY_STATUS NCryptCreatePersistedKey(
  [in]           NCRYPT_PROV_HANDLE hProvider,
  [out]          NCRYPT_KEY_HANDLE  *phKey,
  [in]           LPCWSTR            pszAlgId,
  [in, optional] LPCWSTR            pszKeyName,
  [in]           DWORD              dwLegacyKeySpec,
  [in]           DWORD              dwFlags
);

Параметры

[in] hProvider

Дескриптор поставщика хранилища ключей для создания ключа. Этот дескриптор получается с помощью функции NCryptOpenStorageProvider .

[out] phKey

Адрес переменной NCRYPT_KEY_HANDLE , получающей дескриптор ключа. Завершив использование этого дескриптора, отпустите его, передав его в функцию NCryptFreeObject . Чтобы удалить файл ключа на диске, передайте дескриптор функции NCryptDeleteKey . Это также освободит дескриптор. Поэтому приложения могут передавать дескриптор В NCryptFreeObject или NCryptDeleteKey, но не оба.

[in] pszAlgId

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

[in, optional] pszKeyName

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

[in] dwLegacyKeySpec

Устаревший идентификатор, указывающий тип ключа. Может иметь одно из следующих значений:

Значение	Значение
AT_KEYEXCHANGE	Ключ является ключом обмена ключами.
AT_SIGNATURE	Ключ является ключом подписи.
0	Ключ не является ни одним из указанных выше типов.

[in] dwFlags

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

Значение	Значение
NCRYPT_MACHINE_KEY_FLAG	Ключ применяется к локальному компьютеру. Если этот флаг отсутствует, ключ применяется к текущему пользователю.
NCRYPT_OVERWRITE_KEY_FLAG	Если ключ уже существует в контейнере с указанным именем, существующий ключ будет перезаписан. Если этот флаг не указан и ключ с указанным именем уже существует, эта функция вернет NTE_EXISTS.
NCRYPT_REQUIRE_VBS_FLAG	Указывает, что ключ должен быть защищен с помощью защиты на основе виртуализации (VBS). Если VBS недоступен, операция завершится ошибкой. (*См. примечания)
NCRYPT_PREFER_VBS_FLAG	Указывает, что ключ должен быть защищен с помощью защиты на основе виртуализации (VBS). Операция создаст ключ с программной изоляцией, если VBS недоступен. (*См. примечания)

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

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

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

Код возврата	Описание
ERROR_SUCCESS	Функция выполнена успешно.
NTE_BAD_FLAGS	Параметр dwFlags содержит недопустимое значение.
NTE_EXISTS	Ключ с указанным именем уже существует, и NCRYPT_OVERWRITE_KEY_FLAG не указан.
NTE_INVALID_HANDLE	Недопустимый параметр hProvider .
NTE_INVALID_PARAMETER	Один или несколько параметров недопустимы.
NTE_NO_MEMORY	Произошел сбой выделения памяти.
NTE_VBS_UNAVAILABLE	VBS недоступен.

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

Если вы создаете пару ключей RSA, вы также можете сохранить ключ в хранилище прежних версий, чтобы его можно было использовать с CryptoAPI, передав флаг NCRYPT_WRITE_KEY_TO_LEGACY_STORE_FLAG функции NCryptFinalizeKey после завершения ключа.

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

Дополнительные требования к оборудованию для ключей VBS

Хотя на компьютере может быть установлена соответствующая ОС, для создания и защиты ключей с помощью VBS необходимо выполнить следующие дополнительные требования к оборудованию.

VBS включен (см. раздел Безопасность на основе виртуализации (VBS))
TPM включен
- Для сред без операционной системы требуется TPM 2.0.
- Для сред виртуальных машин поддерживается vTPM (Виртуальный TPM).
Bios необходимо обновить до UEFI с профилем SecureBoot

Дополнительные сведения о требованиях к оборудованию:

VBS имеет несколько требований к оборудованию для запуска, включая Hyper-V (гипервизор Windows), 64-разрядную архитектуру и поддержку IOMMU. Полный список требований к оборудованию VBS можно найти здесь.
Требования к высокозащищенным устройствам можно найти здесь.

Требования

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

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

NCryptDeleteKey

NCryptFinalizeKey

Share via