Share via

CryptMsgGetParam (Compact 2013)

  • Article

3/28/2014

This function acquires a message parameter after a cryptographic message has been encoded or decoded. This function is called after the final CryptMsgUpdate call.

Syntax

BOOL WINAPI CryptMsgGetParam(
  HCRYPTMSG hCryptMsg,
  DWORD dwParamType,
  DWORD dwIndex,
  void* pvData,
  DWORD* pcbData
);

Parameters

  • hCryptMsg
    [in] Handle of a cryptographic message.

  • dwParamType
    [in] Indicates the parameter types of data to be retrieved. The type of data to be retrieved determines the type of structure to use for pvData.

    For an encoded message, only the CMSG_BARE_CONTENT, CMSG_ENCODE_SIGNER, CMSG_CONTENT_PARAM and CMSG_COMPUTED_HASH_PARAM dwParamTypes are valid.

    Value

    Description

    CMSG_ATTR_CERT_COUNT_PARAM

    pvData data type: pointer to a DWORD

    Returns the count of the attribute certificates in a SIGNED or ENVELOPED message.

    CMSG_ATTR_CERT_PARAM

    pvData data type: pointer to a BYTE array

    Retrieves an attribute certificate. To get all the attribute certificates, call CryptMsgGetParam varying dwIndex from 0 to the number of attributes minus one.

    CMSG_BARE_CONTENT_PARAM

    pvData data type: pointer to a BYTE array

    Retrieves the encoded content of an encoded cryptographic message, without the outer layer of the CONTENT_INFO structure. That is, only the encoding of the PKCS #7 defined ContentInfo.content field is returned.

    CMSG_CERT_COUNT_PARAM

    pvData data type: pointer to DWORD

    Returns the number of certificates in a received SIGNED or ENVELOPED message.

    CMSG_CERT_PARAM

    pvData data type: pointer to a BYTE array

    Returns a signer's certificate. To get all of the signer's certificates, call CryptMsgGetParam, varying dwIndex from 0 to the number of available certificates minus one.

    CMSG_COMPUTED_HASH_PARAM

    pvData data type: pointer to a BYTE array

    Returns the hash calculated of the data in the message. This type is applicable to both encode and decode.

    CMSG_CONTENT_PARAM

    pvData data type: pointer to a BYTE array

    Returns the whole PKCS #7 message from a message opened to encode. Retrieves the inner content of a message opened to decode. If the message is enveloped, the inner type is data, and CryptMsgControl has been called to decrypt the message, the decrypted content is returned. If the inner type is not data, the encoded BLOB that requires further decoding is returned. If the message is not enveloped and the inner content is DATA, the returned data is the octets of the inner content. This type is applicable to both encode and decode.

    For decoding, if the type is CMSG_DATA, the content's octets are returned. Otherwise, the encoded inner content is returned.

    CMSG_CRL_COUNT_PARAM

    pvData data type: pointer to DWORD

    Returns the count of CRLs in a received, SIGNED or ENVELOPED message.

    CMSG_CRL_PARAM

    pvData data type: pointer to a BYTE array

    Returns a CRL. To get all the CRLs, call CryptMsgGetParam, varying dwIndex from 0 to the number of available CRLs minus one.

    CMSG_ENCODED_MESSAGE

    pvData data type: pointer to a BYTE array

    Changes 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. 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. This can be used, for instance, to add a time-stamp attribute to a message.

    CMSG_ENCODED_SIGNER

    pvData data type: pointer to a BYTE array

    Returns the encoded CMSG_SIGNER_INFO signer information for a message signer.

    CMSG_ENCRYPTED_DIGEST

    pvData data type: pointer to a BYTE array

    Returns the encrypted hash of a signature. Typically used for performing time-stamping.

    CMSG_ENCRYPT_PARAM

    pvData data type: pointer to a BYTE array for a CRYPT_ALGORITHM_IDENTIFIER structure.

    Returns the encryption algorithm used to encrypted the message.

    CMSG_ENVELOPE_ALGORITHM_PARAM

    pvData data type: pointer to a BYTE array for a CRYPT_ALGORITHM_IDENTIFIER structure.

    Returns the encryption algorithm used to encrypt an ENVELOPED message.

    CMSG_HASH_ALGORITHM_PARAM

    pvData data type: pointer to a BYTE array for a CRYPT_ALGORITHM_IDENTIFIER structure.

    Returns the hash algorithm used to hash the message when it was created.

    CMSG_HASH_DATA_PARAM

    pvData data type: pointer to a BYTE array

    Returns the hash value stored in the message when it was created.

    CMSG_INNER_CONTENT_TYPE_PARAM

    pvData data type: pointer to a BYTE array to receive a NULL-terminated object identifier (OID) string.

    An OID is a number that uniquely identifies an object class or attribute. An object identifier is represented as a dotted decimal string, such as 1.2.3.4. Object identifiers are organized into a global hierarchy. Registration authorities issue root object identifiers to individuals or organizations, who manage the hierarchy below their root object identifier.

    Returns the inner content type of a received message. This type is not applicable to messages of type DATA.

    CMSG_RECIPIENT_COUNT_PARAM

    pvData data type: pointer to a DWORD

    Returns the number of key transport recipients of an ENVELOPED received message.

    CMSG_CMS_RECIPIENT_COUNT_PARAM

    pvData data type: pointer to DWORD

    Returns the total count of all message recipients including key agreement and mail list recipients.

    CMSG_RECIPIENT_INDEX_PARAM

    pvData data type: pointer to a DWORD

    Returns the index of the key transport recipient used to decrypt an ENVELOPED message. This value is available only after a message has been decrypted.

    CMSG_CMS_RECIPIENT_INDEX_PARAM

    pvData data type: pointer to a DWORD

    Returns the index of the key transport, key agreement, or mail list recipient used to decrypt an ENVELOPED message.

    CMSG_CMS_RECIPIENT_ENCRYPTED_KEY_INDEX_PARAM

    pvData data type: pointer to a DWORD

    Returns the index of the encrypted key of a key agreement recipient used to decrypt an ENVELOPED message.

    CMSG_RECIPIENT_INFO_PARAM

    pvData data type: pointer to a BYTE array to receive a CERT_INFO structure.

    Returns certificate information about a key transport message's recipient. To get certificate information on all key transport message's recipients, repetitively call CryptMsgGetParam, varying dwIndex from 0 to the number of recipients minus one. Only the Issuer, SerialNumber, and PublicKeyAlgorithm members of the CERT_INFO structure returned are available and valid.

    CMSG_CMS_RECIPIENT_INFO_PARAM

    pvData data type: pointer to a BYTE array to receive a CMSG_CMS_RECIPIENT_INFO structure.

    Returns information about a key transport, key agreement, or mail list recipient. It is not limited to key transport message recipients. To get information on all of a message's recipients, repetitively call CryptMsgGetParam, varying dwIndex from 0 to the number of recipients minus one.

    CMSG_SIGNER_AUTH_ATTR_PARAM

    pvData data type: pointer to a BYTE array to receive a CRYPT_ATTRIBUTES structure.

    Returns the authenticated attributes of a message signer. To retrieve the authenticated attributes for a specified signer, call CryptMsgGetParam with dwIndex equal to that signer's index.

    CMSG_SIGNER_CERT_INFO_PARAM

    pvData data type: pointer to a BYTE array to receive the CERT_INFO structure.

    Returns information on a message signer needed to identify the signer's certificate. A certificate's Issuer and SerialNumber can be used to uniquely identify a certificate for retrieval. To retrieve information for all the signers, repetitively call CryptMsgGetParam varying dwIndex from 0 to the number of signers minus one. Only the Issuer and SerialNumber fields in the CERT_INFO structure returned contain available, valid data.

    CMSG_SIGNER_CERT_ID_PARAM

    pvData data type: pointer to a BYTE array to receive a CERT_ID structure.

    Returns information on a message signer needed to identify the signer's public key. This could be a certificate's Issuer and SerialNumber, a KeyID, or a HashId. To retrieve information for all the signers, call CryptMsgGetParam varying dwIndex from 0 to the number of signers minus one.

    CMSG_SIGNER_COUNT_PARAM

    pvData data type: pointer to a DWORD

    Returns the number of signers of a received SIGNED message.

    CMSG_SIGNER_HASH_ALGORITHM_PARAM

    pvData data type: pointer to a BYTE array to receive the CRYPT_ALGORITHM_IDENTIFIER structure.

    Returns the hash algorithm used by a signer of the message. To get the hash algorithm for a specified signer, call CryptMsgGetParam with dwIndex equal to that signer's index.

    CMSG_SIGNER_INFO_PARAM

    pvData data type: pointer to a BYTE array to receive a CMSG_SIGNER_INFO structure.

    Returns information on a message signer. This includes the issuer and serial number of the signer's certificate and authenticated and unauthenticated attributes of the signer's certificate. To retrieve signer information on all of the signers of a message, call CryptMsgGetParam varying dwIndex from 0 to the number of signers minus one.

    CMSG_CMS_SIGNER_INFO_PARAM

    pvData data type: pointer to a BYTE array to receive a CMSG_CMS_SIGNER_INFO structure.

    Returns information on a message signer. This includes a signerId and authenticated and unauthenticated attributes. To retrieve signer information on all of the signers of a message, call CryptMsgGetParam varying dwIndex from 0 to the number of signers minus one.

    CMSG_SIGNER_UNAUTH_ATTR_PARAM

    pvData data type: pointer to a BYTE array to receive a CRYPT_ATTRIBUTES structure.

    Returns a message signer's unauthenticated attributes. To retrieve the unauthenticated attributes for a specified signer, call CryptMsgGetParam with dwIndex equal to that signer's index.

    CMSG_TYPE_PARAM

    pvData data type: pointer to a DWORD

    Returns the message type of a decoded message of unknown type. The retrieved message type can be compared to supported types to determine whether processing can continued. For supported message types, see the dwMessageType parameter of CryptMsgOpenToDecode.

    CMSG_UNPROTECTED_ATTR_PARAM

    pvData data type: pointer to a BYTE array to receive a CMSG_ATTR structure.

    Returns the unprotected attributes in an enveloped message.

    CMSG_VERSION_PARAM

    pvData data type: pointer to a DWORD

    Returns the version of the decoded message. For detailed information, see the table in the Remarks section.
  • dwIndex
    [in] Index for the parameter being retrieved, where applicable. When a parameter is not being retrieved, this parameter is ignored and is set to zero.

  • pvData
    [out] Pointer to a buffer that receives the data retrieved. The form of this data will vary depending on the value of the dwParamType parameter.

    This parameter can be NULL to set the size of this information for memory allocation purposes.

    When processing the data returned in this buffer, applications need to use the actual size of the data returned. The actual size can be slightly smaller than the size of the buffer specified on input. (On input, buffer sizes are usually specified large enough to ensure that the largest possible output data will fit in the buffer.) On output, the variable pointed to by this parameter is updated to reflect the actual size of the data copied to the buffer.

  • pcbData
    [in, out] 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.

Return Value

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

If the function fails, the return value is zero (FALSE). For extended error information, call GetLastError.

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

Return 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_UNEXPECTED_ENCODING

The message is not encoded as expected.

E_INVALIDARG

One or more arguments are invalid.

ERROR_MORE_DATA

The specified buffer is not large enough to hold the returned data.

For dwParamType CMSG_COMPUTED_HASH_PARAM, an error can be propagated from CryptGetHashParam.

If the function fails, GetLastError returns an ASN.1 encoding/decoding error.

Remarks

The following version numbers are returned by calls to CryptMsgGetParam with dwParamType set to CMSG_VERSION_PARAM are defined:

  • CMSG_SIGNED_DATA_V1
  • CMSG_SIGNED_DATA_V3
  • CMSG_SIGNED_DATA_PKCS_1_5_VERSION
  • CMSG_SIGNED_DATA_CMS_VERSION
  • CMSG_SIGNER_INFO_V1
  • CMSG_SIGNER_INFO_V3
  • CMSG_SIGNER_INFO_PKCS_1_5_VERSION
  • CMSG_SIGNER_INFO_CMS_VERSION
  • CMSG_HASHED_DATA_V0
  • CMSG_HASHED_DATA_V2
  • CMSG_HASHED_DATA_PKCS_1_5_VERSION
  • CMSG_HASHED_DATA_CMS_VERSION
  • CMSG_ENVELOPED_DATA_V0
  • CMSG_ENVELOPED_DATA_V2
  • CMSG_ENVELOPED_DATA_PKCS_1_5_VERSION
  • CMSG_ENVELOPED_DATA_CMS_VERSION

Requirements

Header

wincrypt.h

Library

crypt32.lib

See Also

Reference

Cryptography Functions
CryptMsgUpdate
CryptMsgOpenToDecode
CryptMsgOpenToEncode