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
Target platform |
Desktop |
Header |
Cardmod.h (include Cardmod.h) |