CardGetChallenge function
A card principal can be authenticated by using either a PIN or a challenge/response protocol in which the card generates a block of challenge data, by using its administrative key.
The authenticating caller must compute the response to the challenge by using shared knowledge of that key, and then submitting the response back to the card. If the response is correct, the principal is authenticated to the card.
Syntax
DWORD WINAPI CardGetChallenge(
_In_ PCARD_DATA pCardData,
_Out_ PBYTE *ppbChallengeData,
_Out_ PDWORD pcbChallengeData
);
Parameters
pCardData [in]
Context information for the call. For more information, see CardAcquireContext.ppbChallengeData [out]
Pointer to byte pointer to receive the challenge data from the card.pcbChallengeData [out]
Byte count of the challenge data.
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” section of File System Requirements.
This challenge/response method is generally used to establish the context for privileged operations such as unblocking a user’s PIN. For security reasons, we recommend that implementers of card minidrivers produce a design in which the challenge and response values are not invariant so that these values cannot be replayed.
The caller can decide not to use the challenge value. It is significant only if an authentication tries to use it. It is discarded if the next command to the card is not an authentication attempt that uses it (for more information, see CardAuthenticateChallenge). The smart card’s internal operating system should be designed to enforce this behavior.
The challenge buffer is allocated by the card minidriver and freed by the caller by using PFN_CSP_FREE.
Return values should follow the conventions described in Smart Card Minidriver Overview.
Requirements
Target platform |
Desktop |
Header |
Cardmod.h (include Cardmod.h) |