PFN_CSP_GET_DH_AGREEMENT function pointer

This function is used when one of the parameters in the CARD_DERIVE_KEY structure (for pfnCardDeriveKey) is of KDF_NCRYPT_SECRET_HANDLE type. Call this function to retrieve the on-card handle. If KDF_NCRYPT_SECRET_HANDLE corresponds to a non-card secret agreement, this function returns failure.

This callback function is set by the KSP before calling CardAcquireContext.

Syntax

typedef DWORD ( WINAPI *PFN_CSP_GET_DH_AGREEMENT)(
  _In_        pCardData,
  _In_        hSecretAgreement,
  _Out_       pbSecretAgreement,
  _In_  DWORD dwFlags
);

Parameters

• pCardData [in]
  This should be the same structure that is passed into the pfnCardDeriveKey function.

• hSecretAgreement [in]
  This should be the KDF_VALUE_SECRET parameter that is passed into pfnCardDeriveKey through the pParameterList member of the CARD_DERIVE_KEY structure.

• pbSecretAgreement [out]
  This is returned by this callback and is the on-card handle maintained by the card minidriver itself. This secret agreement should not be destroyed during the call to pfnCardDeriveKey.

• dwFlags [in]
  Reserved. Set to 0.

Return value

Zero on success; otherwise, nonzero.

Remarks

Ephemeral nature of secret agreements on the card

The lifetime of pbSecretAgreement is limited by the length of time of the card minidriver context associated with the card or by a call to CardDestroyDHAgreement. All smart card DH agreements are ephemeral and are not retrievable after a card reset. Card minidrivers should not rely on calls to CardDestroyDHAgreement. They can keep them in volatile memory or clean them up during power-up.

Requirements

Send comments about this topic to Microsoft