Função CryptEncrypt (wincrypt.h)

Importante essa API foi preterida. O software novo e existente deve começar a usar APIs de Próxima Geração da Criptografia. 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.

Alterações importantes para dar suporte a interoperabilidade de email do de Email seguro/multiuso (S/MIME) foram feitas no CryptoAPI que afetam o tratamento de mensagens envolvidas. 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 o CryptGenKey ou a função CryptImportKey.

A chave especifica o algoritmo de criptografia usado.

[in] hHash

Um identificador para um objeto de hash . Se os dados forem criptografados e criptografados simultaneamente, um identificador para um objeto hash poderá ser passado no parâmetro hHash. O valor de hash é atualizado com o texto sem formatação 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 pode 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 é definido como VERDADEIRO para o último ou único bloco e para FALSE se houver mais blocos a serem criptografados. Para obter mais informações, consulte Comentários.

[in] dwFlags

O seguinte valor de dwFlags é definido, mas reservado para uso futuro.

Valor	Significado
CRYPT_OAEP	Use OAEP (Preenchimento de Criptografia Assimétrica Ideal) (PKCS nº 1 versão 2). Esse sinalizador só é compatível com o 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 sem formatação a ser criptografado. O texto sem formatação nesse buffer é substituído com o de texto criptografado criado por essa função.

O parâmetro pdwDataLen aponta para uma variável que contém o comprimento, em bytes, do texto sem formatação. 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 criptografado e colocará o valor apontado pelo parâmetro pdwDataLen .

[in, out] pdwDataLen

Um ponteiro para um DWORD valor que, na entrada, contém o comprimento, em bytes, do texto sem formatação no buffer pbData. Na saída, este DWORD contém o comprimento, em bytes, do texto criptografado no buffer pbData.

Se o buffer alocado para pbData não for grande o suficiente para armazenar 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 um de criptografia de bloco é usado, 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 ser criptografada e o parâmetro Final é VERDADEIRO.

[in] dwBufLen

Especifica o tamanho total, em bytes, do buffer de 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 um de criptografia de fluxo for usado, o texto criptografado será do mesmo tamanho que o texto sem formatação. Se um de criptografia de bloco for usado, o texto criptografado será até um tamanho de bloco maior que o texto sem formatação.

Valor de retorno

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. Isso geralmente é um ponteiro que não é válido.
NTE_BAD_ALGID	A chave de sessão hKey especifica um algoritmo que esse CSP não dá suporte.
NTE_BAD_DATA	Os dados a serem criptografados não são válidos. Por exemplo, quando uma criptografia 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 não é 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 criptografado 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.

Observações

Se uma grande quantidade de dados deve ser criptografada, ela pode ser feita em seções chamando CryptEncrypt repetidamente. O parâmetro Final deve ser definido para 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 é verdadeiro:

• Se a chave for uma chave de criptografia de bloco, os dados serão adicionados a 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 criptografia for umade criptografia de fluxo de , a próxima CryptEncrypt redefinirá a criptografia para seu estado de inicial.

Não há como definir o registro de comentários da criptografia para o valor KP_IV da chave sem definir o parâmetro Final como VERDADEIRO. 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 poderá 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 de criptografia Microsoft Enhanced Cryptographic dá suporte à criptografia direta com RSA de chaves públicas e descriptografia com chaves privadas RSA. A criptografia usa pkcs nº 1 de preenchimento. 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 criptografado é retornado em formato de little-endian.

Exemplos

Para obter exemplos que usam essa função, consulte Exemplo de Programa C: Criptografando um de Arquivo e Exemplo de Programa C: Descriptografando um arquivo.

Requisitos

Requisito	Valor
de cliente com suporte mínimo	Windows XP [somente aplicativos da área de trabalho]
servidor com suporte mínimo	Windows Server 2003 [somente aplicativos da área de trabalho]
da Plataforma de Destino	Windows
cabeçalho	wincrypt.h
biblioteca	Advapi32.lib
de DLL	Advapi32.dll

Consulte também

CryptCreateHash

CryptDecrypt

CryptGenKey

CryptGetHashParam

CryptGetKeyParam

CryptImport Key

CryptMsgOpenToEncode

CryptSignHash

Funções de criptografia e descriptografia de dados