CryptDecryptAndVerifyMessageSignature function (wincrypt.h)

Article
10/13/2021

The CryptDecryptAndVerifyMessageSignature function decrypts a message and verifies its signature.

Syntax

BOOL CryptDecryptAndVerifyMessageSignature(
  [in]                PCRYPT_DECRYPT_MESSAGE_PARA pDecryptPara,
  [in]                PCRYPT_VERIFY_MESSAGE_PARA  pVerifyPara,
  [in]                DWORD                       dwSignerIndex,
  [in]                const BYTE                  *pbEncryptedBlob,
  [in]                DWORD                       cbEncryptedBlob,
  [out, optional]     BYTE                        *pbDecrypted,
  [in, out, optional] DWORD                       *pcbDecrypted,
  [out, optional]     PCCERT_CONTEXT              *ppXchgCert,
  [out, optional]     PCCERT_CONTEXT              *ppSignerCert
);

Parameters

[in] pDecryptPara

A pointer to a CRYPT_DECRYPT_MESSAGE_PARA structure that contains decryption parameters.

[in] pVerifyPara

A pointer to a CRYPT_VERIFY_MESSAGE_PARA structure that contains verification parameters.

[in] dwSignerIndex

Identifies a particular signer of the message. A message can be signed by more than one signer and this function can be called multiple times changing this parameter to check for several signers. It is set to zero for the first signer. If the function returns FALSE, and GetLastError returns CRYPT_E_NO_SIGNER, the previous call received the last signer of the message.

[in] pbEncryptedBlob

A pointer to the signed, encoded, and encrypted message to be decrypted and verified.

[in] cbEncryptedBlob

The size, in bytes, of the encrypted message.

[out, optional] pbDecrypted

A pointer to a buffer to receive the decrypted message.

This parameter can be NULL if the decrypted message is not required or to set the size of the decrypted message for memory allocation purposes. A decrypted message will not be returned if this parameter is NULL. For more information, see Retrieving Data of Unknown Length.

[in, out, optional] pcbDecrypted

A pointer to a DWORD that specifies the size, in bytes, of the buffer pointed to by the pbDecrypted parameter. When the function returns, it contains the size of the decrypted message copied to pbDecrypted.

Note When processing the data returned in the pbDecrypted buffer, applications must use the actual size of the data returned. The actual size can be slightly smaller than the size of the buffer specified in pcbDecrypted on input. On output, the variable pointed to by this parameter is set to reflect the actual size of the data copied to the buffer.

[out, optional] ppXchgCert

A pointer to a CERT_CONTEXT structure of the certificate that corresponds to the private exchange key needed to decrypt the message.

[out, optional] ppSignerCert

A pointer to a CERT_CONTEXT structure of the certificate of the signer.

Return value

If the function succeeds, the function returns nonzero (TRUE).

If the function fails, it returns zero (FALSE). For extended error information, call GetLastError.

Note Errors from the called functions CryptDecryptMessage and CryptVerifyMessageSignature might be propagated to this function.

The GetLastError function returns the following error code most often.

Return code	Description
ERROR_MORE_DATA	If the buffer specified by the pbDecrypted parameter is not large enough to hold the returned data, the function sets the ERROR_MORE_DATA code, and stores the required buffer size, in bytes, in the variable pointed to by pcbDecrypted.

Remarks

For a successfully decrypted and verified message, the certificate context pointers pointed to by ppXchgCert and ppSignerCert are updated. They must be freed by calling CertFreeCertificateContext. If the function fails, they are set to NULL.

To indicate that the caller is not interested in the exchange certificate or the signer certificate context, set the ppXchgCert and ppSignerCert parameters to NULL.

Examples

For an example that uses this function, see Example C Program: Sending and Receiving a Signed and Encrypted Message.

Requirements

Requirement	Value
Minimum supported client	Windows XP [desktop apps only]
Minimum supported server	Windows Server 2003 [desktop apps only]
Target Platform	Windows
Header	wincrypt.h
Library	Crypt32.lib
DLL	Crypt32.dll

Share via