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
Target platform |
Desktop |
Header |
Cardmod.h (include Cardmod.h) |