CardAuthenticatePin function

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

The CardAuthenticatePin function, defined by a smart card module, authenticates a user by submitting a PIN to the smart card.

Syntax

DWORD WINAPI CardAuthenticatePin(
  _In_      PCARD_DATA pCardData,
  _In_      LPWSTR     pwszUserId,
  _In_      PBYTE      pbPin,
  _In_      DWORD      cbPin,
  _Out_opt_ PDWORD     pcAttemptsRemaining
);

Parameters

pCardData [in]

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

pwszUserId [in]

A pointer to a string that contains the user ID. This ID is associated with the PIN specified by the pbPin parameter.

This parameter can be one of the following values.

Value	Meaning
wszCARD_USER_EVERYONE L"anonymous"	The user is anonymous.
wszCARD_USER_USER L"user"	The user is not an administrator.
wszCARD_USER_ADMIN L"admin"	The user is an administrator. We recommend that administrators be authenticated by using the CardGetChallenge and CardAuthenticateChallenge functions instead of by using this function.

pbPin [in]

A pointer to a buffer that contains the PIN.

cbPin [in]

The size, in bytes, of the pbPin buffer.

pcAttemptsRemaining [out, optional]

On output, a pointer to a DWORD variable that contains the number of times that an incorrect PIN can be submitted before the card is locked.

If this function has already returned a zero as the value of 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 if the value of the parameter on input is not NULL.

Return value

If the function succeeds, the function returns zero.

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

Requirements

See also

CARD_DATA

CardAcquireContext

Microsoft Base Smart Card Cryptographic Service Provider