CardChangeAuthenticatorEx function

This function changes the authenticator for the affected card principal. It can be used to change a PIN or unblock a PIN. The usages are distinguished by use of a flag value.

Syntax

DWORD WINAPI CardChangeAuthenticatorEx(
  _In_      PCARD_DATA pCardData,
  _In_      DWORD      dwFlags,
  _In_      PIN_ID     dwAuthenticatingPinId,
  _In_      PBYTE      pbAuthenticatingPinData,
  _In_      DWORD      cbAuthenticatingPinData,
  _In_      PIN_ID     dwTargetPinId,
  _In_      PBYTE      pbTargetData,
  _In_      DWORD      cbTargetData,
  _In_      DWORD      cbTargetData,
  _In_      DWORD      cRetryCount,
  _Out_opt_ PDWORD     pcAttemptsRemaining
);

Parameters

• pCardData [in]
  Context information for the call. For more information, see CardAcquireContext.

• dwFlags [in]
  Indication of whether this is a PIN change or unblock operation.

• dwAuthenticatingPinId [in]
  PIN identifier to be authenticated.

• pbAuthenticatingPinData [in]
  Pointer to a byte buffer that contains PIN data.

• cbAuthenticatingPinData [in]
  Byte count of the PIN data.

• dwTargetPinId [in]
  PIN identifier to be updated.

• pbTargetData [in]
  Pointer to a byte buffer that contains the new PIN.

• cbTargetData [in]
  Byte count of the new PIN data.

• cbTargetData [in]
  Byte count of the new PIN data.

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

• pcAttemptsRemaining [out, optional]
  Pointer to the count of remaining times that a wrong PIN does not result in a blocked card.

Return value

Zero on success; otherwise, nonzero.

Remarks

This function is used for all situations in which the authenticator is to be set.

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 allowed values for the PinId parameter are ROLE_USER, ROLE_ADMIN or 3 through 7. For any other PinId value, this function should return SCARD_E_INVALID_PARAMETER.

The interpretation of the Authenticator buffers is dictated by the value of dwFlags. Currently supported values are PIN_CHANGE_FLAG_UNBLOCK and PIN_CHANGE_FLAG_CHANGEPIN. If dwFlags indicates PIN_CHANGE_FLAG_UNBLOCK, the card minidriver performs an unblock operation. In this scenario, dwAuthenticatingPinId indicates the authenticator being verified and dwTargetPinId indicates the PIN identifier for the authenticator to be changed (the value should be different in the unblock scenario). If the authenticating PIN is a challenge response PIN, the caller must have previously obtained a challenge value from the card through CardGetChallenge.

For a description of the usage of pdwcAttemptsRemaining, see the comments for CardAuthenticatePin earlier in this specification.

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 0 is passed.

Implementations that enforce policies about the authenticator (such as PIN policies) should return SCARD_E_INVALID_PARAMETER if changing the authenticator or the form of the new authenticator do not comply with policy.

When CardChangeAuthenticatorEx is used to change a PIN, successful completion should leave the card in an authenticated state. If CardChangeAuthenticatorEx is used to unblock a PIN, the successful completion should leave the card in a deauthenticated state for both the unblocked PIN and the authenticating PIN.

Requirements

Send comments about this topic to Microsoft