CardUnblockPin function

Article
05/31/2018

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

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 2148532228 (0x80100004)	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 [desktop apps only]
Minimum supported server	Windows Server 2003 [desktop apps only]
Header	Cardmod.h