CryptMsgGetParam

The CryptMsgGetParam function gets a parameter after encoding/decoding a cryptographic message. This function is called after the final CryptMsgUpdate. For an encoded message, only the CMSG_CONTENT_PARAM and CMSG_COMPUTED_HASH_PARAM are valid.

#include <wincrypt.h>
BOOL WINAPI CryptMsgGetParam(
  HCRYPTMSG hCryptMsg,    // in
  DWORD dwParamType,      // in
  DWORD dwIndex,          // in
  void *pvData,           // out
  DWORD *pcbData          // in/out
);

Parameters

hCryptMsg

A handle to a cryptographic message.

dwParamType

The following list contains the defined parameter types. These parameter types indicate the type of data being requested and correspondingly, the type of data structure to use at pvData to receive it.

CMSG_BARE_CONTENT_PARAM (3)

Used to retrieve the encoded content of an encoded cryptographic message, without the outer layer of CONTENT_INFO. That is, only the encoding of the ContentInfo.content field is returned, as defined in PKCS #7, General syntax. Also used for Microsoft® Internet Explorer version 3.0 compatibility for SPC files.

Applicable only to encode.

pvData points to the buffer receiving the encoded bytes.

CMSG_CERT_COUNT_PARAM (11)

Used to determine the count of Certificates in a received signed message.

Applicable only to decode.

pvData points to a DWORD, which receives the count.

CMSG_CERT_PARAM (12)

Used to retrieve a Certificate when decoding a received signed message.

To get all the Certificates, repetitively call CryptMsgGetParam, while varying dwIndex from 0 to (CertCount - 1), where CertCount is the value obtained from a previous call to CryptMsgGetParam with dwParamType set to CMSG_CERT_COUNT_PARAM.

Applicable only to decode.

pvData points to an array of the certificate's encoded bytes.

CMSG_COMPUTED_HASH_PARAM (22)

This parameter is used when decoding a received hashed message to retrieve the value of the hash that was calculated, based on the data in the message.

Applicable for a HASHED message.

For HASHED, this parameter may be used for either encoding or decoding a message.

Applicable to both encode and decode.

pvData points to an array of bytes.

CMSG_CONTENT_PARAM (2)

When a message has been opened to encode, this parameter is used to retrieve the whole PKCS#7 message.

When a message has been opened to decode, this parameter is used to retrieve the inner content. If the message is enveloped and the inner type is data, the decrypted content is returned if you have already called CryptMsgControl to decrypt it. If the inner type is not data, the encoded blob is returned, which requires further decoding. If the message is not enveloped, and if the inner content is of type DATA, the returned data is the contents octets of the inner content.

Applicable to both encode and decode.

For encode, pvData points to the buffer receiving the encoded bytes.

For decode, pvData points to the buffer receiving the inner content. If the type is CMSG_DATA, the contents octets are returned. If the type is not CMSG_DATA, the encoded inner content is returned.

CMSG_CRL_COUNT_PARAM (13)

Used to determine the count of Certificate Revocation Lists (CRLs) in a received signed message.

Applicable only to decode.

pvData points to a DWORD, which receives the count.

CMSG_CRL_PARAM (14)

Used to retrieve a Certificate Revocation List (CRL) when decoding a received signed message.

To get all the CRLs, repetitively call CryptMsgGetParam, while varying dwIndex from 0 to (CrlCount - 1), where CrlCount is the value obtained from a previous call to CryptMsgGetParam with dwParamType set to CMSG_CRL_COUNT_PARAM.

Applicable only to decode.

pvData points to an array of the CRL's encoded bytes.

CMSG_ENCODED_MESSAGE (29)

Used when it is desired to change the contents of an already encoded message. The message must first be decoded with a call to CryptMsgOpenToDecode. Then the change to the message is made through a call to CryptMsgControl, CryptMsgCountersign, or CryptMsgCountersignEncoded. The message is then encoded again with a call to CryptMsgGetParam, specifying CMSG_ENCODED_MESSAGE to get a new encoding that reflects the changes made. One such purpose for performing this operation is during a time stamping where an attribute may be added to the message.

Applicable only to decode.

pvData points to a buffer that receives the encoded bytes.

CMSG_ENCODED_SIGNER (28)

The encoding of the signer info (CMSG_SIGNER_INFO) for one signer of a signed message.

Applicable only to decode.

pvData points to a buffer receiving the encoded bytes.

CMSG_ENCRYPTED_DIGEST (27)

Used when retrieving the encrypted digest of the signature. Typically used for performing time stamping.

Applicable only to decode.

pvData points to a buffer receiving the encrypted digest bytes.

CMSG_ENVELOPE_ALGORITHM_PARAM (15)

Used to retrieve the ContentEncryptionAlgorithm that was used for a ENVELOPED or SIGNED_AND_ENVELOPED received message.

Applicable only to decode.

pvData points to an CRYPT_ALGORITHM_IDENTIFIER struct.

CMSG_HASH_ALGORITHM_PARAM (20)

This parameter is used when decoding a received hashed message to retrieve the HashAlgorithm that was used to hash the message when it was created.

Applicable only to decode.

pvData points to an CRYPT_ALGORITHM_IDENTIFIER struct.

CMSG_HASH_DATA_PARAM (21)

This parameter is used when decoding a received hashed message to retrieve the value of the hash that was stored in the message when it was created.

Applicable only to decode.

pvData points to an array of bytes.

CMSG_INNER_CONTENT_TYPE_PARAM (4)

Used to determine the inner content type of a received message. Returns the type of the inner content of a decoded cryptographic message, in the form of a NULL-terminated object identifier string (for example: "1.2.840.113549.1.7.1").

Applicable only to decode. Not applicable to messages of type DATA.

pvData points to the buffer receiving the object identifier string.

CMSG_RECIPIENT_COUNT_PARAM (17)

Used to determine the count of recipients in an ENVELOPED or SIGNED_AND_ENVELOPED received message.

Applicable only to decode.

pvData points to a DWORD, which receives the count.

CMSG_RECIPIENT_INDEX_PARAM (18)

Used to determine the index of the recipient used to decrypt an ENVELOPED or SIGNED_AND_ENVELOPED message. This parameter is available only after the message has been decrypted.

Applicable only to decode.

pvData points to a DWORD, which receives the count.

CMSG_RECIPIENT_INFO_PARAM (19)

Used to retrieve the CERT_INFO for a recipient when decoding a received signed message.

To get the CERT_INFO for all the recipients, repetitively call CryptMsgGetParam, while varying dwIndex from 0 to (RecipientCount - 1), where RecipientCount is the value obtained from a previous call to CryptMsgGetParam with dwParamType set to CMSG_RECIPIENT_COUNT_PARAM.

Only the following fields have been updated in the CERT_INFO struct: Issuer, SerialNumber.

Applicable only to decode.

pvData points to a CERT_INFO struct.

CMSG_SIGNER_AUTH_ATTR_PARAM (9)

This parameter is used when decoding a received signed message to retrieve the authenticated attributes for the signer of the message.

To get all the authenticated attributes for a given signer, call CryptMsgGetParam, with dwIndex equal to that signer's index.

Applicable only to decode.

pvData points to a CRYPT_ATTRIBUTES struct.

CMSG_SIGNER_CERT_INFO_PARAM (7)

Used to retrieve the CERT_INFO for a signer when decoding a received signed message. Typically, this is done when preparing to get the Certificate for a signer of interest, which requires the signer's Issuer and SerialNumber. To get the CERT_INFOs for all the signers, repetitively call CryptMsgGetParam while varying dwIndex from 0 to (SignerCount - 1), where SignerCount is the value obtained from a previous call to CryptMsgGetParam with dwParamType set to CMSG_SIGNER_COUNT_PARAM.

Only the following fields contain valid data in the CERT_INFO struct returned: Issuer and SerialNumber.

Applicable only to decode.

pvData points to a CERT_INFO struct.

CMSG_SIGNER_COUNT_PARAM (5)

Used to determine the count of signers in a received message of type SIGNED, SIGNED_AND_ENVELOPED.

Applicable only to decode.

pvData points to a DWORD which receives the count.

CMSG_SIGNER_HASH_ALGORITHM_PARAM (8)

This parameter is used when decoding a received signed message to retrieve the HashAlgorithm that was used by a signer of the message.

To get the hash algorithm for a given signer, call CryptMsgGetParam, with dwIndex equal to that signer's index.

Applicable only to decode.

pvData points to a CRYPT_ALGORITHM_IDENTIFIER struct.

CMSG_SIGNER_INFO_PARAM (6)

Used to retrieve a signer when decoding a received signed message. To get all the signers, repetitively call CryptMsgGetParam, while varying dwIndex from 0 to (SignerCount - 1), where SignerCount is the value obtained from a previous call to CryptMsgGetParam with dwParamType set to CMSG_SIGNER_COUNT_PARAM.

Applicable only to decode.

pvData points to a CMSG_SIGNER_INFO struct.

CMSG_SIGNER_UNAUTH_ATTR_PARAM (10)

This parameter is used when decoding a received signed message to retrieve the unauthenticated attributes for the signer of the message.

To get the unauthenticated attributes for a given signer, call CryptMsgGetParam, with dwIndex equal to that signer's index.

Applicable only to decode.

pvData points to a CRYPT_ATTRIBUTES struct.

CMSG_TYPE_PARAM (1)

This parameter is used to retrieve the message type from a decoded message. When a message is received and its type is unknown, this parameter can be passed to retrieve the message type. This retrieved message type can then be compared to supported types to see if processing should be continued. For supported message types see the dwMessageType parameter of the CryptMsgOpenToDecode function.

Applicable only to decode.

pvData points to a DWORD which receives the message type.

dwIndex

The index for the parameter being retrieved, where applicable. When a parameter is not being retrieved, this parameter is ignored and should be set to zero.

pvData

Pointer to a buffer that receives the data retrieved. The form of this data will vary, depending on the parameter type.

This parameter can be NULL to set the size of this information for memory allocation purposes. For more information, see Common In/Out Parameter Conventions.

pcbData

Pointer to a variable that specifies the size, in bytes, of the buffer pointed to by the pvData parameter. When the function returns, the variable pointed to by the pcbData parameter contains the number of bytes stored in the buffer. This parameter can be NULL, only if pvData is NULL.

Return Values

If the function fails, the return value is FALSE (zero). If it succeeds, the return value is TRUE (non-zero).

To retrieve extended error information, use the GetLastError function.

The following table lists the error codes most commonly returned by the GetLastError function.

Error code	Description
CRYPT_E_ATTRIBUTES_MISSING	The message does not contain the requested attributes.
CRYPT_E_INVALID_INDEX	The index value is not valid.
CRYPT_E_INVALID_MSG_TYPE	The message type is invalid.
CRYPT_E_NOT_DECRYPTED	The message content has not been decrypted yet.
CRYPT_E_OID_FORMAT	The object identifier is badly formatted.
CRYPT_E_OSS_ERROR	OSS Certificate encode/decode error code base. Note, to get the OSS error subtract CRYPT_E_OSS_ERROR from the returned error and see asn1code.h for details on the error.
CRYPT_E_UNEXPECTED_ENCODING	The message is not encoded as expected.
E_INVALIDARG	One or more arguments are invalid.
ERROR_MORE_DATA	The specified is not large enough to hold the returned data.
Propagated errors that may be encountered:	For dwParamType == CMSG_COMPUTED_HASH_PARAM an error can be propagated from: CryptGetHashParam

Example

See Signed Message Example Code.

See Enveloped Message Example 1.

See Hashed Message Example Code.

QuickInfo

  Windows NT: Requires version 4.0 SP3 or later. Available also in IE 3.02 and later.
  Windows: Requires Windows 98 (or Windows 95 with IE 3.02 or later).
  Windows CE: Unsupported.
  Header: Declared in wincrypt.h.
  Import Library: Use crypt32.lib.

CryptMsgGetParam

Parameters

Return Values

Example

QuickInfo

See Also