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.

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 with the following attributes:

publicKey: the imported public key, as a PublicKey
privateKey: the imported private key, as a PrivateKey

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:	`Pin`array.

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.

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.

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.