CardUnblockPin Function

The CardUnblockPin function, defined by a smart card module, unblocks a smart card that has become blocked after exceeding the maximum number of incorrect PIN entry attempts. The function also authenticates a user to the smart card.

Syntax

DWORD WINAPI CardUnblockPin(
  __in  PCARD_DATA pCardData,
  __in  LPWSTR pwszUserId,
  __in  PBYTE pbAuthenticationData,
  __in  DWORD cbAuthenticationData,
  __in  PBYTE pbNewPinData,
  __in  DWORD cbNewPinData,
  __in  DWORD cRetryCount,
  __in  DWORD dwFlags
);

Parameters

pCardData [in]
A pointer to a CARD_DATA structure received from a call to the CardAcquireContext function.

pwszUserId [in]
A pointer to a string that contains the ID of the user associated with the PIN specified to unblock.

This parameter can be one of the following values.

Value	Meaning
wszCARD_USER_EVERYONE L"anonymous"	The user is an anonymous user.
wszCARD_USER_USER L"user"	The user is not an administrator.
wszCARD_USER_ADMIN L"admin"	The user is an administrator.

pbAuthenticationData [in]
A pointer to a buffer that contains the authentication data. This data represents either a PIN or a response to an authentication challenge, depending on the value of the dwFlags parameter.
cbAuthenticationData [in]
The size, in bytes, of the data contained in the pbAuthenticationData buffer.
pbNewPinData [in]
A pointer to a buffer that contains the new PIN to be set.
cbNewPinData [in]
The size, in bytes, of the data contained in the pbNewPinData buffer.
cRetryCount [in]
The number of incorrect attempts at authentication using the new PIN that are allowed before the smart card is blocked again.

To leave the number of allowed attempts unchanged, set the value of this parameter to –1. Card modules that do not support setting the number of allowed attempts should return SCARD_E_INVALID_PARAMETER if this parameter is set to any value other than –1.

dwFlags [in]
A DWORD value that represents the type of authentication that this function performs.

This parameter can be one of the following values.

Value	Meaning
CARD_UNBLOCK_PIN_CHALLENGE_RESPONSE 1	The authentication data in the pbAuthenticationData parameter is a response to a challenge from a previous call to the CardGetChallenge function.
CARD_UNBLOCK_PIN_PIN 2	The authentication data in the pbAuthenticationData parameter is a PIN.

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.

Return code/value	Description
SCARD_E_INVALID_PARAMETER 21485322280x80100004	The value of the pbAuthenticationData parameter is NULL.

Remarks

This function both unblocks the PIN and authenticates the user.

Requirements

Minimum supported client	Windows XP, Windows 2000 Professional with SP4
Minimum supported server	Windows Server 2003, Windows 2000 Server with SP4
Header	Cardmod.h

Share via