Token

public class Token

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

Fields

handle

protected String handle

pins

Pin[] pins

port

protected int port

Methods

activateADF

public void activateADF(String adfPath)

Activates a DF. Must be preceded by a login special loginSpecial with the transport PIN. Activation of the DF is followed by resetting the counters tries for each PIN in the profile to maximum. The availability of this feature depends on the card profile. If a secure messaging has been opened before this function is called, it will be closed afterwards. A new one must be opened if necessary.

Parameters:

  • adfPath – DF path in String format. For instance: 1ADF.

Throws:

activateCertificates

public void activateCertificates(String container, int count)

Activates certificates in the card.

Parameters:

  • container – The container label in which the certificates to activate are stored in. Can be auth, sign, conf, mpp or winlogon. Possible values depending on the card profile.

  • count – The count of certificates to activate, starting by the first container in EFID ascending order.

Throws:

chipAuthenticate

public void chipAuthenticate(String keyPath, String keyID, String algorithm, ChipAuthenticateHandler chipAuthHandler)

Chip authenticate. This function issues the opening of a secure channel through a CHIP AUTHENTICATE command. The ChipAuthenticateHandler.extractPublicKey method of given ChipAuthenticateHandler interface allows to read a file containing a public key, an x509 certificate, etc., in the format decided by the application. The application must extract the public key from the input data. In addition, this application-side callback method can include a step for verifying the authenticity of the public key. This method must return a byte array containing the authenticated public key as a PKCS#8 format allowing to perform a CHIP AUTHENTICATE. Following this operation, all subsequent commands are sent with the appropriate secure channel wrapping/unwrapping, until the Token.closeSecureChannel method is called.

Parameters:

  • keyPath – the public key path, given as an absolute slash-separated path. Format for keyPath is AID/keyPath or keyPath if key set is in Master File.

  • keyID – the key reference, given as an absolute slash-separated path. Format for keyID is AID/keyID or keyID if key set is in Master File.

  • algorithm – indicating the algorithm OID to use. For instance ECDH-AES-CBC-CMAC-128 must be "0.4.0.127.0.7.2.2.3.2.2" according to the specification ICAO 9303 part 11.

  • chipAuthHandler – the ChipAuthenticateHandler object with the needed method to authenticate the public key for the CHIP AUTHENTICATE command.

closeSecureChannel

public void closeSecureChannel()

Closes a secure channel session. Following this operation, all subsequent commands are sent in clear.

createDataContainer

public DataContainer createDataContainer(Map<String, Object> attributes)

disconnect

public void disconnect()

Disconnects from the token.

externalAuthenticate

public void externalAuthenticate(String keyPath, String algorithm, ExternalAuthenticateHandler extAuthHandler)

External authenticate. On a IAS ECC token: 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. On a NXP P71 token: This function performs a GET CHALLENGE and finally the EXTERNAL AUTHENTICATE command. The ExternalAuthenticateHandler.computeExternalAuthenticate method of given ExternalAuthenticateHandler interface 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.

Parameters:

  • 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.

  • algorithm – indicating the algorithm ID to use. In IAS ECC token: the content of the 80 tag of the MSE SET command must be provided (For instance: 1C for 3DES, FFA01200 for AES.). On a NXP P71 token, this parameter is RFU, and must be filled with an empty string.

  • extAuthHandler – the ExternalAuthenticateHandler object with method that will compute the cryptogram.

generateKeyPair

public KeyPair generateKeyPair(int keyLength, Map<String, Object> attributes)

Generates a new RSA key pair in the card, with some attributes. The key pair attributes are provided by the attributes parameter. It must be a java.util.Map object with the following keys:

  • container: the container label in which the key pair will be stored in. Value can be auth, sign, conf, mpp, mpp_rgs or winlogon. Possible values depending on the card profile.

  • label: the ckLabel name to give for both generated keys.

When the operation completes, the newly created keys are returned, organized as a KeyPair object with the following attributes:

  • publicKey: the imported public key, as a PublicKey

  • privateKey: the imported private key, as a PrivateKey

Parameters:

  • keyLength – the length, in bits, of the new key to generate.

  • attributes – the key pair attributes given as described above.

Returns:

the KeyPair object.

getCPLCData

public byte[] getCPLCData()

Gets Card Production Life Cycle (CPLC) Data of the token as a byte array. If a secure channel is opened, it will be closed by this function’s call.

Returns:

the CPLC Data.

getLabel

public String getLabel()

Gets the token label.

Returns:

the token label.

getLicenseEndDate

public String getLicenseEndDate()

Returns the end date for the license validity.

Returns:

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

public String getManufacturer()

Gets the token manufacturer name.

Returns:

the manufacturer name.

getModel

public String getModel()

Gets the token model name.

Returns:

the model name.

getObjects

public List<TokenObject> 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 two TokenObject instances refer to the same physical object in the card, the TokenObject.equals method can be used.

Returns:

the list of TokenObject items.

getPins

public Pin[] getPins()

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

Returns:

Pinarray.

getReader

public Reader getReader()

Gets the Reader object from which this token is issued.

Returns:

the reader object.

getSerialNumber

public String getSerialNumber()

Gets the token serial number.

Returns:

the serial number.

getTechData

public byte[] getTechData()

Gets the Technical Data of the token as a byte array, read from EF.TECH file.

Returns:

the technical data.

hasProtectedAuthPath

public boolean hasProtectedAuthPath()

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

Returns:

true if this token allows user authentication through a hardware protected path; false otherwise

importObject

public List<TokenObject> importObject(byte[] data, String password, Map<String, Object> attributes)

Imports a single X.509 certificate or a PKCS#12 (containing both a key pair and a certificate) in the card. The import attributes are provided by attributes parameter. It must be a java.util.Map object with the following keys:

  • container: the container label in which the key pair and certificate will be stored in. Can be auth, sign, conf, mpp, mpp_rgs or winlogon. Possible values depending on the card profile. The container is chosen in EFID ascending order among available containers.

  • label: the ckLabel name to give for the imported objects.

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

Parameters:

  • 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.

  • password – (only for importing a PKCS#12): Password string of the PKCS#12 file.

  • attributes – the imported object attributes given as described above.

Returns:

the list of TokenObject object of the newly created item(s).

initPinSpecial

public void initPinSpecial(String value, String type)

Initialises the special PIN.

Parameters:

  • value – the PIN value

  • type – a String indicating on which PIN the operation must be made. Possible values depending on the card profile.

isInitialized

public boolean isInitialized()

Returns true if this this token has been initialized.

Returns:

true if this token has been initialized; false otherwise

isLicenseValid

public boolean isLicenseValid()

Returns whether the license is valid for this card.

Returns:

true if the card has a valid license; false otherwise

loginSpecial

public void loginSpecial(String value, String type)

Verifies the special PIN.

Parameters:

  • value – the PIN value

  • type – a String indicating on which PIN the operation must be made. Possible values depending on the card profile.

mutualAuthenticate

public void mutualAuthenticate(String keyPath, String algorithm, MutualAuthenticateHandler mutualAuthHandler)

Mutual authenticate. 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 MutualAuthenticateHandler.computeMutualAuthenticate1 method of given MutualAuthenticateHandler interface 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 MutualAuthenticateHandler.computeMutualAuthenticate2 method of given MutualAuthenticateHandler interface 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 Token.closeSecureChannel method is called.

Parameters:

  • 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.

  • 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.

  • mutualAuthHandler – the MutualAuthenticateHandler object with 2 needed methods to open a secure channel.

nextPinChangeNotInAOD

public void nextPinChangeNotInAOD()

Indicate next pin to be changed is not registered in AOD. Must be used before a SCWS.Pin.change

removeObjects

public void removeObjects(TokenObject... tokenObjects)

Destroys the given object(s). For objects that belong to a smart card, the object is physically destroyed from the smart card.

Parameters:

  • tokenObjects – A single TokenObject, or an arbitrary number of such objects.