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

Статья
05/29/2024

Функция NCryptImportKey импортирует ключ API шифрования следующего поколения (CNG) из большого двоичного объекта памяти.

Синтаксис

SECURITY_STATUS NCryptImportKey(
  [in]           NCRYPT_PROV_HANDLE hProvider,
  [in, optional] NCRYPT_KEY_HANDLE  hImportKey,
  [in]           LPCWSTR            pszBlobType,
  [in, optional] NCryptBufferDesc   *pParameterList,
  [out]          NCRYPT_KEY_HANDLE  *phKey,
  [in]           PBYTE              pbData,
  [in]           DWORD              cbData,
  [in]           DWORD              dwFlags
);

Параметры

[in] hProvider

Дескриптор поставщика хранилища ключей.

[in, optional] hImportKey

Дескриптор криптографического ключа , с помощью которого были зашифрованы данные ключа в импортированном большом двоичном объекте . Это должен быть дескриптор того же ключа, который был передан в параметре hExportKey функции NCryptExportKey . Если этот параметр имеет значение NULL, предполагается, что blOB-объект ключа не шифруется.

[in] pszBlobType

Строка Юникода, заканчивающаяся null, которая содержит идентификатор, указывающий формат ключа BLOB. Эти форматы относятся к конкретному поставщику хранилища ключей. Сведения о форматах BLOB, поддерживаемых поставщиками Майкрософт, см. в разделе Примечания.

[in, optional] pParameterList

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

[out] phKey

Адрес переменной NCRYPT_KEY_HANDLE , получающей дескриптор ключа. Завершив использование этого дескриптора, отпустите его, передав его в функцию NCryptFreeObject .

[in] pbData

Адрес буфера, содержащего blOB-объект ключа для импорта. Параметр cbData содержит размер этого буфера.

[in] cbData

Размер буфера pbData (в байтах).

[in] dwFlags

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

Значение	Значение
NCRYPT_SILENT_FLAG	Запрашивает, чтобы поставщик служб ключей (KSP) не отображал пользовательский интерфейс. Если поставщик должен отображать пользовательский интерфейс для работы, вызов завершается сбоем, а KSP должен задать код ошибки NTE_SILENT_CONTEXT как последнюю ошибку.
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 недоступен.
NTE_VBS_CANNOT_DECRYPT_KEY	Сбой операции расшифровки VBS.

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

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

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

Microsoft Software KSP
Поставщик ключевых показателей эффективности смарт-карт Майкрософт

Microsoft Software KSP

Следующие константы поддерживаются поставщиком программного обеспечения Майкрософт для параметра pszBlobType .

Если имя ключа не указано, microsoft Software KSP обрабатывает ключ как временный и не сохраняет его постоянно. Для типа NCRYPT_OPAQUETRANSPORT_BLOB имя ключа сохраняется в большом двоичном объекте при экспорте. Для других форматов BLOB имя можно указать в параметре буфера NCRYPTBUFFER_PKCS_KEY_NAME в параметре pParameterList .

В Windows Server 2008 и Windows Vista с помощью приведенного выше метода можно сохранять только ключи, импортированные в виде больших двоичных объектов с конвертом PKCS #7 (NCRYPT_PKCS7_ENVELOPE_BLOB) или PKCS #8 (NCRYPT_PKCS8_PRIVATE_KEY_BLOB). Чтобы сохранить ключи, импортированные с помощью других типов BLOB на этих платформах, используйте метод, описанный в разделе Импорт и экспорт ключей.

Следующие флаги поддерживаются этим поставщиком ключей.

Термин	Описание
NCRYPT_NO_KEY_VALIDATION	Не проверяйте открытую часть пары ключей. Этот флаг применяется только к парам открытых и закрытых ключей.
NCRYPT_DO_NOT_FINALIZE_FLAG	Не завершайте работу ключа. Этот параметр полезен, когда необходимо добавить или изменить свойства ключа после его импорта. Необходимо завершить работу ключа, прежде чем его можно будет использовать, передав дескриптор ключа в функцию NCryptFinalizeKey . Этот флаг поддерживается для закрытых ключей PKCS 7 и PKCS 8, но не для открытых ключей.
NCRYPT_MACHINE_KEY_FLAG	Ключ применяется к локальному компьютеру. Если этот флаг отсутствует, ключ применяется к текущему пользователю.
NCRYPT_OVERWRITE_KEY_FLAG	Если ключ уже существует в контейнере с указанным именем, существующий ключ будет перезаписан. Если этот флаг не указан и ключ с указанным именем уже существует, эта функция вернет NTE_EXISTS.
NCRYPT_WRITE_KEY_TO_LEGACY_STORE_FLAG	Кроме того, сохраните ключ в хранилище прежних версий. Это позволяет использовать ключ с CryptoAPI. Этот флаг применяется только к ключам RSA.

Поставщик ключевых показателей эффективности смарт-карт Майкрософт

Набор форматов и флагов ключевых BLOB-объектов, поддерживаемых этим поставщиком служб KSP, идентичен набору, поддерживаемму поставщиком программного обеспечения Майкрософт.

В Windows Server 2008 и Windows Vista поставщик параметров microsoft Smart Card KSP импортирует все ключи в KSP программного обеспечения Майкрософт. Таким образом, ключи нельзя сохранить на смарт-карте с помощью этого API, и рекомендации, приведенные в приведенном выше разделе, применимы при попытке сохранить ключи в поставщике программного обеспечения Майкрософт.

В Windows Server 2008 R2 и Windows 7 поставщик хранилища ключей смарт-карт Майкрософт может импортировать закрытый ключ на смарт-карту при условии выполнения следующих условий:

Имя контейнера ключей на карточке является допустимым.
Смарт-карта поддерживает импорт закрытых ключей.
Для следующих двух разделов реестра задано значение DWORD :0x1
- HKLM\SOFTWARE\Microsoft\Cryptography\Defaults\Provider\Microsoft Base Smart Card Crypto Provider\AllowPrivateExchangeKeyImport
- HKLM\SOFTWARE\Microsoft\Cryptography\Defaults\Provider\Microsoft Base Smart Card Crypto Provider\AllowPrivateSignatureKeyImport

Если имя контейнера ключей имеет значение NULL, поставщик служб microsoft Smart Card KSP обрабатывает ключ как временный и импортирует его в KSP программного обеспечения Майкрософт.

Дополнительные требования к оборудованию для ключей 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

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

NCryptBuffer

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