Função CryptGenKey (wincrypt.h)

O aplicativo de chamada deve especificar o algoritmo ao chamar essa função. Como esse tipo de algoritmo é mantido agrupado com a chave, o aplicativo não precisa especificar o algoritmo posteriormente quando as operações criptográficas reais são executadas.

Sintaxe

BOOL CryptGenKey(
  [in]  HCRYPTPROV hProv,
  [in]  ALG_ID     Algid,
  [in]  DWORD      dwFlags,
  [out] HCRYPTKEY  *phKey
);

Parâmetros

[in] hProv

Um identificador para um CSP (provedor de serviços criptográfico) criado por uma chamada para CryptAcquireContext.

[in] Algid

Um valor ALG_ID que identifica o algoritmo para o qual a chave deve ser gerada. Os valores desse parâmetro variam dependendo do CSP usado.

Para ALG_ID valores a serem usados com o Provedor Criptográfico Base da Microsoft, consulte algoritmos de provedor base.

Para ALG_ID valores a serem usados com o Provedor Criptográfico Forte da Microsoft ou com o Provedor criptográfico avançado da Microsoft, consulte algoritmos de provedor aprimorados.

Para um CSP Diffie-Hellman, use um dos valores a seguir.

Além de gerar chaves de sessão para algoritmos simétricos, essa função também pode gerar pares de chaves públicas/privadas. Cada cliente CryptoAPI geralmente possui dois pares de chave pública/privada. Para gerar um desses pares de chaves, defina o parâmetro Argel como um dos seguintes valores.

[in] dwFlags

Especifica o tipo de chave gerada. Os tamanhos de uma chave de sessão, chave de assinatura RSA e chave RSA chaves de troca podem ser definidos quando a chave é gerada. O tamanho da chave, que representa o comprimento do módulo de chave em bits, é definido com os 16 bits superiores desse parâmetro. Portanto, se uma chave de assinatura RSA de 2.048 bits for gerada, o valor 0x08000000 será combinado com qualquer outra dwFlags valor predefinido com uma operaçãoor bit a bit. Os 16 bits superiores de 0x08000000 são 0x0800 ou decimal 2.048. O valor RSA1024BIT_KEY pode ser usado para especificar uma chave RSA de 1024 bits.

Devido à alteração das restrições de controle de exportação, o CSP padrão e o padrão comprimento da chave podem mudar entre as versões do sistema operacional. É importante que a criptografia e a descriptografia usem o mesmo CSP e que o comprimento da chave seja definido explicitamente usando o parâmetro dwFlags para garantir a interoperabilidade em diferentes plataformas do sistema operacional.

Em particular, o provedor de serviços de criptografia completo RSA padrão é o Provedor Criptográfico Forte do Microsoft RSA. A assinatura DSS padrão Diffie-Hellman provedor de serviços criptográficos é o provedor de criptografia Diffie-Hellman DSS avançado da Microsoft. Cada um desses CSPs tem um comprimento de chave simétrica padrão de 128 bits para RC2 e RC4 e um comprimento de chave padrão de 1.024 bits para algoritmos de chave pública.

Se os 16 bits superiores forem zero, o tamanho da chave padrão será gerado. Se uma chave maior que o máximo ou menor que o mínimo for especificada, a chamada falhará com o código ERROR_INVALID_PARAMETER.

A tabela a seguir lista comprimentos mínimos, padrão e máximos de assinatura e chave de troca começando com o Windows XP.

Para obter comprimentos de chave de sessão, consulte CryptDeriveKey .

Para obter mais informações sobre chaves geradas usando provedores da Microsoft, consulte Provedores de Serviços Criptográficos da Microsoft.

Os 16 bits inferiores desse parâmetro podem ser zero ou uma combinação de um ou mais dos valores a seguir.

[out] phKey

Endereço para o qual a função copia o identificador da chave recém-gerada. Quando terminar de usar a chave, exclua o identificador para a chave chamando a função CryptDestroyKey.

Valor de retorno

Retorna diferente de zero se tiver êxito ou zero caso contrário.

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. Alguns códigos de erro possíveis são listados na tabela a seguir.

Observações

Se as chaves forem geradas para criptografias de bloco simétricas, a chave, por padrão, será configurada no modo cbc ( de encadeamento de blocos de criptografia) com um vetor de inicialização zero. Esse modo de criptografia fornece um bom método padrão para criptografar dados em massa. Para alterar esses parâmetros, use a função CryptSetKeyParam.

Para escolher umade comprimento de chave apropriada, os seguintes métodos são recomendados:

• Enumera os algoritmos aos quais o CSP dá suporte e obtém comprimentos máximos e mínimos de chave para cada algoritmo. Para fazer isso, chame CryptGetProvParam com PP_ENUMALGS_EX.
• Use os comprimentos mínimo e máximo para escolher um comprimento de chave apropriado. Nem sempre é aconselhável escolher o comprimento máximo porque isso pode levar a problemas de desempenho.
• Depois que o comprimento da chave desejado tiver sido escolhido, use os 16 bits superiores do parâmetro dwFlags para especificar o comprimento da chave.

Exemplos

O exemplo a seguir mostra a criação de uma chave de sessão aleatória. Para obter um exemplo que inclua o contexto completo para este exemplo, consulte Exemplo de Programa C: Criptografando um arquivo. Para obter outro exemplo que usa essa função, consulte Exemplo de Programa C: Descriptografando um arquivo.

//-------------------------------------------------------------------
//  Declare the handle to the key.
HCRYPTKEY hKey; 
//-------------------------------------------------------------------
//  This example assumes that a cryptographic context 
//  has been acquired, and that it is stored in hCryptProv.
//---------------------------------------------------------------
//  Create a random session key. 

 if(CryptGenKey(
          hCryptProv, 
          ENCRYPT_ALGORITHM, 
          KEYLENGTH | CRYPT_EXPORTABLE, 
          &hKey))
 {
         printf("A session key has been created.\n");
 } 
 else
 {
          printf("Error during CryptGenKey.\n"); 
          exit(1);
 }
//-------------------------------------------------------------------
//  The key created can be exported into a key BLOB that can be
//  written to a file.
//  ...
//  When you have finished using the key, free the resource.
if (!CryptDestroyKey(hKey))
{
          printf("Error during CryptDestroyKey.\n"); 
          exit(1);
}

Requisitos

Consulte também

CryptAcquireContext

CryptDestroyKey

CryptExportKey

CryptGetKeyParam

CryptImport Key

CryptSetKeyParam

geração de chaves e funções do Exchange

problemas de threading com provedores de serviços criptográficos