Função CryptExportKey (wincrypt.h)
Um identificador para a chave a ser exportada é passado para a função e a função retorna um BLOB de chave. Esse BLOB de chave pode ser enviado por um transporte não seguro ou armazenado em um local de armazenamento não seguro. Essa função pode exportar uma chave de sessão Schannel , uma chave de sessão regular, uma chave pública ou um par de chaves públicas/privadas. O BLOB de chave a ser exportado é inútil até que o destinatário pretendido use a função CryptImportKey nela para importar a chave ou o par de chaves para o CSP de um destinatário.
Sintaxe
BOOL CryptExportKey(
[in] HCRYPTKEY hKey,
[in] HCRYPTKEY hExpKey,
[in] DWORD dwBlobType,
[in] DWORD dwFlags,
[out] BYTE *pbData,
[in, out] DWORD *pdwDataLen
);
Parâmetros
[in] hKey
Um identificador para a chave a ser exportada.
[in] hExpKey
Um identificador para uma chave criptográfica do usuário de destino. Os principais dados dentro do BLOB de chave exportada são criptografados usando essa chave. Isso garante que apenas o usuário de destino seja capaz de usar o BLOB de chave. HExpKey e hKey devem vir do mesmo CSP.
Na maioria das vezes, essa é a chave pública de troca de chaves do usuário de destino. No entanto, determinados protocolos em alguns CSPs exigem que uma chave de sessão pertencente ao usuário de destino seja usada para essa finalidade.
Se o tipo de BLOB de chave especificado por dwBlobType for PUBLICKEYBLOB, esse parâmetro não será utilizado e deverá ser definido como zero.
Se o tipo de BLOB de chave especificado por dwBlobType for PRIVATEKEYBLOB, esse normalmente é um identificador para uma chave de sessão que deve ser usada para criptografar o BLOB de chave. Alguns CSPs permitem que esse parâmetro seja zero, nesse caso, o aplicativo deve criptografar o BLOB de chave privada manualmente para protegê-lo.
Para determinar como os provedores de serviços criptográficos da Microsoft respondem a esse parâmetro, consulte as seções blob de chave privada dos Provedores de Serviços Criptográficos da Microsoft.
[in] dwBlobType
Especifica o tipo de BLOB de chave a ser exportado em pbData. Essa deve ser uma das seguintes constantes, conforme discutido no Armazenamento de Chaves Criptográficas e no Exchange.
| Valor | Significado |
|---|---|
|
Usado para armazenar chaves de sessão em um CSP do Schannel ou em qualquer outro formato específico do fornecedor. OPACOKEYBLOBs não são intransferíveis e devem ser usados dentro do CSP que gerou o BLOB. |
|
Usado para transportar pares de chaves públicas/privadas. |
|
Usado para transportar chaves públicas. |
|
Usado para transportar chaves de sessão. |
|
Um PLAINTEXTKEYBLOB usado para exportar qualquer chave com suporte pelo CSP em uso. |
|
Usado para exportar e importar uma chave simétrica encapsulada com outra chave simétrica. A chave encapsulada real está no formato especificado no padrão RFC 3217 do IETF. |
[in] dwFlags
Especifica opções adicionais para a função. Esse parâmetro pode ser zero ou uma combinação de um ou mais dos valores a seguir.
| Valor | Significado |
|---|---|
|
Esse sinalizador faz com que essa função exporte a versão 3 de um tipo BLOB. |
|
Esse sinalizador destrói a chave original no OPAQUEKEYBLOB. Esse sinalizador está disponível apenas em CSPs do Schannel. |
|
Esse sinalizador faz com que a formatação PKCS nº 1 versão 2 seja criada com a criptografia RSA e a descriptografia ao exportar SIMPLEBLOBs. |
|
Os primeiros oito bytes do preenchimento do bloco de criptografia RSA devem ser definidos como 0x03 em vez de dados aleatórios. Isso impede ataques de reversão de versão e é discutido na especificação SSL3. Esse sinalizador está disponível apenas para CSPs do Schannel. |
|
Esse sinalizador não é usado. |
[out] pbData
Um ponteiro para um buffer que recebe os dados importantes do BLOB . O formato desse BLOB varia dependendo do tipo BLOB solicitado no parâmetro dwBlobType . Para obter o formato de PRIVATEKEYBLOBs, PUBLICKEYBLOBs e SIMPLEBLOBs, consulte BLOBs de chave do provedor base.
Se esse parâmetro for NULL, o tamanho do buffer necessário será colocado no valor apontado pelo parâmetro pdwDataLen . Para obter mais informações, consulte Recuperando dados de comprimento desconhecido.
[in, out] pdwDataLen
Um ponteiro para um valor DWORD que, na entrada, contém o tamanho, em bytes, do buffer apontado pelo parâmetro pbData . Quando a função retorna, esse valor contém o número de bytes armazenados no buffer.
Retornar valor
Se a função for bem-sucedida, a função retornará diferente de zero (TRUE).
Se a função falhar, ela retornará zero (FALSE). Para obter informações de erro estendidas, chame GetLastError.
Os códigos de erro precedidos por "NTE" são gerados pelo CSP específico que está sendo usado. A tabela a seguir mostra alguns dos códigos de erro possíveis.
| Código de retorno | Descrição |
|---|---|
|
Um dos parâmetros especifica um identificador que não é válido. |
|
Um dos parâmetros contém um valor que não é válido. Isso geralmente é um ponteiro que não é válido. |
|
Se o buffer especificado pelo parâmetro pbData não for grande o suficiente para manter os dados retornados, a função definirá o código ERROR_MORE_DATA e armazenará o tamanho do buffer necessário, em bytes, na variável apontada por pdwDataLen. |
|
Não há suporte para o algoritmo que funciona com a chave pública a ser exportada por esse CSP ou foi feita uma tentativa de exportar uma chave de sessão criptografada com algo diferente de uma de suas chaves públicas. |
|
O parâmetro dwFlags não é zero. |
|
Uma ou ambas as chaves especificadas por hKey e hExpKey não são válidas. |
|
Você não tem permissão para exportar a chave. Ou seja, quando a chave hKey foi criada, o sinalizador CRYPT_EXPORTABLE não foi especificado. |
|
O tipo de BLOB de chave especificado por dwBlobType é PUBLICKEYBLOB, mas hExpKey não contém um identificador de chave pública. |
|
O parâmetro dwBlobType especifica um tipo BLOB desconhecido. |
|
O contexto CSP especificado quando a chave hKey foi criada não pode ser encontrado. |
|
Uma chave de sessão está sendo exportada e o parâmetro hExpKey não especifica uma chave pública. |
Comentários
Para qualquer uma das permutações de chave DES que usam um PLAINTEXTKEYBLOB, somente o tamanho completo da chave, incluindo o bit de paridade, pode ser exportado. Há suporte para os seguintes tamanhos de chave.
| Algoritmo | Tamanho da chave com suporte |
|---|---|
| CALG_DES | 64 bits |
| CALG_3DES_112 | 128 bits |
| CALG_3DES | 192 bits |
Exemplos
O exemplo a seguir mostra como exportar uma chave criptográfica ou um par de chaves de maneira mais segura. Este exemplo pressupõe que um contexto criptográfico foi adquirido e que uma chave pública está disponível para exportação. Para obter um exemplo que inclui o contexto completo para usar essa função, consulte Exemplo de Programa C: Assinando um hash e Verificando a assinatura de hash. Para obter outro exemplo que usa essa função, consulte Exemplo de Programa C: Exportando uma chave de sessão.
#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;
}
Requisitos
| Requisito | Valor |
|---|---|
| Cliente mínimo com suporte | Windows XP [somente aplicativos da área de trabalho] |
| Servidor mínimo com suporte | Windows Server 2003 [somente aplicativos da área de trabalho] |
| Plataforma de Destino | Windows |
| Cabeçalho | wincrypt.h |
| Biblioteca | Advapi32.lib |
| DLL | Advapi32.dll |
Confira também
Comentários
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulte https://aka.ms/ContentUserFeedback.
Enviar e exibir comentários de