Функция NCryptCreatePersistedKey (ncrypt.h)
Функция 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 недоступен. (*См. примечания) |
| NCRYPT_USE_PER_BOOT_KEY_FLAG | Дополнительный флаг, который можно использовать вместе с NCRYPT_REQUIRE_VBS_FLAG или NCRYPT_PREFER_VBS_FLAG. Указывает безопасности на основе виртуализации (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 |