PFN_CMSG_EXPORT_KEY_AGREE callback function (wincrypt.h)
The PFN_CMSG_EXPORT_KEY_AGREE callback function encrypts and exports the content encryption key for a key agreement recipient of an enveloped message. PFN_CMSG_EXPORT_KEY_AGREE can be installed by using a CryptoAPI object identifier (OID). This function is called by the CryptMsgOpenToEncode function when its dwMsgType parameter is set to CMSG_ENVELOPED.
Syntax
PFN_CMSG_EXPORT_KEY_AGREE PfnCmsgExportKeyAgree;
BOOL PfnCmsgExportKeyAgree(
[in] PCMSG_CONTENT_ENCRYPT_INFO pContentEncryptInfo,
[in] PCMSG_KEY_AGREE_RECIPIENT_ENCODE_INFO pKeyAgreeEncodeInfo,
[in, out] PCMSG_KEY_AGREE_ENCRYPT_INFO pKeyAgreeEncryptInfo,
[in] DWORD dwFlags,
void *pvReserved
)
{...}
Parameters
[in] pContentEncryptInfo
A pointer to a CMSG_CONTENT_ENCRYPT_INFO structure that contains the content encryption key.
[in] pKeyAgreeEncodeInfo
A pointer to a CMSG_KEY_AGREE_RECIPIENT_ENCODE_INFO structure that specifies the key used to encrypt the content encryption key.
[in, out] pKeyAgreeEncryptInfo
A pointer to a CMSG_KEY_AGREE_ENCRYPT_INFO structure that contains the encrypted content encryption key.
[in] dwFlags
This value is not used. Set it to zero.
pvReserved
This parameter is reserved and must be NULL.
Return value
If the function succeeds, the return value is nonzero (TRUE).
If the function fails, the return value is zero (FALSE). For extended error information, call GetLastError.
Remarks
For each recipient key, the PFN_CMSG_EXPORT_KEY_AGREE function must update the EncryptedKey member of the CMSG_KEY_AGREE_KEY_ENCRYPT_INFO structure referred to by the rgpKeyAgreeKeyEncryptInfo member of the CMSG_KEY_AGREE_ENCRYPT_INFO structure pointed to by the pKeyAgreeEncryptInfo parameter. This function must use the pfnAlloc and pfnFree members of the CMSG_CONTENT_ENCRYPT_INFO structure pointed to by the pContentEncryptInfo parameter to manage memory for any values that it updates.
If, upon entry, the dwEncryptFlags member of the CMSG_CONTENT_ENCRYPT_INFO structure pointed to by the pContentEncryptInfo member is set to CMSG_CONTENT_ENCRYPT_PAD_ENCODED_LEN_FLAG, the ephemeral PublicKey member of the CERT_PUBLIC_KEY_INFO structure referred to by the OriginatorPublicKeyInfo member of the CMSG_KEY_AGREE_ENCRYPT_INFO structure pointed to by the pKeyAgreeEncryptInfo parameter should be padded with zeros to always obtain the same maximum encoded length.
You can use OID Support Functions to deploy this callback function. Wincrypt.h defines the following constants for this purpose.
You must define different callback functions for CAPI1 keys and Cryptography API: Next Generation (CNG) keys. Both functions have the same signature but use different OIDs. Which function is called depends on the value of the fCNG member of the CMSG_CONTENT_ENCRYPT_INFO structure pointed to by the pContentEncryptInfo parameter. The following table shows the relationship between the callback function and the value of the fCNG member.
fCNG value | Constant | Definition |
---|---|---|
FALSE | CMSG_OID_EXPORT_KEY_AGREE_FUNC or CMSG_OID_CAPI1_EXPORT_KEY_AGREE_FUNC | "CryptMsgDllExportKeyAgree" |
TRUE | CMSG_OID_CNG_EXPORT_KEY_AGREE_FUNC | "CryptMsgDllCNGExportKeyAgree" |
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 |