CardUnblockPin function

The CardUnblockPin function is used to unblock a card that has become blocked by too many incorrect PIN entry attempts.

The unblock function is atomic in that, authentication and unblocking of the card must occur as a single operation. Therefore, authentication information and the new user PIN must be presented when the call is made.

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]
  Context information for the call. For more information, see CardAcquireContext.

• pwszUserId [in]
  String that specifies the card principal that is associated with the PIN.

• pbAuthenticationData [in]
  Pointer to the CardGetChallengeEx response data or the PIN unblock key (PUK) value for cards that support only PUK for unblocking.

• cbAuthenticationData [in]
  Byte count of the authentication data.

• pbNewPinData [in]
  Pointer to a buffer that contains the new PIN to be set.

• cbNewPinData [in]
  Byte count of the data to which pbNewPinData points.

• cRetryCount [in]
  Count of times that a wrong PIN does not result in a blocked card.

• dwFlags [in]
  Set to CARD_AUTHENTICATE_PIN_CHALLENGE_RESPONSE.

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.

The authentication data for the operation is a response that corresponds to the challenge that is acquired by a call to CardGetChallenge. This is distinguished by the CARD_ AUTHENTICATE _PIN_CHALLENGE_RESPONSE flag value that identifies the buffer because that contains a response to a challenge.

For example, a typical scenario is unblocking the user PIN by using administrator challenge/response.

In addition, for general conventions and guidelines for using PIN and challenge/response authenticators, see Card PIN Operations earlier in this specification. For administrators, challenge/response support is mandatory. For users, challenge/response support is not supported.

If zero is passed for cRetryCount, the PIN retry maximum value is unchanged. Implementations that do not support setting the retry count should return an invalid parameter error if a retry value other than zero is passed. In that situation, the challenge should be considered invalid and a fresh one be requested.

A successful call to CardUnblockPin should leave the card in a deauthenticated state.

If CardUnblockPin is called with a NULL value for pbAuthenticationData, the expected error code is SCARD_E_INVALID_PARAMETER.

Requirements

Send comments about this topic to Microsoft