Compartir a través de


CardGetChallenge function

This topic is not current. For the most current information about the Smart Card API, see Smart Card Minidriver Specification.

The CardGetChallenge function, defined by a smart card module, authenticates a user with a challenge and response.

Syntax

DWORD WINAPI CardGetChallenge(
  _In_  PCARD_DATA pCardData,
  _Out_ PBYTE      *ppbChallengeData,
  _Out_ PDWORD     pcbChallengeData
);

Parameters

pCardData [in]

A pointer to a CARD_DATA structure received from a call to the CardAcquireContext function.

ppbChallengeData [out]

A pointer to a PBYTE value that receives the challenge data from the smart card.

pcbChallengeData [out]

A pointer to a DWORD value that specifies the size, in bytes, of the challenge data contained in the ppbChallengeData parameter.

Return value

If the function succeeds, the function returns zero.

If the function fails, it returns a nonzero value.

Remarks

The smart card creates challenge data by using its administrative key and places this data in the ppbChallengeData parameter. The caller then computes the response to the challenge by using shared knowledge of that key and submits the response to the card by calling the CardAuthenticateChallenge function. If the response is correct, the user is authenticated.

This authentication technique is normally used for privileged operations such as unblocking a user's PIN. To help avoid possible spoofing of identity, card module implementations should require that identical challenge and response values are not used more than once.

If the next call to the smart card module is not a call to the CardAuthenticateChallenge function that uses the challenge data received in the ppbChallengeData buffer, this function should discard that data.

Requirements

Minimum supported client
Windows XP [desktop apps only]
Minimum supported server
Windows Server 2003 [desktop apps only]
Header
Cardmod.h

See also

Microsoft Base Smart Card Cryptographic Service Provider

CARD_DATA

CardAcquireContext

CardAuthenticateChallenge