CardChangeAuthenticator Function

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

The CardChangeAuthenticator function, defined by a smart card module, changes the authentication data associated with a smart card and a specified user type.

Syntax

DWORD WINAPI CardChangeAuthenticator(
  __in       PCARD_DATA pCardData,
  __in       LPWSTR pwszUserId,
  __in       PBYTE pbCurrentAuthenticator,
  __in       DWORD cbCurrentAuthenticator,
  __in       PBYTE pbNewAuthenticator,
  __in       DWORD cbNewAuthenticator,
  __in       DWORD cRetryCount,
  __in       DWORD dwFlags,
  __out_opt  PDWORD pcAttemptsRemaining
);

Parameters

pCardData [in]

A pointer to the CARD_DATA structure received from a call to the CardAcquireContext function.

pwszUserId [in]

A pointer to a string that contains the user ID. The ID is associated with the authentication data specified by the pbCurrentAuthenticator parameter.

This parameter can be one of the following values.

ValueMeaning
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.

 

pbCurrentAuthenticator [in]

A pointer to a buffer that contains the current authentication data. This data represents either a PIN or a response to an authentication challenge, depending on the value of the dwFlags parameter.

cbCurrentAuthenticator [in]

The size, in bytes, of the pbCurrentAuthenticator buffer.

pbNewAuthenticator [in]

A pointer to a buffer that contains the new authentication data. This data represents either a PIN or a response to an authentication challenge, depending on the value of the dwFlags parameter.

cbNewAuthenticator [in]

The size, in bytes, of the pbNewAuthenticator buffer.

cRetryCount [in]

The number of incorrect attempts at authentication that are allowed before the smart card is blocked.

To leave the number of allowed attempts unchanged, set the value of this parameter to zero.

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 zero.

dwFlags [in]

The type of authentication that this function performs. This parameter can be one of the following values.

ValueMeaning
CARD_UNBLOCK_PIN_CHALLENGE_RESPONSE
1

The authentication data in the pbCurrentAuthenticator and pbNewAuthenticator buffers are responses to a challenge returned by the CardGetChallenge function.

CARD_UNBLOCK_PIN_PIN
2

The authentication data in the pbCurrentAuthenticator and pbNewAuthenticator buffers are PIN data.

 

pcAttemptsRemaining [out, optional]

On output, a pointer to a DWORD variable that contains the number of times that incorrect authentication data can be submitted before the card is locked.

If this function has already returned a zero as the value of this parameter and is called again, the function fails and returns SCARD_W_CHV_BLOCKED.

If the value of this parameter is NULL, the smart card module ignores it.

Card modules that do not support a count of remaining authentication attempts should return a value of –1 for this parameter if the value of the parameter on input is not NULL.

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/valueDescription
SCARD_E_INVALID_PARAMETER
2148532228 (0x80100004)

The smart card module does not support changing the authentication data to the specified form.

SCARD_W_WRONG_CHV
2148532331 (0x8010006B)

The authentication data is incorrect.

SCARD_W_CHV_BLOCKED
2148532332 (0x8010006C)

The card has been blocked after too many attempts that use the wrong authentication data.

 

Requirements

Minimum supported client

Windows XP

Minimum supported server

Windows Server 2003

Header

Cardmod.h

See Also

Microsoft Base Smart Card Cryptographic Service Provider
CARD_DATA
CardAcquireContext
CardAuthenticatePin
CardGetChallenge

 

 

Send comments about this topic to Microsoft

Build date: 4/19/2011

Show: