Class Token

Class represents connection to a smart card (or more generally, any cryptographic device). Token objects are obtained by calling the Connect() method.

Inheritance

System.Object

Token

Inherited Members

System.Object.Equals(System.Object)

System.Object.Equals(System.Object, System.Object)

System.Object.GetHashCode()

System.Object.GetType()

System.Object.MemberwiseClone()

System.Object.ReferenceEquals(System.Object, System.Object)

System.Object.ToString()

Namespace: scmapi

Assembly: scmapi.dll

Syntax

public class Token

Methods

CloseSecureChannel()

Closes a secure channel session.

Following this operation, all subsequent commands are sent in clear.

Declaration

public void CloseSecureChannel()

Disconnect()

Disconnects from the token.

Declaration

public void Disconnect()

ExternalAuthenticate(String, String, ExternalAuthenticateHandler)

This function issues the appropriate MSE SET with the given algorithm and key reference, followed by a GET CHALLENGE and finally the EXTERNAL AUTHENTICATE command.

The @scmapi.ExternalAuthenticateHandler.ComputeExternalAuthenticate is called between the GET CHALLENGE and EXTERNAL AUTHENTICATE commands to compute the required cryptograms. The method must return the cryptogram to be provided to the EXTERNAL AUTHENTICATE command.

Declaration

public void ExternalAuthenticate(string keyPath, string algorithm, ExternalAuthenticateHandler extAuthHandler)

Parameters

Type	Name	Description
System.String	keyPath	the key reference, given as an absolute slash-separated path. Format for keyPath is AID/ID or ID if key set is in Master File.
System.String	algorithm	indicating the algorithm ID to use, as expected in the 80 tag of the MSE SET command. For instance: 1C for 3DES, FFA01200 for AES.
ExternalAuthenticateHandler	extAuthHandler

GenrateKeyPair(Int32)

Generates a new RSA key pair in the card. When the operation completes, the newly created keys are returned, organized as a KeyPair object.

Declaration

public KeyPair GenrateKeyPair(int keyLength)

Parameters

Type	Name	Description
System.Int32	keyLength	the length, in bits, of the new key to generate

Returns

Type	Description
KeyPair	the KeyPair object.

GetLabel()

Gets the token label.

Declaration

public string GetLabel()

Returns

Type	Description
System.String	the token label.

GetLicenseEndDate()

Returns the end date for the license validity.

Declaration

public string GetLicenseEndDate()

Returns

Type	Description
System.String	The end date, as a string with the "YYYYMMDD" format. The return value may be "000000" for licenses with permanent validity. The return value may be an empty string for cards that do not have a license loaded, or for cards that benefit from a global licensing scheme. These cases can be identified depending on the IsLicenseValid() result.

GetManufacturer()

Gets the token manufacturer name.

Declaration

public string GetManufacturer()

Returns

Type	Description
System.String	the manufacturer name.

GetModel()

Gets the token model name.

Declaration

public string GetModel()

Returns

Type	Description
System.String	the model name.

GetObjects()

Retrieves all objects found in the token (certificates and keys). Note that private objects may not be returned if the associated PIN has not been verified previously. Also take in consideration that the API does not internally keep references to the retrieved objects, and calling this method will always return newly created TokenObject instances, even if the objects have been previously retrieved.To check whether twpo TokenObject instances refer to the same physical object in the card, the @scmapi.TokenOject.Equals method can be used.

Declaration

public List<TokenObject> GetObjects()

Returns

Type	Description
System.Collections.Generic.List<TokenObject>	the list of TokenObject items.

GetPins()

Returns a list of Pin objects describing all the PINs available with this card.

Declaration

public List<Pin> GetPins()

Returns

Type	Description
System.Collections.Generic.List<Pin>	the list of Pin objects.

GetReader()

Gets the Reader object from which this token is issued.

Declaration

public Reader GetReader()

Returns

Type	Description
Reader	the Reader object.

GetSerialNumber()

Gets the token serial number.

Declaration

public string GetSerialNumber()

Returns

Type	Description
System.String	the serial number.

HasProtectedAuthPath()

Returns true if this token allows user authentication through a hardware protected path (like a PIN pad reader, or using biometric recognition).

Declaration

public bool HasProtectedAuthPath()

Returns

Type	Description
System.Boolean	true if this token allows user authentication through a hardware protected path (like a PIN pad reader, or using biometric recognition); otherwise, false.

ImportObject(Byte[], String)

Imports a single X.509 certificate or a PKCS#12 (containing both a key pair and a certificate) in the card.

When the operation completes, the newly created items are returned, organized as a list of TokenObject.

Declaration

public List<TokenObject> ImportObject(byte[] data, string password)

Parameters

Type	Name	Description
System.Byte[]	data	The binary data of the item to import. For a single certificate, the data can be either in raw binary (DER-encoded) form, or encoded in PEM form. For a PKCS#12, the data must be in binary form.
System.String	password	(only for importing a PKCS#12): Password string of the PKCS#12 file.

Returns

Type	Description
System.Collections.Generic.List<TokenObject>	the list of TokenObject object of the newly created item(s).

IsInitialized()

Returns true if this this token has been initialized.

Declaration

public bool IsInitialized()

Returns

Type	Description
System.Boolean	true if this token has been initialized; otherwise, false.

IsLicenseValid()

Returns whether the license is valid for this card.

Declaration

public bool IsLicenseValid()

Returns

Type	Description
System.Boolean	true if the card has a valid license; otherwise, false.

MutualAuthenticate(String, String, MutualAuthenticateHandler)

This function issues the appropriate MSE SET with the given algorithm and key reference, followed by a GET CHALLENGE and finally the MUTUAL AUTHENTICATE command.

The @scmapi.MutualAuthenticateHandler.ComputeMutualAuthenticate1 method is called between the GET CHALLENGE and MUTUAL AUTHENTICATE commands to perform the first half of the authentication process. This method must return a byte array containing the complete data field (encrypted challenges and key seeds followed by the MAC) to be provided to the MUTUAL AUTHENTICATE command.

The @scmapi.MutualAuthenticateHandler.ComputeMutualAuthenticate2 is called following the MUTUAL AUTHENTICATE to check the cryptograms generated by the card and finalize the authentication by computing the session keys. This method must return the resulting session keys, as a list of byte[] containing the following values:

• keyenc: the resulting session encryption key.
• keymac: the resulting session MAC computation key.
• seqnum: the initial sequence number.

Following this operation, all subsequent commands are sent with the appropriate secure channel wrapping/unwrapping, until the CloseSecureChannel() method is called.

Declaration

public void MutualAuthenticate(string keyPath, string algorithm, MutualAuthenticateHandler mutualAuthHandler)

Parameters

Type	Name	Description
System.String	keyPath	the key reference, given as an absolute slash-separated path. Format for keyPath is AID/ID or ID if key set is in Master File.
System.String	algorithm	indicating the algorithm ID to use, as expected in the 80 tag of the MSE SET command. For instance: 8C for 3DES with SHA-256, FF200110 for AES with SHA-256.
MutualAuthenticateHandler	mutualAuthHandler	the MutualAuthenticateHandler object with 2 needed methods to open a secure channel.

RemoveObjects(TokenObject[])

Destroys the given object(s).

For objects that belong to a smart card, the object is physically destroyed from the smart card.

Declaration

public void RemoveObjects(params TokenObject[] tokenObjects)

Parameters

Type	Name	Description
TokenObject[]	tokenObjects	a single @TokenObject, or an arbitrary number of such objects.