Функция CryptExportKey (wincrypt.h)
Дескриптор ключа для экспорта передается функции, а функция возвращает большой двоичный объект ключа. Этот ключевой BLOB-объект может быть отправлен через небезопасный транспорт или храниться в небезопасном расположении хранилища. Эта функция может экспортировать ключ сеанса Schannel , обычный ключ сеанса, открытый ключ или пару открытого и закрытого ключей. Экспортируйте большой двоичный объект ключа, пока предполагаемый получатель не использует функцию CryptImportKey для импорта ключа или пары ключей в CSP получателя.
Синтаксис
BOOL CryptExportKey(
[in] HCRYPTKEY hKey,
[in] HCRYPTKEY hExpKey,
[in] DWORD dwBlobType,
[in] DWORD dwFlags,
[out] BYTE *pbData,
[in, out] DWORD *pdwDataLen
);
Параметры
[in] hKey
Дескриптор ключа для экспорта.
[in] hExpKey
Дескриптор криптографического ключа целевого пользователя. Данные ключа в экспортируемом blOB-объекте ключа шифруются с помощью этого ключа. Это гарантирует, что только конечный пользователь сможет использовать ключевой BLOB-объект. HExpKey и hKey должны поступать из одного поставщика служб конфигурации.
Чаще всего это открытый ключ обмена ключами целевого пользователя. Однако некоторые протоколы в некоторых CSP требуют, чтобы для этой цели использовался ключ сеанса, принадлежащий конечному пользователю.
Если тип ключа BLOB, заданный параметром dwBlobType , — PUBLICKEYBLOB, этот параметр не используется и должен иметь нулевое значение.
Если тип ключа BLOB, заданный параметром dwBlobType , — PRIVATEKEYBLOB, обычно это дескриптор сеансового ключа, который должен использоваться для шифрования ключа BLOB. Некоторые поставщики служб конфигурации допускают нулевое значение этого параметра. В этом случае приложение должно зашифровать большой двоичный объект закрытого ключа вручную, чтобы защитить его.
Сведения о том, как поставщики служб шифрования Майкрософт реагируют на этот параметр, см. в разделах о blOB-объектах закрытого ключастатьи Поставщики служб шифрования Майкрософт.
[in] dwBlobType
Указывает тип ключа BLOB для экспорта в pbData. Это должна быть одна из следующих констант, как описано в разделе Хранилище криптографических ключей и Exchange.
| Значение | Значение |
|---|---|
|
Используется для хранения ключей сеанса в Schannel CSP или в любом другом формате, зависят от поставщика. OPAQUEKEYBLOB не являются передаваемыми и должны использоваться в CSP, создавшей большой двоичный объект. |
|
Используется для передачи пар открытого и закрытого ключей. |
|
Используется для передачи открытых ключей. |
|
Используется для передачи ключей сеанса. |
|
ОБЪЕКТ PLAINTEXTKEYBLOB, используемый для экспорта любого ключа, поддерживаемого используемым поставщиком служб конфигурации. |
|
Используется для экспорта и импорта симметричного ключа , заключенного в другой симметричный ключ. Фактический ключ в оболочке имеет формат, указанный в стандарте RFC 3217 IETF. |
[in] dwFlags
Задает дополнительные параметры для функции. Этот параметр может быть равен нулю или сочетанию одного или нескольких из следующих значений.
| Значение | Значение |
|---|---|
|
Этот флаг заставляет эту функцию экспортировать версию 3 типа BLOB. |
|
Этот флаг уничтожает исходный ключ в OPAQUEKEYBLOB. Этот флаг доступен только в Schannel CSP. |
|
Этот флаг приводит к созданию форматирования PKCS #1 версии 2 с шифрованием и расшифровкой RSA при экспорте SIMPLEBLOB. |
|
Первые восемь байтов заполнения блока шифрования RSA должны иметь значение 0x03, а не случайные данные. Это предотвращает откаты версий и рассматривается в спецификации SSL3. Этот флаг доступен только для Schannel CSP. |
|
Этот флаг не используется. |
[out] pbData
Указатель на буфер, который получает ключевые данные БОЛЬШОГО ДВОИЧНОГО ОБЪЕКТА . Формат этого большого двоичного объекта зависит от типа большого двоичного объекта, запрошенного в параметре dwBlobType . Формат для PRIVATEKEYBLOB, PUBLICKEYBLOB и SIMPLEBLOB см. в разделе Базовые BLOB-объекты ключа поставщика.
Если этот параметр имеет значение NULL, требуемый размер буфера помещается в значение, на которое указывает параметр pdwDataLen . Дополнительные сведения см. в разделе Извлечение данных неизвестной длины.
[in, out] pdwDataLen
Указатель на значение DWORD , которое в записи содержит размер буфера в байтах, на который указывает параметр pbData . При возврате функции это значение содержит количество байтов, хранящихся в буфере.
Возвращаемое значение
Если функция выполняется успешно, функция возвращает ненулевое значение (TRUE).
Если функция завершается сбоем, она возвращает ноль (FALSE). Для получения дополнительных сведений об ошибке вызовите Метод GetLastError.
Коды ошибок, предваряемые "NTE", создаются конкретным поставщиком служб конфигурации. В следующей таблице показаны некоторые возможные коды ошибок.
| Код возврата | Описание |
|---|---|
|
Один из параметров указывает недопустимый дескриптор. |
|
Один из параметров содержит недопустимое значение. Чаще всего это недопустимый указатель. |
|
Если буфер, заданный параметром pbData , недостаточно велик для хранения возвращаемых данных, функция задает код ERROR_MORE_DATA и сохраняет требуемый размер буфера в байтах в переменной, на которую указывает pdwDataLen. |
|
Либо алгоритм, который работает с открытым ключом для экспорта, не поддерживается этим поставщиком служб конфигурации, либо предпринята попытка экспортировать сеансовый ключ, зашифрованный с помощью другого открытого ключа. |
|
Параметр dwFlags не равен нулю. |
|
Один или оба ключа, указанные hKey и hExpKey , недопустимы. |
|
У вас нет разрешения на экспорт ключа. То есть при создании ключа hKey флаг CRYPT_EXPORTABLE не был указан. |
|
Тип ключа BLOB , заданный dwBlobType , — PUBLICKEYBLOB, но hExpKey не содержит дескриптор открытого ключа. |
|
Параметр dwBlobType указывает неизвестный тип BLOB. |
|
Не удается найти контекст CSP, указанный при создании ключа hKey . |
|
Ключ сеанса экспортируется, а параметр hExpKey не указывает открытый ключ. |
Комментарии
Для любых перестановок клавиш DES, использующих ОБЪЕКТ PLAINTEXTKEYBLOB, можно экспортировать только полный размер ключа, включая бит четности. Поддерживаются следующие размеры ключей.
| Алгоритм | Поддерживаемый размер ключа |
|---|---|
| CALG_DES | 64 бита |
| CALG_3DES_112 | 128 бит |
| CALG_3DES | 192 бит |
Примеры
В следующем примере показано, как экспортировать криптографический ключ или пару ключей более безопасным способом. В этом примере предполагается, что был получен криптографический контекст и открытый ключ доступен для экспорта. Пример, включающий полный контекст для использования этой функции, см. в разделе Пример программы C: подписывание хэша и проверка хэш-подписи. Еще один пример использования этой функции см. в разделе Пример программы C: экспорт ключа сеанса.
#include <windows.h>
#include <stdio.h>
#include <Wincrypt.h>
BOOL GetExportedKey(
HCRYPTKEY hKey,
DWORD dwBlobType,
LPBYTE *ppbKeyBlob,
LPDWORD pdwBlobLen)
{
DWORD dwBlobLength;
*ppbKeyBlob = NULL;
*pdwBlobLen = 0;
// Export the public key. Here the public key is exported to a
// PUBLICKEYBLOB. This BLOB can be written to a file and
// sent to another user.
if(CryptExportKey(
hKey,
NULL,
dwBlobType,
0,
NULL,
&dwBlobLength))
{
printf("Size of the BLOB for the public key determined. \n");
}
else
{
printf("Error computing BLOB length.\n");
return FALSE;
}
// Allocate memory for the pbKeyBlob.
if(*ppbKeyBlob = (LPBYTE)malloc(dwBlobLength))
{
printf("Memory has been allocated for the BLOB. \n");
}
else
{
printf("Out of memory. \n");
return FALSE;
}
// Do the actual exporting into the key BLOB.
if(CryptExportKey(
hKey,
NULL,
dwBlobType,
0,
*ppbKeyBlob,
&dwBlobLength))
{
printf("Contents have been written to the BLOB. \n");
*pdwBlobLen = dwBlobLength;
}
else
{
printf("Error exporting key.\n");
free(*ppbKeyBlob);
*ppbKeyBlob = NULL;
return FALSE;
}
return TRUE;
}
Требования
| Требование | Значение |
|---|---|
| Минимальная версия клиента | Windows XP [только классические приложения] |
| Минимальная версия сервера | Windows Server 2003 [только классические приложения] |
| Целевая платформа | Windows |
| Header | wincrypt.h |
| Библиотека | Advapi32.lib |
| DLL | Advapi32.dll |