.. java:import:: org.json JSONArray .. java:import:: org.json JSONException .. java:import:: org.json JSONObject .. java:import:: java.io IOException .. java:import:: java.nio.charset Charset .. java:import:: java.security GeneralSecurityException .. java:import:: java.util ArrayList .. java:import:: java.util HashMap .. java:import:: java.util Iterator .. java:import:: java.util List .. java:import:: java.util Map Token ===== .. java:package:: com.idopte.scmapi :noindex: .. java:type:: public class Token Class represents connection to a smart card (or more generally, any cryptographic device). Token objects are obtained by calling the \ :java:ref:`Reader.connect()`\ method. Fields ------ handle ^^^^^^ .. java:field:: protected String handle :outertype: Token pins ^^^^ .. java:field:: Pin[] pins :outertype: Token port ^^^^ .. java:field:: protected int port :outertype: Token Methods ------- activateADF ^^^^^^^^^^^ .. java:method:: public void activateADF(String adfPath) throws IOException, JSONException, SCMException :outertype: Token Activates a DF. Must be preceded by a login special \ :java:ref:`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. :param adfPath: DF path in String format. For instance: ``1ADF``. :throws SCMException: :throws JSONException: activateCertificates ^^^^^^^^^^^^^^^^^^^^ .. java:method:: public void activateCertificates(String container, int count) throws SCMException :outertype: Token Activates certificates in the card. :param 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. :param count: The count of certificates to activate, starting by the first container in EFID ascending order. :throws SCMException: chipAuthenticate ^^^^^^^^^^^^^^^^ .. java:method:: public void chipAuthenticate(String keyPath, String keyID, String algorithm, ChipAuthenticateHandler chipAuthHandler) throws JSONException, SCMException, IOException, GeneralSecurityException :outertype: Token Chip authenticate. This function issues the opening of a secure channel through a ``CHIP AUTHENTICATE`` command. The \ :java:ref:`ChipAuthenticateHandler.extractPublicKey`\ method of given \ :java:ref:`ChipAuthenticateHandler`\ interface allows to read a file containing a public key, a 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 \ :java:ref:`Token.closeSecureChannel`\ method is called. :param 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. :param 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. :param 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. :param chipAuthHandler: the \ :java:ref:`ChipAuthenticateHandler`\ object with the needed method to authenticate the public key for the ``CHIP AUTHENTICATE`` command. closeSecureChannel ^^^^^^^^^^^^^^^^^^ .. java:method:: public void closeSecureChannel() throws SCMException, IOException :outertype: Token Closes a secure channel session. Following this operation, all subsequent commands are sent in clear. createDataContainer ^^^^^^^^^^^^^^^^^^^ .. java:method:: public DataContainer createDataContainer(Map attributes) throws SCMException, JSONException, IOException :outertype: Token disconnect ^^^^^^^^^^ .. java:method:: public void disconnect() throws SCMException :outertype: Token Disconnects from the token. externalAuthenticate ^^^^^^^^^^^^^^^^^^^^ .. java:method:: public void externalAuthenticate(String keyPath, String algorithm, ExternalAuthenticateHandler extAuthHandler) throws SCMException, JSONException, IOException, GeneralSecurityException :outertype: Token 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 \ :java:ref:`ExternalAuthenticateHandler.computeExternalAuthenticate`\ method of given \ :java:ref:`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. :param 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. :param 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. :param extAuthHandler: the \ :java:ref:`ExternalAuthenticateHandler`\ object with method that will compute the cryptogram. generateKeyPair ^^^^^^^^^^^^^^^ .. java:method:: public KeyPair generateKeyPair(int keyLength, Map attributes) throws SCMException :outertype: Token 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 \ :java:ref:`KeyPair`\ object with the following attributes: .. * ``publicKey``: the imported public key, as a \ :java:ref:`PublicKey`\ * ``privateKey``: the imported private key, as a \ :java:ref:`PrivateKey`\ :param keyLength: the length, in bits, of the new key to generate. :param attributes: the key pair attributes given as described above. :return: the \ :java:ref:`KeyPair`\ object. getCPLCData ^^^^^^^^^^^ .. java:method:: public byte[] getCPLCData() throws SCMException :outertype: Token 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. :return: the CPLC Data. getLabel ^^^^^^^^ .. java:method:: public String getLabel() :outertype: Token Gets the token label. :return: the token label. getLicenseEndDate ^^^^^^^^^^^^^^^^^ .. java:method:: public String getLicenseEndDate() throws SCMException :outertype: Token Returns the end date for the license validity. :return: 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 ^^^^^^^^^^^^^^^ .. java:method:: public String getManufacturer() :outertype: Token Gets the token manufacturer name. :return: the manufacturer name. getModel ^^^^^^^^ .. java:method:: public String getModel() :outertype: Token Gets the token model name. :return: the model name. getObjects ^^^^^^^^^^ .. java:method:: public List getObjects() throws SCMException :outertype: Token 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 \ :java:ref:`TokenObject`\ instances, even if the objects have been previously retrieved. To check whether two \ :java:ref:`TokenObject`\ instances refer to the same physical object in the card, the \ :java:ref:`TokenObject.equals`\ method can be used. :return: the list of \ :java:ref:`TokenObject`\ items. getPins ^^^^^^^ .. java:method:: public Pin[] getPins() :outertype: Token Returns array of \ :java:ref:`Pin`\ objects describing all the PINs available with this card. :return: \ :java:ref:`Pin`\ array. getReader ^^^^^^^^^ .. java:method:: public Reader getReader() :outertype: Token Gets the \ :java:ref:`Reader`\ object from which this token is issued. :return: the reader object. getSerialNumber ^^^^^^^^^^^^^^^ .. java:method:: public String getSerialNumber() :outertype: Token Gets the token serial number. :return: the serial number. getTechData ^^^^^^^^^^^ .. java:method:: public byte[] getTechData() :outertype: Token Gets the Technical Data of the token as a byte array, read from EF.TECH file. :return: the technical data. hasProtectedAuthPath ^^^^^^^^^^^^^^^^^^^^ .. java:method:: public boolean hasProtectedAuthPath() :outertype: Token Returns \ ``true``\ if this token allows user authentication through a hardware protected path (like a PIN pad reader, or using biometric recognition). :return: \ ``true``\ if this token allows user authentication through a hardware protected path; \ ``false``\ otherwise importObject ^^^^^^^^^^^^ .. java:method:: public List importObject(byte[] data, String password, Map attributes) throws SCMException :outertype: Token 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 \ :java:ref:`TokenObject`\ . :param 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. :param password: (only for importing a PKCS#12): Password string of the PKCS#12 file. :param attributes: the imported object attributes given as described above. :return: the list of \ :java:ref:`TokenObject`\ object of the newly created item(s). initPinSpecial ^^^^^^^^^^^^^^ .. java:method:: public void initPinSpecial(String value, String type) throws SCMException :outertype: Token Initialises the special PIN. :param value: the PIN value :param type: a String indicating on which PIN the operation must be made. Possible values depending on the card profile. isInitialized ^^^^^^^^^^^^^ .. java:method:: public boolean isInitialized() :outertype: Token Returns \ ``true``\ if this this token has been initialized. :return: \ ``true``\ if this token has been initialized; \ ``false``\ otherwise isLicenseValid ^^^^^^^^^^^^^^ .. java:method:: public boolean isLicenseValid() throws SCMException :outertype: Token Returns whether the license is valid for this card. :return: \ ``true``\ if the card has a valid license; \ ``false``\ otherwise loginSpecial ^^^^^^^^^^^^ .. java:method:: public void loginSpecial(String value, String type) throws SCMException :outertype: Token Verifies the special PIN. :param value: the PIN value :param type: a String indicating on which PIN the operation must be made. Possible values depending on the card profile. mutualAuthenticate ^^^^^^^^^^^^^^^^^^ .. java:method:: public void mutualAuthenticate(String keyPath, String algorithm, MutualAuthenticateHandler mutualAuthHandler) throws JSONException, SCMException, IOException, GeneralSecurityException :outertype: Token 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 \ :java:ref:`MutualAuthenticateHandler.computeMutualAuthenticate1`\ method of given \ :java:ref:`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 \ :java:ref:`MutualAuthenticateHandler.computeMutualAuthenticate2`\ method of given \ :java:ref:`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 \ :java:ref:`Token.closeSecureChannel`\ method is called. :param 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. :param 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. :param mutualAuthHandler: the \ :java:ref:`MutualAuthenticateHandler`\ object with 2 needed methods to open a secure channel. nextPinChangeNotInAOD ^^^^^^^^^^^^^^^^^^^^^ .. java:method:: public void nextPinChangeNotInAOD() throws SCMException :outertype: Token Indicate next pin to be changed is not registered in AOD. Must be used before a SCWS.Pin.change removeObjects ^^^^^^^^^^^^^ .. java:method:: public void removeObjects(TokenObject... tokenObjects) throws SCMException :outertype: Token Destroys the given object(s). For objects that belong to a smart card, the object is physically destroyed from the smart card. :param tokenObjects: A single \ :java:ref:`TokenObject`\ , or an arbitrary number of such objects.