CardGetChallengeEx function

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

The CardGetChallengeEx function, defined by a smart card module, authenticates a user in a with a specified role with a challenge and response

Syntax

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

Parameters

pCardData [in]

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

PinId [in]

The PIN identifier of the role to be authenticated.

Value Meaning
ROLE_EVERYONE
0
Specifies any requester, including unauthenticated or anonymous users.
ROLE_USER
1
Specifies a user client of the card, who proves his identity to the card by use of a PIN.
ROLE_ADMIN
2
Specifies the card issuer or other party with an administrative relationship to the card or data on the card. Uses a special PIN or KEY which may or may not be unique to the card or user, to perform administrative tasks that the user cannot perform without use of this data, such as PIN unblocking.

ppbChallengeData [out]

A pointer to a pointer to a buffer that receives the challenge data returned from the card.

pcbChallengeData [in]

The number of bytes of challenge data in the buffer pointed to by the ppbChallengeData parameter.

dwFlags [in]

Reserved. Must be set to zero.

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/value Description
SCARD_E_INVALID_PARAMETER
0x80100004L
One or more of the supplied parameters could not be properly interpreted.

Remarks

This authentication technique is normally 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 elect not to 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 using it (see CardAuthenticateChallenge). 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.

Requirements

Minimum supported client
Windows Vista [desktop apps only]
Minimum supported server
Windows Server 2008 [desktop apps only]