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.

Methods

createDataContainer

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

Creates a new data container in the card.

The data container attributes are provided by the attributes parameter. It must be a java.util.Map object with the following keys:

  • private: Boolean indicating if the data container object is protected by PIN (for both reading and writing). Optional, defaults to false.

  • modifiable: Boolean indicating if the data container object is modifiable. Optional, defaults to true.

  • label: label String of the data container object. Optional.

  • application: String naming the application that manages the object. Optional.

  • value: byte array containing the data to store.

Parameters:

  • attributes – the data container attributes.

Returns:

the created DataContainer object.

destroyObjects

public void destroyObjects(TokenObject... tokenObjects)

Destroys the given object(s).

The objects are physically destroyed from the smart card.

Parameters:

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

disconnect

public void disconnect()

Disconnects from the token.

generateAppLicense

public void generateAppLicense()

Generates an App License for the current token, if current API embeds this mechanism.

This function is also called internally on certificates registration, through SCMEnvironment.registerCertificates(Token) for instance.

Note that the resulting license will be stored in app data; thus, for a same smart card, calling this function on each app instance (on a different device, after a re-installation or if app data is cleared) using this smart card is needed.

Throws:

  • SCMException – if an error occurred, typically if this API does not embed App License Generation.

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 as a String in which the key pair will be stored in. Optional. When specified, 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 as a String to give for both generated keys.

  • signVerify: boolean flag that will be use to initialize CKA_SIGN attribute for the private key and CKA_VERIFY for the public key. Optional, defaults to true.

  • encryptDecrypt: boolean flag that will be use to initialize CKA_DECRYPT attribute for the private key and CKA_ENCRYPT for the public key. Optional, defaults to true.

  • wrapUnwrap: boolean flag that will be use to initialize CKA_WRAP attribute for the private key and CKA_UNWRAP for the public key. Optional, defaults to true.

When the operation completes, the newly created keys are returned, organized as a KeyPair object.

Important note: It is strongly recommended not to generate a key through NFC reader interface. Indeed, key pair generation may take some time and a card disconnection during this operation may be fatal for the card’s contents.

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.

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.

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 as a String in which the key pair will be stored in. Optional. When specified, 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 as a String to give for both generated keys.

  • signVerify: boolean flag that will be use to initialize CKA_SIGN attribute for the private key and CKA_VERIFY for the public key. Optional, defaults to true.

  • encryptDecrypt: boolean flag that will be use to initialize CKA_DECRYPT attribute for the private key and CKA_ENCRYPT for the public key. Optional, defaults to true.

  • wrapUnwrap: boolean flag that will be use to initialize CKA_WRAP attribute for the private key and CKA_UNWRAP for the public key. Optional, defaults to true.

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

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

isPresent

public boolean isPresent()

Gets token presence state.

Returns:

true if token is still connected and usable, false if it has been disconnected or removed from reader.

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.

setPaceCanValue

public static void setPaceCanValue(String can)

Sets PACE CAN value for further token connections.

Depending on card profile, a PACE with CAN value is done during token connection (see Reader.connect()). This function must be called to set CAN value to use. This value is permanently stored in app data and is used for all connections to a card requiring PACE protocol.

If stored CAN value (or if this function has never been called) does not permit a successful PACE protocol, Reader.connect() will throw a SCMException with SCMException.CXR_PACE_NEEDED error code. In this case, the app should ask the user to enter a CAN value before trying to read the token again.

Parameters:

  • can – the CAN value to set.