Tokens
======

Manipulating tokens
-------------------

The ``Token`` class is described below:

.. js:autoclass:: SCWS.ICAO.Token()
.. js:autoattribute:: Token#reader
.. js:autofunction:: Token#disconnect


Token operations
----------------

Reading data
^^^^^^^^^^^^

.. js:autofunction:: Token#readFile

.. note::
  see :ref:`asn1_data_reading_formatting` part for format of returned ``content`` value of :js:func:`Token.readFile` method.

Security mechanisms
^^^^^^^^^^^^^^^^^^^

.. js:autofunction:: Token#doBAC
.. js:autofunction:: Token#doPACE(credentialType, credential[, securityInfoFileId[, securityInfoIndex]][, additionalParameters])
.. js:autofunction:: Token#doPassiveAuthentication(CSCACertificate[, DSCertificate])
.. js:autofunction:: Token#doActiveAuthentication
.. js:autofunction:: Token#doChipAuthenticationV1([securityInfoFileId[, securityInfoIndex]])
.. js:autofunction:: Token#doChipAuthenticationV2
.. js:autofunction:: Token#doTerminalAuthenticationV1
.. js:autofunction:: Token#doTerminalAuthenticationV2(CVCs, callback[, securityInfoFileId[, securityInfoIndex]])


PIN management
^^^^^^^^^^^^^^

.. js:autofunction:: Token#resumePIN(canValue, pinValue[, securityInfoFileId[, securityInfoIndex]])
.. js:autofunction:: Token#resumePUK(canValue, pukValue[, securityInfoFileId[, securityInfoIndex]])
.. js:autofunction:: Token#unblockPIN
.. js:autofunction:: Token#changePIN
.. js:autofunction:: Token#activatePIN
.. js:autofunction:: Token#deactivatePIN

Notes
-----

Sessions
^^^^^^^^

The following API entry points will start a **new session**:

- :js:func:`Token.doBAC`
- :js:func:`Token.doPACE`
- :js:func:`Token.resumePIN`
- :js:func:`Token.resumePUK`

Session is released after completion of:

- :js:func:`Token.resumePIN`
- :js:func:`Token.resumePUK`

See ICAO specifications (Doc 9303 part 11) for a definition of a *session*.

Additional error attributes
^^^^^^^^^^^^^^^^^^^^^^^^^^^

Some API entry points reject a :js:class:`SCWS.Error` object with additional attributes:

- :js:func:`Token.doPACE` when :js:data:`ICAO.CREDENTIAL_TYPE.PIN` or :js:data:`ICAO.CREDENTIAL_TYPE.PUK` with a wrong value is used. In the case of an ``ICAO_ERR_AUTHENTICATION_FAILED`` code error, a ``remainingTries`` integer attribute is defined.
- :js:func:`Token.doPassiveAuthentication` when rejects ``ICAO_ERR_AUTHENTICATION_FAILED`` code error and at least one DG hash verification failed. In this case, a ``failedVerificationDGs`` attribute is defined as an array of DGs number.