.. java:import:: org.json JSONArray

.. java:import:: org.json JSONObject

.. java:import:: java.nio.charset Charset

Pin
===

.. java:package:: com.idopte.scmapi
   :noindex:

.. java:type:: public class Pin

   Class represents a PIN that protects smart card contents.

Methods
-------
change
^^^^^^

.. java:method:: public void change(String oldValue, String newValue) throws SCMException
   :outertype: Pin

   Changes the PIN. The operation can only be made against the user PIN.

   :param oldValue: The current PIN value. May be ``null`` if a protected authentication path exists \ :java:ref:`Token.hasProtectedAuthPath()`\ .
   :param newValue: The new PIN value. May be ``null`` if a protected authentication path exists.

getConstraints
^^^^^^^^^^^^^^

.. java:method:: public PinConstraint[] getConstraints() throws SCMException
   :outertype: Pin

   Gets the format constraints of the PIN as an array of \ :java:ref:`PinConstraint`\  object.

   :return: the \ :java:ref:`PinConstraint`\  array.

getLabel
^^^^^^^^

.. java:method:: public String getLabel()
   :outertype: Pin

   Gets the PIN label. Can be undefined if the card has a single PIN without explicit label defined.

   :return: the PIN label.

getMaxTries
^^^^^^^^^^^

.. java:method:: public int getMaxTries()
   :outertype: Pin

   Returns the number of maximum tries for the PIN verification. Can be undefined if the information is unavailable.

   :return: the number of maximum tries for the PIN verification.

getPuksAvailable
^^^^^^^^^^^^^^^^

.. java:method:: public int getPuksAvailable()
   :outertype: Pin

   Returns a bit field indicating availability of each PUK, with the LSB for 1st PUK. A bit at `1` indicates that the corresponding PUK is still available. Can be undefined if the information is unavailable.

   :return: a bit field indicating availability of each PUK.

getRemainingTries
^^^^^^^^^^^^^^^^^

.. java:method:: public int getRemainingTries()
   :outertype: Pin

   Returns the number of remaining tries for the PIN verification. Can be undefined if the information is unavailable.

   :return: the number of remaining tries for the PIN verification.

getToken
^^^^^^^^

.. java:method:: public Token getToken()
   :outertype: Pin

   Returns \ :java:ref:`Token`\  object this PIN belongs to.

   :return: the \ :java:ref:`Token`\  object.

initPin
^^^^^^^

.. java:method:: public void initPin(String newValue) throws SCMException
   :outertype: Pin

   Reinitializes the PIN value (eventually unblocking it, if required). The operation can only be made against the user PIN, and requires the security officer PIN to be verified \ :java:ref:`Pin.login(String)`\ .

   :param newValue: The new PIN value. May be ``null`` if a protected authentication path exists.

initPinSo
^^^^^^^^^

.. java:method:: public void initPinSo() throws SCMException
   :outertype: Pin

   Unblocks the SO PIN or the PUKs, depending on the profile. This function can operate only if the appropriate access conditons have been fulfilled.

isBlocked
^^^^^^^^^

.. java:method:: public boolean isBlocked()
   :outertype: Pin

   Returns \ ``true``\  if the PIN is blocked.

   :return: \ ``true``\  if the PIN is blocked; \ ``false``\  otherwise.

isInitialized
^^^^^^^^^^^^^

.. java:method:: public boolean isInitialized()
   :outertype: Pin

   Returns \ ``true``\  if the PIN has been initialized.

   :return: \ ``true``\  if the PIN has been initialized; \ ``false``\  otherwise.

isToBeChanged
^^^^^^^^^^^^^

.. java:method:: public boolean isToBeChanged()
   :outertype: Pin

   Returns \ ``true``\  if the PIN need to be changed before use.

   :return: \ ``true``\  if the PIN need to be changed before use; \ ``false``\  otherwise.

isTryCountLow
^^^^^^^^^^^^^

.. java:method:: public boolean isTryCountLow()
   :outertype: Pin

   Returns \ ``true``\  if the PIN try counter is lower than the maximum (an unsuccessful verification attempt has been made).

   :return: \ ``true``\  if the PIN try counter is lower than the maximum; \ ``false``\  otherwise.

isValidated
^^^^^^^^^^^

.. java:method:: public boolean isValidated()
   :outertype: Pin

   Returns \ ``true``\  if the PIN has been successfully verified (access to the private objects is granted).

   :return: \ ``true``\  if the PIN has been successfully verified; \ ``false``\  otherwise.

lastTry
^^^^^^^

.. java:method:: public boolean lastTry()
   :outertype: Pin

   Returns \ ``true``\  if the PIN try counter shows only one attempt remaining.

   :return: \ ``true``\  if the PIN try counter shows only one attempt remaining; \ ``false``\  otherwise.

login
^^^^^

.. java:method:: public void login(String value) throws SCMException
   :outertype: Pin

   Verifies the PIN.

   :param value: the PIN value. May be ``null`` if a protected authentication path exists(\ :java:ref:`Token.hasProtectedAuthPath()`\ ).

loginSO
^^^^^^^

.. java:method:: public void loginSO(String value) throws SCMException
   :outertype: Pin

   Verifies the Security Officer (administrator or unblocking) PIN

   :param value: the PIN value. May be ``null`` if a protected authentication path exists(\ :java:ref:`Token.hasProtectedAuthPath()`\ ).

logout
^^^^^^

.. java:method:: public void logout() throws SCMException
   :outertype: Pin

   Resets the verified status of the PIN (cancels a call to \ :java:ref:`Pin.login(String)`\ ).