CardGetChallengeEx function

Besides authentication by using a PIN, a card principal can be authenticated by using a challenge/response protocol in which the card generates a block of challenge data.

The authenticating caller must compute the response to the challenge by using shared knowledge of a key and submit the response back to the card by calling CardGetChallengeEx. If the response is correct, the principal is authenticated to the card.

Syntax

 WINAPI CardGetChallengeEx(
  _In_  PCARD_DATA pCardData,
  _In_  PIN_ID     PinId,
  _Out_ PBYTE      *ppbChallengeData,
  _Out_ PDWORD     pcbChallengeData,
  _In_  DWORD      dwFlags
);

Parameters

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

• PinId [in]
  PIN identifier to be authenticated.

• ppbChallengeData [out]
  Pointer to byte pointer to receive the challenge data from the card.

• pcbChallengeData [out]
  Byte count of the challenge data.

• dwFlags [in]
  Reserved. Set to 0.

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. For security reasons, implementers of card minidrivers are advised to produce a design in which the challenge and response values are not invariant so that these values cannot be replayed.

The caller may choose to not use the challenge value. It is significant only if an authentication is attempted by using it. It is discarded if the next command to the card is not an authentication attempt to use it. For more information, see CardAuthenticateChallenge earlier in this specification. The smart card’s internal operating system should be designed to enforce this behavior.

The challenge buffer is allocated by the card minidriver and freed by the caller by using PFN_CSP_FREE.

If PinId is not set to ChallengeResponsePinType, the function should return SCARD_E_INVALID_PARAMETER.

Requirements

Send comments about this topic to Microsoft