ISCardISO7816::InternalAuthenticate

The InternalAuthenticate method constructs an APDU command that initiates the computation of the authentication data by the card using the challenge data sent from the interface device and a relevant secret (for example, a key) stored in the card.

When the relevant secret is attached to the MF, the command may be used to authenticate the card as a whole.

When the relevant secret is attached to another DF, the command may be used to authenticate that DF.

HRESULT InternalAuthenticate(
  BYTE byAlgorithmRef,
  BYTE bySecretRef,
  LPBYTEBUFFER pChallenge,
  LONG lReplyBytes,
  LPSCARDCMD *ppCmd
);

Parameters

byAlgorithmRef [in, defaultvalue(NULL_BYTE)]
Reference of the algorithm in the card.

If this value is zero, this indicates that no information is given. The reference of the algorithm is known either before issuing the command or is provided in the data field.

bySecretRef [in, defaultvalue(NULL_BYTE)]
Reference of the secret:
Meaning 8 7 6 5 4 3 2 1
No Info 0 0 0 0 0 0 0 0
Global ref 0 - - - - - - -
Specific ref 1 - - - - - - -
RFU - x x - - - - -
Secret - - - x x x x x

No Info = No information is given.

Global ref = Global reference data (an MF specific key).

Specific ref = Specific reference data (a DF specific key).

RFU = 00 (other values are RFU).

Secret = Number of the secret.

pChallenge [in]
Pointer to the authentication-related data (for example, challenge).
lReplyBytes [in, defaultvalue(0)]
Maximum number of bytes expected in response.
ppCmd [in, out]
On input, a pointer to an ISCardCmd interface object or NULL.

On return, it is filled with the APDU command constructed by this operation. If ppCmd was set to NULL, a smart card ISCardCmd object is internally created and returned via the ppCmd pointer.

Return Values

The possible return values are the following:

Value Meaning
S_OK Operation completed successfully.
E_INVALIDARG Invalid parameter.
E_POINTER A bad pointer was passed in.
E_OUTOFMEMORY Out of memory.

Remarks

The successful execution of the command may be subject to successful completion of prior commands (for example, VERIFY or SELECT FILE) or selections (for example, the relevant secret).

If a key and an algorithm are currently selected when issuing the command, then the command may implicitly use the key and the algorithm.

The number of times the command is issued may be recorded in the card to limit the number of further attempts of using the relevant secret or the algorithm.

For a list of all the methods provided by the ISCardISO7816 interface, see ISCardISO7816.

In addition to the COM error codes listed above, this interface may return a smart card error code if a smart card function was called to complete the request. For information on smart card error codes, see Error Codes.

QuickInfo

  Windows NT: Use version 4.0 SP3 and later.
  Windows: Use Windows 95 OSR2.1.
  Windows CE: Unsupported.
  Header: Declared in scardsrv.h.
  Import Library: scardsrv.tlb.

See Also

ExternalAuthenticate, ISCardISO7816