Функция BCryptImportKey (bcrypt.h)

Статья
07/16/2024

Функция BCryptImportKey импортирует симметричный ключ из ключа BLOB. Функция BCryptImportKeyPair используется для импорта пары открытых и закрытых ключей.

Синтаксис

NTSTATUS BCryptImportKey(
  [in]            BCRYPT_ALG_HANDLE hAlgorithm,
  [in, optional]  BCRYPT_KEY_HANDLE hImportKey,
  [in]            LPCWSTR           pszBlobType,
  [out]           BCRYPT_KEY_HANDLE *phKey,
  [out, optional] PUCHAR            pbKeyObject,
  [in]            ULONG             cbKeyObject,
  [in]            PUCHAR            pbInput,
  [in]            ULONG             cbInput,
  [in]            ULONG             dwFlags
);

Параметры

[in] hAlgorithm

Дескриптор поставщика алгоритма для импорта ключа. Этот дескриптор получается путем вызова функции BCryptOpenAlgorithmProvider.

[in, optional] hImportKey

Дескриптор ключа шифрования ключа, необходимый для распаковки ключа BLOB-объекта в параметре pbInput.

примечание Дескриптор должен предоставляться тем же поставщиком, который предоставил импортируемый ключ.

Windows Server 2008 и Windows Vista: Этот параметр не используется и должен иметь значение NULL.

[in] pszBlobType

Строка Юникода, завершающая значение NULL, содержащая идентификатор, указывающий тип БОЛЬШОго двоичного объекта, содержащегося в буфере pbInput. Это может быть одно из следующих значений.

Ценность	Значение
BCRYPT_AES_WRAP_KEY_BLOB	Импорт симметричного ключа из ключа AES, упаковаемого в большой двоичный объект. Параметр hImportKey должен ссылаться на допустимый указатель BCRYPT_KEY_HANDLE на ключ шифрования ключей. Windows Server 2008 и Windows Vista: этот тип BLOB-объектов не поддерживается.
BCRYPT_KEY_DATA_BLOB	Импорт симметричного ключа из BLOB-объекта данных. Параметр pbInput — это указатель на структуру BCRYPT_KEY_DATA_BLOB_HEADER сразу после ключа BLOB.
BCRYPT_OPAQUE_KEY_BLOB	Импортируйте симметричный ключ BLOB в формате, относящееся к одному поставщику служб CSP. Непрозрачные BLOB-объекты не переносимы и должны быть импортированы с помощью того же поставщика служб CSP, который создал БОЛЬШОЙ ДВОИЧНЫй объект. Непрозрачные BLOB-объекты предназначены только для межпроцессного передачи ключей и не подходят для сохранения и чтения в разных версиях поставщика.

[out] phKey

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

[out, optional] pbKeyObject

Указатель на буфер, получающий импортированный объект ключа. Параметр cbKeyObject содержит размер этого буфера. Требуемый размер этого буфера можно получить путем вызова функции BCryptGetProperty для получения свойства BCRYPT_OBJECT_LENGTH. Это обеспечит размер ключевого объекта для указанного алгоритма.

Эта память может быть освобождена только после того, как дескриптор ключа phKey будет уничтожен.

[in] cbKeyObject

Размер в байтах буфера pbKeyObject.

[in] pbInput

Адрес буфера, содержащего ключевой BLOB-объект для импорта. Параметр cbInput содержит размер этого буфера. Параметр pszBlobType указывает тип ключа BLOB, который содержит этот буфер.

[in] cbInput

Размер pbInput буфера в байтах.

[in] dwFlags

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

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

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

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

Возвращаемый код	Описание
STATUS_SUCCESS	Функция была успешной.
STATUS_BUFFER_TOO_SMALL	Размер ключевого объекта, указанного параметром cbKeyObject, недостаточно велик для хранения ключевого объекта.
STATUS_INVALID_HANDLE	Дескриптор алгоритма в параметре hAlgorithm недопустим.
STATUS_INVALID_PARAMETER	Один или несколько параметров недопустимы.
STATUS_NOT_SUPPORTED	Поставщик алгоритмов, указанный параметром hAlgorithm , не поддерживает тип BLOB, указанный параметром pszBlobType.

Замечания

В зависимости от того, какие режимы процессора поддерживает поставщик, BCryptImportKey можно вызывать из пользовательского режима или режима ядра. Вызывающие серверы режима ядра могут выполняться в PASSIVE_LEVELIRQL или DISPATCH_LEVEL IRQL. Если текущий уровень IRQL DISPATCH_LEVEL, то дескриптор, предоставленный в параметре hAlgorithm, должен быть открыт с помощью флага BCRYPT_PROV_DISPATCH, а все указатели, передаваемые в функцию BCryptImportKey, должны ссылаться на неупакованную (или заблокированную) память.

Чтобы вызвать эту функцию в режиме ядра, используйте Cng.lib, которая входит в состав пакета средств разработки драйверов (DDK). Windows Server 2008 и Windows Vista: для вызова этой функции в режиме ядра используйте Ksecdd.lib.

Требования

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

См. также

BCryptDeskkey

BCryptExportKey

BCryptImportKeyPair

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