CardConstructDHAgreement function

The CardConstructDHAgreement function performs a secret agreement calculation for Diffie Hellman (DH) key exchange by using a private key that is present on the card. For RSA-only card minidrivers, this entry point is not defined and is set to NULL in the CARD_DATA structure that is returned from CardAcquireContext. The CARD_DH_AGREEMENT structure changes to allow for return of a handle to the agreed secret. This raises a point about how to index the DH agreement on the card in an opaque manner. Maintaining a map file is unnecessary because Ncrypt makes no provision for persistent DH agreements and there is no way to retrieve one after a provider is closed. DH agreements are addressable on card through an opaque BYTE that the card minidriver maintains. This BYTE should be associated with a handle to a card-side agreement.

Syntax

DWORD WINAPI CardConstructDHAgreement(
  _In_    PCARD_DATA              pCardData,
  _Inout_ PCARD_DH_AGREEMENT_INFO pSecretInfo
);

Parameters

• pCardData [in]
  Context information for the call. For more information, see CardAcquireContext.

• pSecretInfo [in, out]
  Information that needs necessary context to calculate the secret agreement. This structure is used to return the results. The bSecretAgreementIndex member is updated within the passed-in structure to which pSecretInfo points.

Return value

Zero on success; otherwise, nonzero.

Remarks

Like CardRSADecrypt, the information is passed to this routine through the following structure.

#define CARD_DH_AGREEMENT_INFO_VERSION 2

typedef struct _CARD_DH_AGREEMENT_INFO
{
    DWORD  dwVersion;
    BYTE  bContainerIndex;
    DWORD  dwFlags;
    DWORD  dwPublicKey;
    PBYTE  pbPublicKey;
    PBYTE  pbReserved;
    DWORD  cbReserved;
    OUT BYTE  bSecretAgreementIndex;
} CARD_DH_AGREEMENT_INFO, *PCARD_DH_AGREEMENT_INFO;

Version 1 of the structure is not supported on any card minidriver that is intended to be certified for FIPS 140-2. If the dwVersion member has a value of 1, the function should return ERROR_REVISION_MISMATCH.

One can support as many agreements in parallel. If no space to store an agreement exists, the function should return SCARD_E_NO_MEMORY.

Note  You can implement bSecretAgreementIndex as a persistent counter on the card. We expect that a secret agreement is ephemeral in nature and not usable after the card has been removed. This index is also not designed to be used across processes.

Requirements

Send comments about this topic to Microsoft