Share via


CARD_CHANGE_AUTHENTICATOR structure

This structure is used by the minidriver to facilitate changing the PIN by using secure key injection function calls.

Syntax

typedef struct _CARD_CHANGE_AUTHENTICATOR {
  DWORD  dwVersion;
  DWORD  dwFlags;
  PIN_ID dwAuthenticatingPinId;
  DWORD  cbAuthenticatingPinData;
  PIN_ID dwTargetPinId;
  DWORD  cbTargetData;
  DWORD  cRetryCount;
  BYTE   pbData[];
} CARD_CHANGE_AUTHENTICATOR, *PCARD_CHANGE_AUTHENTICATOR;

Members

  • dwVersion
    The version of the structure. Set to CARD_CHANGE_AUTHENTICATOR_CURRENT_VERSION.

  • dwFlags
    A set of flags that specify the operation to be performed with the data. Current flags settings indicate whether this data is used for a PIN change or unblock operation.

  • dwAuthenticatingPinId
    PIN identifier to be authenticated.

  • cbAuthenticatingPinData
    Byte count of the PIN data.

  • dwTargetPinId
    PIN identifier to be updated.

  • cbTargetData
    Byte count of the new PIN data.

  • cRetryCount
    The count of times that a wrong PIN does not result in a blocked card.

  • pbData
    Both PIN data and new PIN data are appended at this address. PIN data is saved at pbDatapbData, size is specified by cbAuthenticatingPinData. New PIN data is saved at (pbDatapbData + cbAuthenticatingPinData), and size is specified by cbTargetData.

Remarks

This structure must be used in all situations in which the authenticator is to be changed securely by using the secure key injection API. The current PIN data is accessed within the pbData buffer at offset 0, and its size is specified by the cbAuthenticatingPinData member.

The new PIN data is accessed within the pbData buffer at offset cbAuthenticatingPinData, and its size is specified by the cbTargetData member.

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

For an explanation of dwFlags, see CardChangeAuthenticatorEx.

If changing the authenticator or the form of the new authenticator does not comply with policy, implementations that enforce policies about the authenticator (such as, PIN policies) should return SCARD_E_INVALID_PARAMETER.

When the call is used to change a PIN, the successful completion should leave the card in an authenticated state. If the call is used to unblock a PIN, the successful completion should leave the card in a de-authenticated state for both the unblocked PIN and the authenticating PIN.

When this data structure is passed to any of the secure key injection functions as an input buffer, the size of the buffer that is specified in the function call should include the following:

  • The size of the CARD_CHANGE_AUTHENTICATOR structure.
  • The current PIN data as specified by the cbAuthenticatingPinData member.
  • The new PIN data as specified by the cbTargetData member.

Requirements

Header

Cardmod.h (include Cardmod.h)

 

 

Send comments about this topic to Microsoft