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) |