CardAuthenticateChallenge function

The CardAuthenticateChallenge function performs authentication of a card principal by using a challenge/response protocol.

The caller of this function must have previously called CardGetChallenge to retrieve the challenge data from the card and computed the correct response data to submit with this call.

Syntax

DWORD WINAPI CardAuthenticateChallenge(
  _In_      PCARD_DATA pCardData,
  _In_      PBYTE      pbResponseData,
  _In_      DWORD      cbResponseData,
  _Out_opt_ PDWORD     pcAttemptsRemaining
);

Parameters

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

• pbResponseData [in]
  Pointer to a buffer that contains the response data that corresponds to the challenge.

• cbResponseData [in]
  Byte count of the response data.

• pcAttemptsRemaining [out, optional]
  Count of times that authentications to the card can fail before the card is locked. The card minidriver tests this pointer for NULL before attempting to use it.

Return value

Zero on success; otherwise, nonzero.

Remarks

A card principal is the user type (or role) that is associated with the authentication process that the smart card uses. For more information about the various types of card principals, see ”Known Principals” section of File System Requirements.

This challenge/response method is generally used to establish the context for privileged operations such as unblocking a user’s PIN.

If challenge/response authentication fails, the card minidriver returns SCARD_W_WRONG_CHV. In addition, if the pdwcAttemptsRemaining parameter is non-NULL, it returns the number of remaining attempts. On the last allowed attempt, the function returns SCARD_W_WRONG_CHV and the pdwcAttemptsRemaining parameter returns zero. For all attempts beyond the allowed number, the function returns SCARD_W_CHV_BLOCKED and the pdwcAttemptsRemaining parameter returns zero.

If CardGetChallenge was not called before calling CardAuthenticateChallenge, the count of remaining authentication attempts is not decremented.

Implementations that do not support returning the count of remaining authentication attempts should always return -1 for this value if pdwcAttemptsRemaining is non-NULL, even when the card is blocked.

The minidriver must use the following general rules:

• Failed authentication attempts should always leave the card in a deauthenticated state.
• Successful authentication attempts should leave the card authenticated to the authenticated principal.

Requirements

Send comments about this topic to Microsoft