PFN_CMSG_IMPORT_KEY_AGREE callback function (wincrypt.h)

Article
02/22/2024

The PFN_CMSG_IMPORT_KEY_AGREE callback function imports a content encryption key for a key transport recipient of an enveloped message. PFN_CMSG_IMPORT_KEY_AGREE can be installed by using a CryptoAPI object identifier (OID). This function is called by the CryptMsgControl function when its dwCtrlType parameter is set to CMSG_CTRL_DECRYPT.

Syntax

PFN_CMSG_IMPORT_KEY_AGREE PfnCmsgImportKeyAgree;

BOOL PfnCmsgImportKeyAgree(
  [in]  PCRYPT_ALGORITHM_IDENTIFIER pContentEncryptionAlgorithm,
  [in]  PCMSG_CTRL_KEY_AGREE_DECRYPT_PARA pKeyAgreeDecryptPara,
  [in]  DWORD dwFlags,
        void *pvReserved,
  [out] HCRYPTKEY *phContentEncryptKey
)
{...}

Parameters

[in] pContentEncryptionAlgorithm

A pointer to a CRYPT_ALGORITHM_IDENTIFIER structure that specifies the algorithm used to encrypt the message contents and any associated parameters.

[in] pKeyAgreeDecryptPara

A pointer to a CMSG_CTRL_KEY_AGREE_DECRYPT_PARA structure that contains information about the key agreement recipient.

[in] dwFlags

This value is not used. Set it to zero.

pvReserved

This parameter is reserved and must be NULL.

[out] phContentEncryptKey

The address of a handle to the content encryption key returned by this function.

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.

If this callback function does not support the key encryption algorithm, it must return FALSE and call SetLastError with E_NOTIMPL.

Remarks

You can use OID Support Functions to deploy this callback function. Wincrypt.h defines the following constants for this purpose.

Constant	Definition
CMSG_OID_IMPORT_KEY_AGREE_FUNC or CMSG_OID_CAPI1_IMPORT_KEY_AGREE_FUNC	"CryptMsgDllImportKeyAgree"

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

Share via