CardAuthenticateChallenge Function

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

The CardAuthenticateChallenge function, defined by a smart card module, submits a response to a challenge issued by a smart card to authenticate a user.

Syntax

DWORD WINAPI CardAuthenticateChallenge(
  __in       PCARD_DATA pCardData,
  __in       PBYTE pbResponseData,
  __in       DWORD cbResponseData,
  __out_opt  PDWORD pcAttemptsRemaining
);

Parameters

pCardData [in]

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

pbResponseData [in]

A pointer to a buffer that contains the response to the corresponding challenge received as the ppbChallengeData parameter of a previous call to the CardGetChallenge function.

cbResponseData [in]

The size, in bytes, of the pbResponseData buffer.

pcAttemptsRemaining [out, optional]

A pointer to the count of remaining authentication attempts. The counter contains the number of times that an incorrect PIN can be submitted before the card is blocked.

If this function has already returned zero through this parameter and is called again, the function fails and returns SCARD_W_CHV_BLOCKED.

If the value of this parameter is NULL, the smart card module ignores it.

Card modules that do not support a count of remaining authentication attempts should return a value of –1 for this parameter.

Return Value

If the function succeeds, it returns zero.

If the function fails, it returns a nonzero error value or one of the following possible error values.

Return code/valueDescription
SCARD_W_WRONG_CHV
2148532331 (0x8010006B)

The response is not the correct response to the specified challenge.

SCARD_W_CHV_BLOCKED
2148532332 (0x8010006C)

The card has been blocked after too many attempts that use the wrong response data.

 

Remarks

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

Requirements

Minimum supported client

Windows XP

Minimum supported server

Windows Server 2003

Header

Cardmod.h

See Also

Microsoft Base Smart Card Cryptographic Service Provider
CARD_DATA
CardAcquireContext
CardGetChallenge

 

 

Send comments about this topic to Microsoft

Build date: 4/19/2011

Show: