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 |
|---|---|
|
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 |
|---|---|
|
Um BLOB que contém os bytes codificados do certificado de atributo. |
|
Uma estrutura CRYPT_INTEGER_BLOB que contém os bytes codificados do certificado a ser adicionado à mensagem. |
|
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. |
|
Um BLOB que contém os bytes codificados da CRL a ser adicionada à mensagem. |
|
Uma estrutura CMSG_SIGNER_ENCODE_INFO que contém as informações do signatário a serem adicionadas à mensagem. |
|
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. |
|
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. |
|
O índice do certificado de atributo a ser removido. |
|
O índice do certificado a ser excluído da mensagem. |
|
O índice da CRL a ser excluída da mensagem. |
|
O índice do signatário a ser excluído. |
|
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. |
|
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:
|
|
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. |
|
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. |
|
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. |
|
Este valor não é usado. |
|
Uma estrutura CERT_INFO que identifica o signatário da mensagem cuja assinatura deve ser verificada. |
|
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 |
|---|---|
|
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 .
|
|
O hash calculado do conteúdo da mensagem é comparado com o hash contido na mensagem. |
|
pvCtrlPara aponta para uma estrutura CMSG_SIGNER_ENCODE_INFO que contém as informações do signatário a serem adicionadas à mensagem. |
|
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 . |
|
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 . |
|
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 . |
|
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:
- Cryptcreatehash
- Cryptdecrypt
- Cryptgethashparam
- Cryptgetuserkey
- Crypthashdata
- Cryptimportkey
- Cryptsignhash
- CryptVerifySignature
Os códigos de erro a seguir são mais comumente retornados.
| Código de retorno | Descrição |
|---|---|
|
O conteúdo da mensagem já foi descriptografado. Esse erro poderá ser retornado se o parâmetro dwCtrlType estiver definido como CMSG_CTRL_DECRYPT. |
|
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. |
|
Erro ao codificar ou decodificar. Esse erro poderá ser retornado se o parâmetro dwCtrlType estiver definido como CMSG_CTRL_VERIFY_SIGNATURE. |
|
O tipo de controle não é válido. |
|
O valor de hash está incorreto. |
|
O valor do índice não é válido. |
|
O tipo de mensagem não é válido. |
|
O identificador de objeto está mal formatado. Esse erro poderá ser retornado se o parâmetro dwCtrlType estiver definido como CMSG_CTRL_ADD_SIGNER. |
|
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. |
|
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. |
|
O algoritmo criptográfico é desconhecido. |
|
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. |
|
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. |
|
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 |