Compartilhar via


Função CryptMsgControl (wincrypt.h)

A função CryptMsgControl executa uma operação de controle depois que uma mensagem é decodificada por uma chamada final para a função CryptMsgUpdate . As operações de controle fornecidas por essa função são usadas para descriptografia, verificação de assinatura e hash, além da adição e exclusão de certificados, CRLs ( listas de revogação de certificados ), signatários e atributos não autenticados.

Alterações importantes que afetam o tratamento de mensagens em envelope foram feitas na CryptoAPI para dar suporte à interoperabilidade de email S/MIME ( Secure/Multipurpose Internet Mail Extensions ). Para obter mais informações, consulte os Comentários para a função CryptMsgOpenToEncode .

Sintaxe

BOOL CryptMsgControl(
  [in] HCRYPTMSG  hCryptMsg,
  [in] DWORD      dwFlags,
  [in] DWORD      dwCtrlType,
  [in] void const *pvCtrlPara
);

Parâmetros

[in] hCryptMsg

Um identificador de uma mensagem criptográfica para a qual um controle deve ser aplicado.

[in] dwFlags

O valor a seguir é definido quando o parâmetro dwCtrlType é um dos seguintes:

  • CMSG_CTRL_DECRYPT
  • CMSG_CTRL_KEY_TRANS_DECRYPT
  • CMSG_CTRL_KEY_AGREE_DECRYPT
  • CMSG_CTRL_MAIL_LIST_DECRYPT
Valor Significado
CMSG_CRYPT_RELEASE_CONTEXT_FLAG
O identificador para o provedor criptográfico é liberado na chamada final para a função CryptMsgClose . Esse identificador não será liberado se a função CryptMsgControl falhar.
 

Se o parâmetro dwCtrlType não especificar uma operação de descriptografar, defina esse valor como zero.

[in] dwCtrlType

O tipo de operação a ser executada. Os tipos de controle de mensagem definidos no momento e o tipo de estrutura que deve ser passado para o parâmetro pvCtrlPara são mostrados na tabela a seguir.

Valor Significado
CMSG_CTRL_ADD_ATTR_CERT
14 (0xE)
Um BLOB que contém os bytes codificados do certificado de atributo.
CMSG_CTRL_ADD_CERT
10 (0xA)
Uma estrutura CRYPT_INTEGER_BLOB que contém os bytes codificados do certificado a ser adicionado à mensagem.
CMSG_CTRL_ADD_CMS_SIGNER_INFO
20 (0x14)
Uma estrutura CMSG_CMS_SIGNER_INFO que contém informações do signatário. Essa operação é diferente de CMSG_CTRL_ADD_SIGNER porque as informações do signatário contêm a assinatura.
CMSG_CTRL_ADD_CRL
12 (0xC)
Um BLOB que contém os bytes codificados da CRL a ser adicionada à mensagem.
CMSG_CTRL_ADD_SIGNER
6 (0x6)
Uma estrutura CMSG_SIGNER_ENCODE_INFO que contém as informações do signatário a serem adicionadas à mensagem.
CMSG_CTRL_ADD_SIGNER_UNAUTH_ATTR
8 (0x8)
Uma estrutura CMSG_CTRL_ADD_SIGNER_UNAUTH_ATTR_PARA que contém o índice do signatário e um BLOB que contém as informações de atributo não autenticados a serem adicionadas à mensagem.
CMSG_CTRL_DECRYPT
2 (0x2)
Uma estrutura CMSG_CTRL_DECRYPT_PARA usada para descriptografar a mensagem para o destinatário de transporte de chave especificado. Esse valor é aplicável aos destinatários RSA. Essa operação especifica que a função CryptMsgControl pesquisa o índice do destinatário para obter as informações do destinatário do transporte de chave. Se a função falhar, GetLastError retornará CRYPT_E_INVALID_INDEX se nenhum destinatário de transporte de chave for encontrado.
CMSG_CTRL_DEL_ATTR_CERT
15 (0xF)
O índice do certificado de atributo a ser removido.
CMSG_CTRL_DEL_CERT
11 (0xB)
O índice do certificado a ser excluído da mensagem.
CMSG_CTRL_DEL_CRL
13 (0xD)
O índice da CRL a ser excluída da mensagem.
CMSG_CTRL_DEL_SIGNER
7 (0x7)
O índice do signatário a ser excluído.
CMSG_CTRL_DEL_SIGNER_UNAUTH_ATTR
9 (0x9)
Uma estrutura CMSG_CTRL_DEL_SIGNER_UNAUTH_ATTR_PARA que contém um índice que especifica o signatário e o índice que especifica o atributo não autenticado do signatário a ser excluído.
CMSG_CTRL_ENABLE_STRONG_SIGNATURE
21 (0x15)
Uma estrutura CERT_STRONG_SIGN_PARA usada para executar uma verificação de assinatura forte.

Para marcar para uma assinatura forte, especifique esse tipo de controle antes de chamar CryptMsgGetAndVerifySigner ou antes de chamar CryptMsgControl com os seguintes tipos de controle definidos:

  • CMSG_CTRL_VERIFY_SIGNATURE
  • CMSG_CTRL_VERIFY_SIGNATURE_EX
Depois que a assinatura for verificada com êxito, essa função verificará se há uma assinatura forte. Se a assinatura não for forte, a operação falhará e o valor GetLastError será definido como NTE_BAD_ALGID.
CMSG_CTRL_KEY_AGREE_DECRYPT
17 (0x11)
Uma estrutura CMSG_CTRL_KEY_AGREE_DECRYPT_PARA usada para descriptografar a mensagem para a chave de sessão do contrato de chave especificada. O contrato de chave é usado com Diffie-Hellman criptografia/descriptografia.
CMSG_CTRL_KEY_TRANS_DECRYPT
16 (0x10)
Uma estrutura CMSG_CTRL_KEY_TRANS_DECRYPT_PARA usada para descriptografar a mensagem para o destinatário de transporte de chave especificado. O transporte de chave é usado com criptografia/descriptografia RSA.
CMSG_CTRL_MAIL_LIST_DECRYPT
18 (0x12)
Uma estrutura CMSG_CTRL_MAIL_LIST_DECRYPT_PARA usada para descriptografar a mensagem para o destinatário especificado usando uma KEK (chave de criptografia de chave) distribuída anteriormente.
CMSG_CTRL_VERIFY_HASH
5 (0x5)
Este valor não é usado.
CMSG_CTRL_VERIFY_SIGNATURE
1 (0x1)
Uma estrutura CERT_INFO que identifica o signatário da mensagem cuja assinatura deve ser verificada.
CMSG_CTRL_VERIFY_SIGNATURE_EX
19 (0x13)
Uma estrutura CMSG_CTRL_VERIFY_SIGNATURE_EX_PARA que especifica o índice do signatário e a chave pública para verificar a assinatura da mensagem. A chave pública do signatário pode ser uma estrutura CERT_PUBLIC_KEY_INFO , um contexto de certificado ou um contexto de cadeia de certificados.

[in] pvCtrlPara

Um ponteiro para uma estrutura determinada pelo valor de dwCtrlType.

Valor dwCtrlType Significado
CMSG_CTRL_DECRYPT, CMSG_CTRL_KEY_TRANS_DECRYPT, CMSG_CTRL_KEY_AGREE_DECRYPT ou CMSG_CTRL_MAIL_LIST_DECRYPT, e a mensagem em envelope transmitida está sendo decodificada
A decodificação será feita como se o conteúdo transmitido estivesse sendo descriptografado. Se algum conteúdo transmitido criptografado tiver sido acumulado antes dessa chamada, alguns ou todos os textos sem formatação resultantes da descriptografia do texto cifrado serão passados de volta para o aplicativo por meio da função de retorno de chamada especificada na chamada para a função CryptMsgOpenToDecode .
Nota Ao transmitir uma mensagem em envelope, a função CryptMsgControl não é chamada até que a sondagem para a disponibilidade do CMSG_ENVELOPE_ALGORITHM_PARAM seja bem-sucedida. Se a sondagem não for bem-sucedida, ocorrerá um erro. Para obter uma descrição dessa sondagem, consulte a função CryptMsgOpenToDecode .
 
CMSG_CTRL_VERIFY_HASH
O hash calculado do conteúdo da mensagem é comparado com o hash contido na mensagem.
CMSG_CTRL_ADD_SIGNER
pvCtrlPara aponta para uma estrutura CMSG_SIGNER_ENCODE_INFO que contém as informações do signatário a serem adicionadas à mensagem.
CMSG_CTRL_DEL_SIGNER
Depois que uma exclusão é feita, todos os outros índices de signatários em uso para essa mensagem não são mais válidos e devem ser requisitar chamando a função CryptMsgGetParam .
CMSG_CTRL_DEL_SIGNER_UNAUTH_ATTR
Depois que uma exclusão é feita, todos os outros índices de atributo não autenticados em uso para esse signatário não são mais válidos e devem ser solicitados novamente chamando a função CryptMsgGetParam .
CMSG_CTRL_DEL_CERT
Depois que uma exclusão é feita, todos os outros índices de certificado em uso para essa mensagem não são mais válidos e devem ser readquiridos chamando a função CryptMsgGetParam .
CMSG_CTRL_DEL_CRL
Depois que uma exclusão é feita, todos os outros índices de CRL em uso para essa mensagem não são mais válidos e precisarão ser requisitar chamando a função CryptMsgGetParam .

Valor retornado

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

Se a função falhar, o valor retornado será zero e a função GetLastError retornará um erro de codificação/decodificação ASN.1 ( Abstract Syntax Notation One ). Para obter informações sobre esses erros, consulte Valores retornados de codificação/decodificação asn.1.

Quando uma mensagem em fluxo e envelope está sendo decodificada, erros encontrados na função de retorno de chamada definida pelo aplicativo especificada pelo parâmetro pStreamInfo do
A função CryptMsgOpenToDecode pode ser propagada para a função CryptMsgControl. Se isso acontecer, a função SetLastError não será chamada pela função CryptMsgControl depois que a função de retorno de chamada retornar. Isso preserva todos os erros encontrados sob o controle do aplicativo. É responsabilidade da função de retorno de chamada (ou uma das APIs que ela chama) chamar a função SetLastError se ocorrer um erro enquanto o aplicativo estiver processando os dados transmitidos.

Erros propagados podem ser encontrados nas seguintes funções:

Os códigos de erro a seguir são mais comumente retornados.

Código de retorno Descrição
CRYPT_E_ALREADY_DECRYPTED
O conteúdo da mensagem já foi descriptografado. Esse erro poderá ser retornado se o parâmetro dwCtrlType estiver definido como CMSG_CTRL_DECRYPT.
CRYPT_E_AUTH_ATTR_MISSING
A mensagem não contém um atributo autenticado esperado. Esse erro poderá ser retornado se o parâmetro dwCtrlType estiver definido como CMSG_CTRL_VERIFY_SIGNATURE.
CRYPT_E_BAD_ENCODE
Erro ao codificar ou decodificar. Esse erro poderá ser retornado se o parâmetro dwCtrlType estiver definido como CMSG_CTRL_VERIFY_SIGNATURE.
CRYPT_E_CONTROL_TYPE
O tipo de controle não é válido.
CRYPT_E_HASH_VALUE
O valor de hash está incorreto.
CRYPT_E_INVALID_INDEX
O valor do índice não é válido.
CRYPT_E_INVALID_MSG_TYPE
O tipo de mensagem não é válido.
CRYPT_E_OID_FORMAT
O identificador de objeto está mal formatado. Esse erro poderá ser retornado se o parâmetro dwCtrlType estiver definido como CMSG_CTRL_ADD_SIGNER.
CRYPT_E_RECIPIENT_NOT_FOUND
A mensagem de dados enveloped não contém o destinatário especificado. Esse erro poderá ser retornado se o parâmetro dwCtrlType estiver definido como CMSG_CTRL_DECRYPT.
CRYPT_E_SIGNER_NOT_FOUND
O signatário especificado para a mensagem não foi encontrado. Esse erro poderá ser retornado se o parâmetro dwCtrlType estiver definido como CMSG_CTRL_VERIFY_SIGNATURE.
CRYPT_E_UNKNOWN_ALGO
O algoritmo criptográfico é desconhecido.
CRYPT_E_UNEXPECTED_ENCODING
A mensagem não está codificada conforme o esperado. Esse erro poderá ser retornado se o parâmetro dwCtrlType estiver definido como CMSG_CTRL_VERIFY_SIGNATURE.
E_INVALIDARG
Um ou mais argumentos não são válidos. Esse erro poderá ser retornado se o parâmetro dwCtrlType estiver definido como CMSG_CTRL_DECRYPT.
E_OUTOFMEMORY
Não havia memória suficiente disponível para concluir a operação.

Requisitos

Requisito Valor
Cliente mínimo com suporte Windows XP [aplicativos da área de trabalho | aplicativos UWP]
Servidor mínimo com suporte Windows Server 2003 [aplicativos da área de trabalho | Aplicativos UWP]
Plataforma de Destino Windows
Cabeçalho wincrypt.h
Biblioteca Crypt32.lib
DLL Crypt32.dll

Confira também

Funções de mensagem de baixo nível

Funções de mensagem simplificadas