Função CryptEncrypt (wincrypt.h)

Artigo
08/27/2023

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

A função CryptEncrypt criptografa dados. O algoritmo usado para criptografar os dados é designado pela chave mantida pelo módulo CSP e é referenciado pelo parâmetro hKey .

Foram feitas alterações importantes para dar suporte à interoperabilidade de email S/MIME ( Extensões de Email da Internet) Segura/Multiuso para CriptoAPI que afetam o tratamento de mensagens envelveladas. Para obter mais informações, consulte a seção Comentários de CryptMsgOpenToEncode.

Importante A função CryptEncrypt não tem garantia de ser thread-safe e pode retornar resultados incorretos se invocada simultaneamente por vários chamadores.

Sintaxe

BOOL CryptEncrypt(
  [in]      HCRYPTKEY  hKey,
  [in]      HCRYPTHASH hHash,
  [in]      BOOL       Final,
  [in]      DWORD      dwFlags,
  [in, out] BYTE       *pbData,
  [in, out] DWORD      *pdwDataLen,
  [in]      DWORD      dwBufLen
);

Parâmetros

[in] hKey

Um identificador para a chave de criptografia. Um aplicativo obtém esse identificador usando a função CryptGenKey ou CryptImportKey .

A chave especifica o algoritmo de criptografia usado.

[in] hHash

Um identificador para um objeto hash. Se os dados devem ser criptografados e criptografados simultaneamente, um identificador para um objeto hash pode ser passado no parâmetro hHash . O valor de hash é atualizado com o texto não criptografado passado. Essa opção é útil ao gerar texto assinado e criptografado.

Antes de chamar CryptEncrypt, o aplicativo deve obter um identificador para o objeto hash chamando a função CryptCreateHash . Depois que a criptografia for concluída, o valor de hash poderá ser obtido usando a função CryptGetHashParam ou o hash poderá ser assinado usando a função CryptSignHash .

Se nenhum hash for feito, esse parâmetro deverá ser NULL.

[in] Final

Um valor booliano que especifica se esta é a última seção de uma série que está sendo criptografada. Final será definido como TRUE para o último ou único bloco e como FALSE se houver mais blocos a serem criptografados. Para obter mais informações, consulte Comentários.

[in] dwFlags

O valor dwFlags a seguir é definido, mas reservado para uso futuro.

Valor	Significado
CRYPT_OAEP	Use o OAEP (Preenchimento de Criptografia Assimétrica Ideal) (PKCS nº 1 versão 2). Esse sinalizador só tem suporte do Provedor criptográfico avançado da Microsoft com criptografia/descriptografia RSA.

[in, out] pbData

Um ponteiro para um buffer que contém o texto não criptografado a ser criptografado. O texto não criptografado nesse buffer é substituído pelo texto cifrado criado por essa função.

O parâmetro pdwDataLen aponta para uma variável que contém o comprimento, em bytes, do texto não criptografado. O parâmetro dwBufLen contém o tamanho total, em bytes, desse buffer.

Se esse parâmetro contiver NULL, essa função calculará o tamanho necessário para o texto cifrado e o colocará no valor apontado pelo parâmetro pdwDataLen .

[in, out] pdwDataLen

Um ponteiro para um valor DWORD que , na entrada, contém o comprimento, em bytes, do texto não criptografado no buffer pbData . Na saída, esse DWORD contém o comprimento, em bytes, do texto cifrado gravado no buffer pbData .

Se o buffer alocado para pbData não for grande o suficiente para manter os dados criptografados, GetLastError retornará ERROR_MORE_DATA e armazenará o tamanho do buffer necessário, em bytes, no valor DWORD apontado por pdwDataLen.

Se pbData for NULL, nenhum erro será retornado e a função armazenará o tamanho dos dados criptografados, em bytes, no valor DWORD apontado por pdwDataLen. Isso permite que um aplicativo determine o tamanho correto do buffer.

Quando uma codificação de bloco é usada, esse comprimento de dados deve ser um múltiplo do tamanho do bloco, a menos que esta seja a seção final dos dados a serem criptografados e o parâmetro Final seja TRUE.

[in] dwBufLen

Especifica o tamanho total, em bytes, do buffer pbData de entrada.

Observe que, dependendo do algoritmo usado, o texto criptografado pode ser maior que o texto sem formatação original. Nesse caso, o buffer pbData precisa ser grande o suficiente para conter o texto criptografado e qualquer preenchimento.

Como regra, se uma codificação de fluxo for usada, o texto cifrado será do mesmo tamanho que o texto não criptografado. Se uma codificação de bloco for usada, o texto cifrado será até um comprimento de bloco maior que o texto não criptografado.

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 pelo NTE são gerados pelo CSP específico que está sendo usado. Alguns códigos de erro possíveis seguem.

Valor	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. Geralmente, esse é um ponteiro que não é válido.
NTE_BAD_ALGID	A chave de sessãohKey especifica um algoritmo ao qual esse CSP não dá suporte.
NTE_BAD_DATA	Os dados a serem criptografados não são válidos. Por exemplo, quando uma codificação de bloco é usada e o sinalizador Final é FALSE, o valor especificado por pdwDataLen deve ser um múltiplo do tamanho do bloco.
NTE_BAD_FLAGS	O parâmetro dwFlags é diferente de zero.
NTE_BAD_HASH	O parâmetro hHash contém um identificador que não é válido.
NTE_BAD_HASH_STATE	Foi feita uma tentativa de adicionar dados a um objeto hash que já está marcado como "concluído".
NTE_BAD_KEY	O parâmetro hKey não contém um identificador válido para uma chave.
NTE_BAD_LEN	O tamanho do buffer de saída é muito pequeno para conter o texto cifrado gerado.
NTE_BAD_UID	O contexto CSP especificado quando a chave foi criada não pode ser encontrado.
NTE_DOUBLE_ENCRYPT	O aplicativo tentou criptografar os mesmos dados duas vezes.
NTE_FAIL	A função falhou de alguma forma inesperada.
NTE_NO_MEMORY	O CSP ficou sem memória durante a operação.

Comentários

Se uma grande quantidade de dados deve ser criptografada, isso pode ser feito em seções chamando CryptEncrypt repetidamente. O parâmetro Final deve ser definido como TRUE na última chamada para CryptEncrypt, para que o mecanismo de criptografia possa concluir corretamente o processo de criptografia. As seguintes ações extras são executadas quando Final é TRUE:

Se a chave for uma chave de criptografia de bloco, os dados serão preenchidos em um múltiplo do tamanho do bloco da criptografia. Se o tamanho dos dados for igual ao tamanho do bloco da criptografia, um bloco adicional de preenchimento será acrescentado aos dados. Para localizar o tamanho do bloco de uma criptografia, use CryptGetKeyParam para obter o valor KP_BLOCKLEN da chave.
Se a criptografia estiver operando em um modo de encadeamento, a próxima operação CryptEncrypt redefinirá o registro de comentários da criptografia para o valor KP_IV da chave.
Se a codificação for uma codificação de fluxo, o próximo CryptEncrypt redefinirá a criptografia para seu estado inicial.

Não é possível definir o registro de comentários da codificação como o valor KP_IV da chave sem definir o parâmetro Final como TRUE. Se isso for necessário, como no caso em que você não deseja adicionar um bloco de preenchimento adicional ou alterar o tamanho de cada bloco, você pode simular isso criando uma duplicata da chave original usando a função CryptDuplicateKey e passando a chave duplicada para a função CryptEncrypt . Isso faz com que o KP_IV da chave original seja colocado na chave duplicada. Depois de criar ou importar a chave original, você não pode usar a chave original para criptografia porque o registro de comentários da chave será alterado. O pseudocódigo a seguir mostra como isso pode ser feito.

// Set the IV for the original key. Do not use the original key for 
// encryption or decryption after doing this because the key's 
// feedback register will get modified and you cannot change it.
CryptSetKeyParam(hOriginalKey, KP_IV, newIV)

while(block = NextBlock())
{
    // Create a duplicate of the original key. This causes the 
    // original key's IV to be copied into the duplicate key's 
    // feedback register.
    hDuplicateKey = CryptDuplicateKey(hOriginalKey)

    // Encrypt the block with the duplicate key.
    CryptEncrypt(hDuplicateKey, block)

    // Destroy the duplicate key. Its feedback register has been 
    // modified by the CryptEncrypt function, so it cannot be used
    // again. It will be re-duplicated in the next iteration of the 
    // loop.
    CryptDestroyKey(hDuplicateKey)
}

O Provedor criptográfico avançado da Microsoft dá suporte à criptografia direta com chaves públicas RSA e descriptografia com chaves privadas RSA. A criptografia usa o preenchimento PKCS nº 1. Na descriptografia, esse preenchimento é verificado. O comprimento dos dados de texto não criptografado que podem ser criptografados com uma chamada para CryptEncrypt com uma chave RSA é o comprimento do módulo de chave menos onze bytes. Os onze bytes são o mínimo escolhido para preenchimento PKCS nº 1. O texto cifrado é retornado no formato little-endian .

Exemplos

Para obter exemplos que usam essa função, consulte Exemplo de programa C: criptografando um arquivo e um programa C de exemplo: descriptografando um arquivo.

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