Função CryptGenRandom (wincrypt.h)

Importante Essa API foi preterida. O software novo e existente deve começar a usar APIs de Criptografia de Próxima Geração. A Microsoft pode remover essa API em versões futuras.

 

A função CryptGenRandom preenche um buffer com bytes aleatórios criptograficamente.

Sintaxe

BOOL CryptGenRandom(
  [in]      HCRYPTPROV hProv,
  [in]      DWORD      dwLen,
  [in, out] BYTE       *pbBuffer
);

Parâmetros

[in] hProv

Identificador de um CSP (provedor de serviços criptográficos ) criado por uma chamada para CryptAcquireContext.

[in] dwLen

Número de bytes de dados aleatórios a serem gerados.

[in, out] pbBuffer

Buffer para receber os dados retornados. Esse buffer deve ter pelo menos bytes dwLen de comprimento.

Opcionalmente, o aplicativo pode preencher esse buffer com dados a serem usados como uma semente aleatória auxiliar.

Retornar valor

Se a função for bem-sucedida, o valor retornado será diferente de zero (TRUE).

Se a função falhar, o valor retornado será 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. Alguns códigos de erro possíveis são listados na tabela a seguir.

Código de retorno	Descrição
ERROR_INVALID_HANDLE	Um dos parâmetros especifica um identificador que não é válido.
ERROR_INVALID_PARAMETER	Um dos parâmetros contém um valor que não é válido. Isso geralmente é um ponteiro que não é válido.
NTE_BAD_UID	O parâmetro hProv não contém um identificador de contexto válido.
NTE_FAIL	A função falhou de alguma forma inesperada.

Comentários

Os dados produzidos por essa função são criptograficamente aleatórios. É muito mais aleatório do que os dados gerados pelo gerador de número aleatório típico, como aquele enviado com o compilador C.

Essa função geralmente é usada para gerar vetores de inicialização aleatórios e valores de sal.

Os geradores de números aleatórios de software funcionam fundamentalmente da mesma maneira. Eles começam com um número aleatório, conhecido como semente, e usam um algoritmo para gerar uma sequência pseudo-aleatória de bits com base nele. A parte mais difícil desse processo é obter uma semente que seja verdadeiramente aleatória. Isso geralmente é baseado na latência de entrada do usuário ou na tremulação de um ou mais componentes de hardware.

Com os CSPs da Microsoft, o CryptGenRandom usa o mesmo gerador de número aleatório usado por outros componentes de segurança. Isso permite que vários processos contribuam para uma semente em todo o sistema. CryptoAPI armazena uma semente aleatória intermediária com cada usuário. Para formar a semente para o gerador de número aleatório, um aplicativo de chamada fornece bits que ele pode ter, por exemplo, entrada de tempo de mouse ou teclado, que são combinados com a semente armazenada e vários dados do sistema e dados do usuário, como a ID do processo e a ID do thread, o relógio do sistema, a hora do sistema, o contador do sistema, status de memória, clusters de disco livre, o bloco de ambiente do usuário com hash. Esse resultado é usado para propagar o gerador de números pseudorandom (PRNG). No Windows Vista com Service Pack 1 (SP1) e posterior, é usada uma implementação do PRNG baseado no modo de contador do AES especificado na Publicação Especial NIST 800-90. No Windows Vista, Windows Storage Server 2003 e Windows XP, o PRNG especificado no PADRÃO DE PROCESSAMENTO de Informações Federais (FIPS) 186-2 é usado. Se um aplicativo tiver acesso a uma boa fonte aleatória, ele poderá preencher o buffer pbBuffer com alguns dados aleatórios antes de chamar CryptGenRandom. Em seguida, o CSP usa esses dados para randomizar ainda mais sua semente interna. É aceitável omitir a etapa de inicialização do buffer pbBuffer antes de chamar CryptGenRandom.

Exemplos

O exemplo a seguir mostra a geração de 8 bytes aleatórios. Eles podem ser usados para criar chaves criptográficas ou para qualquer aplicativo que use números aleatórios. Para obter um exemplo que inclui o contexto completo para este exemplo, consulte Exemplo de Programa C: Duplicando uma chave de sessão.

//--------------------------------------------------------------------
// Declare and initialize variables.

HCRYPTPROV   hCryptProv;
BYTE         pbData[16];

//--------------------------------------------------------------------
//  This code assumes that a cryptographic context has been acquired 
//  For code details, see "Example C Program: Duplicating a Session 
//  Key."

//--------------------------------------------------------------------
// Generate a random initialization vector.

if(CryptGenRandom(
   hCryptProv, 
   8, 
   pbData)) 
{
     printf("Random sequence generated. \n");
}
else
{
     printf("Error during CryptGenRandom.\n");
     exit(1);
}

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

Cryptacquirecontext

Cryptgenkey

Cryptsetkeyparam

Funções de Geração de Chaves e Exchange