CardAuthenticatePin function

The CardAuthenticatePin function submits a PIN value as a string to the card to establish the user’s identity and to satisfy access conditions for an operation to be undertaken on the user’s behalf.

Submission of a PIN to the card may involve some processing by the card minidriver to render the PIN information to a card-specific form.

Syntax

DWORD WINAPI CardAuthenticatePin(
  _In_      PCARD_DATA pCardData,
  _In_      LPWSTR     pwszUserId,
  _In_      PBYTE      pbPin,
  _In_      DWORD      cbPin,
  _Out_opt_ PDWORD     pdwcAttemptsRemaining
);

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.

• pbPin [in]
  Pointer to a buffer that contains the PIN information.

• cbPin [in]
  Byte count of the data in the PIN information buffer.

• pdwcAttemptsRemaining [out, optional]
  Count of times that an incorrect PIN can be presented to the card before the card is locked. The card minidriver tests this value for NULL before attempting to use it.

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” later in this specification.

various types of card principals, see ”Known Principals” later in this specification. The allowed values for the pwszUserId are wszCARD_USER_USER or wszCARD_USER_ADMINISTRATOR as defined in Cardmod.h.

For any other pwszUserId value, CardAuthenticatePin should return SCARD_E_INVALID_PARAMETER.

Note  Challenge/response is the preferred mechanism for administrator authentication to the card and the only authentication mode that Windows uses to authenticate an administrator.

If an incorrect PIN is presented, this function returns SCARD_W_WRONG_CHV. If the pdwcAttemptsRemaining parameter is non-NULL, it returns the number of remaining attempts.

On the last allowed attempt, the function returns SCARD_W_WRONG_CHV and the pdwcAttemptsRemaining parameter returns zero. For all attempts beyond the allowed number, the function returns SCARD_W_CHV_BLOCKED and the pdwcAttemptsRemaining parameter returns zero.

Implementations that do not support returning the count of remaining authentication attempts should return -1 for this value if pdwcAttemptsRemaining is non-NULL.

If the pbPin is NULL, the call fails with the SCARD_E_INVALID_PARAMETER error code.

Requirements

Send comments about this topic to Microsoft