CRYPT_ENCRYPT_MESSAGE_PARA

The CRYPT_ENCRYPT_MESSAGE_PARA structure is used for encrypting messages.

typedef struct _CRYPT_ENCRYPT_MESSAGE_PARA {
    DWORD                       cbSize;
    DWORD                       dwMsgEncodingType;
    HCRYPTPROV                  hCryptProv;
    CRYPT_ALGORITHM_IDENTIFIER  ContentEncryptionAlgorithm;
    void                        *pvEncryptionAuxInfo;
    DWORD                       dwFlags;
    DWORD                       dwInnerContentType;
} CRYPT_ENCRYPT_MESSAGE_PARA, *PCRYPT_ENCRYPT_MESSAGE_PARA;
 

Members

cbSize

Must be set to the size of this data structure.

dwMsgEncodingType

The type of message encoding used. Note that it is always acceptable to specify both the certificate and message encoding types, by combining them with a bitwise OR operation as shown in the following example:

X509_ASN_ENCODING | PKCS_7_ASN_ENCODING
 

However, it is required only to specify the message encoding here. Currently defined encoding types are shown in the following table.

Encoding type	Value
X509_ASN_ENCODING	0x00000001
PKCS_7_ASN_ENCODING	0x00010000

hCryptProv

Specifies a handle to the cryptographic service provider to be used for encryption. The CSP identified by hCryptProv is used to do content encryption, recipient key encryption, and recipient key export. Its private key isn't used.

Unless there is a strong reason for passing in a specific cryptographic provider in hCryptProv, zero should be passed in. Passing in zero causes the default RSA or DSS provider to be acquired before doing hash, signature verification or recipient encryption operations.

ContentEncryptionAlgorithm

The object identifier of the encryption algorithm, for example, szOID_RSA_RC4, szOID_RSA_RC2CBC, or szOID_OIWSEC_desCBC. The hCryptProv CSP must support the encryption algorithm.

The following encryption algorithms require that the ContentEncryptionAlgorithm's Parameters contain an encoded 8 byte Initialization Vector (IV) (see CryptSetKeyParam for more information about the KP_IV parameter).

szOID_OIWSEC_desCBC (CALG_DES)
szOID_RSA_DES_EDE3_CBC (CALG_3DES)
szOID_RSA_RC4 (CALG_RC4)

If the ContentEncryptionAlgorithm.Parameters.cbData = 0, then, an ASN.1 encoded OCTET STRING containing the IV is automatically generated. The IV is created using CryptGenRandom.

Note, when a message is decrypted, if it has an Initialization Vector parameter, the cryptographic message functions will call CryptSetKeyParam with the Initialization Vector before doing the decrypt.

The szOID_RSA_RC2CBC(CALG_RC2) algorithm requires the Parameters to be encoded as a CRYPT_RC2_CBC_PARAMETERS data structure. If the ContentEncryptionAlgorithm.Parameters.cbData = 0, then, an ASN.1 encoded CRYPT_RC2_CBC_PARAMETERS containing the IV is automatically generated. It defaults to the dwVersion corresponding to the 40 bit length. To override the default 40 bit length, the pvEncryptionAuxInfo member can be updated to point to a CMSG_RC2_AUX_INFO data structure which contains the bit length.

pvEncryptionAuxInfo

pvEncryption points to a CMSG_RC2_AUX_INFO data structure for RC2 encryption or a CMSG_SP3_COMPATIBLE_AUX_INFO data structure for SP3 compatible encryption. For other than RC2 or SP3 compatible encryption, pvEncryptionAuxInfo must be set to NULL.

dwFlags

dwFlags is normally set to zero. However, if the encoded output is to be a CMSG_ENVELOPED inner content of an outer cryptographic message, such as a CMSG_SIGNED message, then, the CRYPT_MESSAGE_BARE_CONTENT_OUT_FLAG must be set. If it is not set, then it will be encoded as an inner content type of CMSG_DATA.

dwInnerContentType

dwInnerContentType is normally set to zero. It needs to be set if the input to be encrypted is the encoded output of another cryptographic message, such as, a CMSG_SIGNED. When set, it's one of the cryptographic message types, for example, CMSG_SIGNED.

See Also

CRYPT_ALGORITHM_IDENTIFIER, CryptEncryptMessage, CryptSignAndEncryptMessage