CardAuthenticateEx function

The CardAuthenticateEx function handles PIN authentication operations to the card.

This function replaces the CardAuthenticate function of earlier versions of these specifications and adds support for the following PIN types:

• External PINs, which are PINs that are accessed from a device that is connected to the computer.
• Challenge/response PINs.
• Secure PIN channels.
• Session PINs.

Syntax

DWORD WINAPI CardAuthenticateEx(
  _In_      PCARD_DATA pCardData,
  _In_      PIN_ID     PinId,
  _In_      DWORD      dwFlags,
  _In_      PBYTE      pbPinData,
  _In_      DWORD      cbPinData,
  _Out_opt_ PBYTE      *ppbSessionPin,
  _Out_opt_ PDWORD     pcbSessionPin,
  _Out_opt_ PDWORD     pcAttemptsRemaining
);

Parameters

• pCardData [in]
  Context information for the call. For more information, see CardAcquireContext.

• PinId [in]
  PIN identifier to be authenticated, such as ROLE_USER.

• dwFlags [in]
  Flags for the operation. See 'Remarks' section.

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

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

• ppbSessionPin [out, optional]
  Optional pointer to a byte buffer to receive a session PIN.

• pcbSessionPin [out, optional]
  Optional pointer to a byte count of the session PIN data.

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

Return value

Zero on success: otherwise, nonzero.

Expected card behavior

On success, the user can perform any action that requires PinId to be authenticated. This state persists until one of the following occurs:

• Either CardDeauthenticate or CardDeauthenticateEx is called.
• The card is reset through the Winscard API.
• The card loses power.

Note  This does not apply if CARD_AUTHENTICATE_GENERATE_SESSION_PIN is specified in dwFlags.

The allowed values for PinId are ROLE_USER, ROLE_ADMIN or 3 through 7. For any other PinId value, CardAuthenticatePinEx should return SCARD_E_INVALID_PARAMETER.

When multiple roles are authenticated via multiple calls, once ROLE_ADMIN is authenticated, all other roles can be deauthenticated. If a user role is authenticated, ROLE_ADMIN can be deauthenticated.

For UnblockOnly PINS, it is acceptable for CardAuthenticateEx to return SCARD_E_INVALID_PARAMETER or SCARD_E_UNSUPPORTED_FEATURE. An UnblockOnly PIN is specified by setting the SECRET_PURPOSE member of pbPinData to UnblockOnlyPin.

Failed authentication attempts

If an incorrect PIN is presented, this function returns SCARD_W_WRONG_CHV. If the pcAttemptsRemaining parameter is non-NULL, this function returns the number of remaining attempts. On the last allowed attempt, the function returns SCARD_W_WRONG_CHV and the pcAttemptsRemaining parameter returns zero. For all attempts beyond the allowed number, the function returns SCARD_W_CHV_BLOCKED and the pcAttemptsRemaining parameter returns zero.

If the minidriver does not support returning the count of remaining authentication attempts, it should return -1 for the pcAttemptsRemaining value if pcAttemptsRemaining is non-NULL.

Presenting an incorrect PIN for a particular role (as specified through PinId) should result in that role being deauthenticated on the card, but should not affect other roles that are already authenticated to the card.

If the pointer to pbPinData is NULL, the call fails with the error code SCARD_E_INVALID_PARAMETER.

Session PIN

A session PIN is defined as a temporary PIN. This PIN type is generated by the card and expires upon termination of the session.

Cards that support session PINs can return the generated session PIN. If the ppbSessionPin parameter is non-NULL and the card can generate a session PIN, the call should allocate ppbSessionPin to hold the session PIN. In this situation, pcbSessionPin should contain the length of the session PIN. Windows caches the session PIN (according to the PIN caching policy in the PIN_CACHE_POLICY structure in pbPinData) and presents it to the card for the next call to CardAuthenticateEx.

After a successful generation of a session, Windows calls CardAuthenticateEx and sets CARD_AUTHENTICATE_SESSION_PIN in dwFlags. In this situation, the actual PIN is not passed and the minidriver must use the session PIN in pbPinData and cbPinData to authenticate the card. If the CARD_AUTHENTICATE_GENERATE_SESSION_PIN flag is set in dwFlags and either ppbSessionPin or pcbSessionPin is set to NULL, the call must fail with SCARD_E_INVALID_PARAMETER.

If this session PIN is invalid, SCARD_WRONG_CHV should be returned, pcAttemptsRemaining is not expected to hold valid data, and the retry count of the original PIN should not be decremented. The retry counter for the session PIN should be decremented.

External PIN

An external PIN (ExternalPinType returned in PIN_INFO) is defined as a PIN that is stored on a device that is connected to the computer. For example, this might be a BIO match-on-card PIN. In this situation, Windows does not prompt the user for a PIN but calls CardAuthenticateEx with an NULL value for pbPinData for the PIN.

An external PIN is specified by setting the SECRET_PURPOSE member of PIN_INFO structure to ExternalPinType.

The minidriver must always return a session PIN when processing an external PIN. This allows applications to perform PIN caching.

In this call, a minidriver can display its own UI windows, as long as CARD_PIN_SILENT_CONTEXT was not set in dwFlags.

If CARD_PIN_SILENT_CONTEXT is set and the PIN information is passed in through pbPinData, the minidriver must perform pin verification silently. If CARD_PIN_SILENT_CONTEXT is set and no PIN information is passed in pbPinData, the minidriver must return SCARD_E_INVALID_PARAMETER.

If the PIN is a biometric PIN, CardAuthenticateEx should expect a session pin as input in the pbPinData parameter. This session pin may be generated by a prior call to CardAuthenticateEx with CARD_AUTHENTICATE_GENERATE_SESSION_PIN set in dwFlags

The handle of the parent window and a context string are passed to the minidriver before calling CardAuthenticateEx by calling CardSetProperty with the following parameters:

• CardSetProperty (CP_PARENT_WINDOW, YYYYY) where YYYYY is a HWND.
• CardSetProperty (CP_PIN_CONTEXT_STRING, YYYYY) where YYYYY is a string.

Important  Displaying a UI when CARD_PIN_SILENT_CONTEXT was set results in operating system instability. The minidriver must always provide an option to close the UI windows to let users use alternative credential providers for authentication.

Secure PIN channel

A secure PIN channel is enabled if one of the following conditions are true:

• The Common Criteria Group Policy is enabled.
• The card requests a secure PIN channel. For more information, see CardSetProperty.
• The dwFlags member of the PIN_INFO structure (which is pointed to by pbPinData) contains PIN_INFO_REQUIRE_SECURE_ENTRY.

In secure PIN channel mode, the PIN prompt is presented to the user on a secure desktop after the user presses the CTRL+ ALT+DEL keyboard shortcut.

When in secure PIN channel mode, the operating system calls CardAuthenticateEx from a trusted process and sets CARD_AUTHENTICATE_GENERATE_SESSION_PIN in dwFlags. The PIN is specified in clear text. It is expected that the minidriver establishes a secure connection with the card and return a session PIN to the system. The system then passes the session PIN to the nonsecure context process for authentication to the card.

Note  It is imperative that the clear text PIN is handled securely when a CARD_AUTHENTICATE_GENERATE_SESSION_PIN flag is set. This PIN must never be transmitted to the card.

If either ppbSessionPin or pcbSessionPin are NULL, the function should return SCARD_E_INVALID_PARAMETER.

Requirements

Send comments about this topic to Microsoft