Функция CryptImportKey (wincrypt.h)
Синтаксис
BOOL CryptImportKey(
[in] HCRYPTPROV hProv,
[in] const BYTE *pbData,
[in] DWORD dwDataLen,
[in] HCRYPTKEY hPubKey,
[in] DWORD dwFlags,
[out] HCRYPTKEY *phKey
);
Параметры
[in] hProv
Дескриптор CSP, полученный с помощью функции CryptAcquireContext .
[in] pbData
Массив BYTE , содержащий заголовок BLOB-объекта PUBLICKEYSTRUC , за которым следует зашифрованный ключ. Этот ключ BLOB создается функцией CryptExportKey либо в этом приложении, либо другим приложением, которое, возможно, выполняется на другом компьютере.
[in] dwDataLen
Содержит длину ключа BLOB в байтах.
[in] hPubKey
Дескриптор криптографического ключа, который расшифровывает ключ, хранящийся в pbData. Этот ключ должен поступать из того же CSP, на который ссылается hProv . Значение этого параметра зависит от типа CSP и типа импортируемого большого двоичного объекта ключа:
- Если BLOB-объект ключа зашифрован с помощью пары ключей обмена ключами, например SIMPLEBLOB, этот параметр может быть дескриптором ключа обмена ключами.
- Если большой двоичный объект ключа зашифрован с помощью ключа сеанса, например зашифрованного PRIVATEKEYBLOB, этот параметр содержит дескриптор этого ключа сеанса.
- Если blOB-объект ключа не зашифрован, например PUBLICKEYBLOB, этот параметр не используется и должен иметь нулевое значение.
- Если большой двоичный объект ключа зашифрован с помощью ключа сеанса в Schannel CSP, например зашифрованного OPAQUEKEYBLOB или любого другого поставщика OPAQUEKEYBLOB, этот параметр не используется и должен быть равен нулю.
[in] dwFlags
В настоящее время используется только при импорте пары открытого и закрытого ключей в формате PRIVATEKEYBLOB в CSP.
Этот параметр может принимать одно из указанных ниже значений.
| Значение | Значение |
|---|---|
|
В конечном итоге импортируемый ключ будет реэкспортирован. Если этот флаг не используется, вызовы CryptExportKey с дескриптором ключа завершаются ошибкой. |
|
Этот флаг вызывает проверку форматирования PKCS #1 версии 2 с шифрованием и расшифровкой RSA при импорте SIMPLEBLOB. |
|
Значение без соли выделяется для 40-разрядного симметричного ключа. Дополнительные сведения см. в разделе Функции соляного значения. |
|
Если этот флаг установлен, поставщик CSP уведомляет пользователя с помощью диалогового окна или другого метода при попытке выполнения определенных действий с помощью этого ключа. Точное поведение определяется CSP или используемым типом CSP. Если контекст поставщика был получен с CRYPT_SILENT задан, использование этого флага приведет к сбою, а последняя ошибка имеет значение NTE_SILENT_CONTEXT. |
|
Позволяет импортировать ключ RC2 размером более 16 байт. Если этот флаг не задан, вызовы функции CryptImportKey с ключами RC2, превышающими 16 байт, завершаются сбоем, и вызов GetLastError вернет NTE_BAD_DATA. |
[out] phKey
Указатель на значение HCRYPTKEY , которое получает дескриптор импортированного ключа. Завершив использование ключа, отпустите дескриптор, вызвав функцию CryptDeographyKey .
Возвращаемое значение
Если функция выполнена успешно, функция возвращает ненулевое значение.
Если функция завершается сбоем, она возвращает ноль. Чтобы получить дополнительные сведения об ошибке, вызовите Метод GetLastError.
Коды ошибок, предваряемые "NTE", создаются конкретным поставщиком служб CSP. Ниже приведены некоторые возможные коды ошибок.
| Код возврата | Описание |
|---|---|
|
Некоторые поставщики служб конфигурации устанавливают эту ошибку, если закрытый ключ импортируется в контейнер, а другой поток или процесс использует этот ключ. |
|
Один из параметров указывает недопустимый дескриптор. |
|
Один из параметров содержит недопустимое значение. Чаще всего это недопустимый указатель. |
|
Импортируемый простой blOB-объект ключа не шифруется с помощью ожидаемого алгоритма обмена ключами. |
|
Либо алгоритм, который работает с импортируемым открытым ключом, не поддерживается этим поставщиком служб CSP, либо предпринята попытка импортировать ключ сеанса, зашифрованный с помощью другого открытого ключа. |
|
Указанный параметр dwFlags недопустим. |
|
Тип ключа BLOB не поддерживается этим поставщиком служб CSP и, возможно, недопустим. |
|
Параметр hProv не содержит допустимый дескриптор контекста. |
|
Номер версии ключевого BLOB-объекта не соответствует версии CSP. Обычно это означает, что поставщик служб CSP необходимо обновить. |
Комментарии
При импорте ключа HMAC вызывающий объект должен определить импортированный ключ как тип PLAINTEXTKEYBLOB и задать соответствующий идентификатор алгоритма в поле aiKeyAlg заголовка BLOB PUBLICKEYSTRUC.
Функцию CryptImportKey можно использовать для импорта ключа в виде открытого текста для симметричного алгоритма; однако для простоты использования рекомендуется использовать функцию CryptGenKey . При импорте ключа в виде открытого текста структура большого двоичного объекта ключа, передаваемого в параметре pbData , представляет собой PLAINTEXTKEYBLOB.
Тип PLAINTEXTKEYBLOB можно использовать с любым алгоритмом или типом сочетания ключей, поддерживаемых используемым поставщиком служб CSP.
Пример импорта открытого ключа см. в разделе Пример программы C. Импорт открытого ключа.
В следующем примере показано, как задать поля заголовка.
keyBlob.header.bType = PLAINTEXTKEYBLOB;
keyBlob.header.bVersion = CUR_BLOB_VERSION;
keyBlob.header.reserved = 0;
// CALG_AES_128 is used as an example. You would set this to the
// algorithm id that corresponds to the one used by the key.
keyBlob.header.aiKeyAlg = CALG_AES_128;
Длина ключа указывается в файле keyBlob.keyLength, за которым следуют фактические данные ключа.
Поддерживаются следующие размеры ключей.
| Алгоритм | Поддерживаемый размер ключа |
|---|---|
| CALG_DES | 64 бита |
| CALG_3DES_112 | 128 бит |
| CALG_3DES | 192 бит |
Примеры
В следующем примере показано, как импортировать ключ из большого двоичного объекта ключа. Полный пример этой функции см. в разделе Пример программы C: подписывание хэша и проверка хэш-подписи. Дополнительные сведения о коде, в котором используется эта функция, см. в разделе Пример программы C: расшифровка файла.
#include <windows.h>
#include <stdio.h>
#include <Wincrypt.h>
BOOL ImportKey(HCRYPTPROV hProv, LPBYTE pbKeyBlob, DWORD dwBlobLen)
{
HCRYPTKEY hPubKey;
//---------------------------------------------------------------
// This code assumes that a cryptographic provider (hProv)
// has been acquired and that a key BLOB (pbKeyBlob) that is
// dwBlobLen bytes long has been acquired.
//---------------------------------------------------------------
// Get the public key of the user who created the digital
// signature and import it into the CSP by using CryptImportKey.
// The key to be imported is in the buffer pbKeyBlob that is
// dwBlobLen bytes long. This function returns a handle to the
// public key in hPubKey.
if(CryptImportKey(
hProv,
pbKeyBlob,
dwBlobLen,
0,
0,
&hPubKey))
{
printf("The key has been imported.\n");
}
else
{
printf("Public key import failed.\n");
return FALSE;
}
//---------------------------------------------------------------
// Insert code that uses the imported public key here.
//---------------------------------------------------------------
//---------------------------------------------------------------
// When you have finished using the key, you must release it.
if(CryptDestroyKey(hPubKey))
{
printf("The public key has been released.");
}
else
{
printf("The public key has not been released.");
return FALSE;
}
return TRUE;
}
Требования
| Требование | Значение |
|---|---|
| Минимальная версия клиента | Windows XP [только классические приложения] |
| Минимальная версия сервера | Windows Server 2003 [только классические приложения] |
| Целевая платформа | Windows |
| Header | wincrypt.h |
| Библиотека | Advapi32.lib |
| DLL | Advapi32.dll |
См. также раздел
Обратная связь
Ожидается в ближайшее время: в течение 2024 года мы постепенно откажемся от GitHub Issues как механизма обратной связи для контента и заменим его новой системой обратной связи. Дополнительные сведения см. в разделе https://aka.ms/ContentUserFeedback.
Отправить и просмотреть отзыв по