Бөлісу құралы:

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

Функция 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

Дескриптор криптографического ключа , с помощью которого были зашифрованы данные ключа в импортированном BLOB-объекте . Это должен быть дескриптор того же ключа, который был передан в параметре 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 , может произойти взаимоблокировка, а служба может перестать отвечать.

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

  • KSP программного обеспечения Майкрософт
  • KSP смарт-карты Майкрософт

KSP программного обеспечения Майкрософт

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

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

В Windows Server 2008 и Windows Vista только ключи, импортированные как PKCS #NCRYPT_PKCS8_PRIVATE_KEY_BLOB 7, NCRYPT_PKCS7_ENVELOPE_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.

KSP смарт-карты Майкрософт

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

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

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

  • Допустимое имя контейнера ключа на карточке.
  • Импорт закрытых ключей поддерживается смарт-картой.
  • Для следующих двух разделов реестра задано значение DWORD0x1:
    • 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 имеет несколько требований к оборудованию для выполнения, включая Hyper-V (гипервизор Windows), 64-разрядную архитектуру и поддержку IOMMU. Полный список требований к оборудованию VBS см. здесь.
  • Здесь можно найти требования к высокозащищенным устройствам.

Требования

Требование Ценность
Минимальный поддерживаемый клиент Windows Vista [классические приложения | Приложения UWP]
минимальный поддерживаемый сервер Windows Server 2008 [классические приложения | Приложения UWP]
целевая платформа Виндоус
Заголовок ncrypt.h
Библиотека Ncrypt.lib
Библиотека dll Ncrypt.dll

См. также

NCryptBuffer

NCryptCreatePersistedKey

  • Last updated on