CardChangeAuthenticator function
This function changes the authenticator for the affected card principal. It can be used to change a user’s PIN or to change the challenge/response key. The two usages are distinguished by use of a flag value.
Syntax
DWORD WINAPI CardChangeAuthenticator(
_In_ PCARD_DATA pCardData,
_In_ LPWSTR pwszUserId,
_In_ PBYTE pbCurrentAuthenticator,
_In_ DWORD dwcbCurrentAuthenticator,
_In_ PBYTE pbNewAuthenticator,
_In_ DWORD cbNewAuthenticator,
_In_ DWORD cRetryCount,
_In_ DWORD dwFlags,
_Out_opt_ PDWORD pcAttemptsRemaining
);
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.pbCurrentAuthenticator [in]
Pointer to a buffer that contains the current PIN information or a response to a previously issued challenge. See 'Remarks'.dwcbCurrentAuthenticator [in]
Byte count of the current PIN/response.pbNewAuthenticator [in]
Pointer to a buffer that contains the new PIN/key to be set.cbNewAuthenticator [in]
Pointer to a buffer that contains the new PIN/key to be set.cRetryCount [in]
Count of the times that a wrong PIN does not result in a blocked card.dwFlags [in]
Flags for the operation. See 'Remarks'.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
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 . This function is used when the authenticator is to be set and the value on the card is known. Generally, new cards are set up with common values. Therefore, this function is the logical choice to use when individualizing a card.
The allowed values for pwszUserId are wszCARD_USER_USER or wszCARD_USER_ADMIN as defined in Cardmod.h.
The interpretation of the Authenticator buffers is dictated by the value of dwFlags. Currently, the only supported values are CARD_AUTHENTICATE_PIN_PIN and CARD_AUTHENTICATE_PIN_CHALLENGE_RESPONSE. In the latter situation, the caller must have previously obtained a challenge value from the card through CardGetChallenge and this response is placed in the pbCurrentAuthenticator member of the context information to which pCardData points.
For a description of the usage of pdwcAttemptsRemaining, see the 'Remarks' section for CardAuthenticatePin.
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.
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.
A successful call to CardChangeAuthenticator should leave the card in an authenticated state.
Requirements
Target platform |
Desktop |
Header |
Cardmod.h (include Cardmod.h) |