ISCardISO7816::ExternalAuthenticate

The ExternalAuthenticate method constructs an APDU command that conditionally updates security status, verifying the identity of the computer when the smart card does not trust it.

The command uses the result (yes or no) of the computation by the card (based on a challenge previously issued by the card — for example, by the INS_GET_CHALLENGE command), a key (possibly secret) stored in the card, and authentication data transmitted by the interface device.

HRESULT ExternalAuthenticate (
  BYTE byAlgorithmRef,
  BYTE bySecretRef,
  LPBYTEBUFFER pChallenge,
  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. The reference of the secret is known either before issuing the command or is provided in the data field.

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, defaultvalue(NULL)]

Pointer to the authentication-related data; may be NULL.

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:

Remarks

For the encapsulated command to be successful, the last challenge obtained from the card must be valid.

Unsuccessful comparisons may be recorded in the card (for example, to limit the number of further attempts of the use of the reference data).

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

InternalAuthenticate, ISCardISO7816