CardAuthenticatePin Function

The CardAuthenticatePin function, defined by a smart card module, authenticates a user by submitting a PIN to the smart card.

Syntax

DWORD WINAPI CardAuthenticatePin(
  __in       PCARD_DATA pCardData,
  __in       LPWSTR pwszUserId,
  __in       PBYTE pbPin,
  __in       DWORD cbPin,
  __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. This ID is associated with the PIN specified by the pbPin parameter.

  This parameter can be one of the following values.

  Value	Meaning
  wszCARD_USER_EVERYONE L"anonymous"	The user is anonymous.
  wszCARD_USER_USER L"user"	The user is not an administrator.
  wszCARD_USER_ADMIN L"admin"	The user is an administrator. We recommend that administrators be authenticated by using the CardGetChallenge and CardAuthenticateChallenge functions instead of by using this function.

• pbPin [in]
  A pointer to a buffer that contains the PIN.

• cbPin [in]
  The size, in bytes, of the pbPin buffer.

• pcAttemptsRemaining [out, optional]
  On output, a pointer to a DWORD variable that contains the number of times that an incorrect PIN 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.

Requirements

See Also

CARD_DATA

CardAcquireContext

Microsoft Base Smart Card Cryptographic Service Provider

Send comments about this topic to Microsoft

Build date: 3/5/2009