Pin

public class Pin

Class represents a PIN that protects smart card contents.

Methods

change

public void change(String oldValue, String newValue)

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

Parameters:
  • oldValue – The current PIN value. May be null if a protected authentication path exists Token.hasProtectedAuthPath().
  • newValue – The new PIN value. May be null if a protected authentication path exists.

change

public void change(CredentialValue value)

Verifies the PIN with the returned value of requestCredential function.

Parameters:

getConstraints

public PinConstraint[] getConstraints()

Gets the format constraints of the PIN as an array of PinConstraint object.

Returns:the PinConstraint array.

getCredentialProperties

public JSONObject getCredentialProperties()

Returns a JSONObject which contains the PIN properties of a specific slot. The PIN properties contains the card label in String format and a JSONObject which contains the biometric capabilities (facial and digital) of the current slot. The returned JSONObject is used in the requestCredential function in order to provide information that will be displayed in the PIN dialog. The JSONObject retuned has this format: { pinLabel: a String that represents the PIN label, can be obtained by using getLabel function of the Pin class, methods: { facialBio: true if the PIN supports the facial biometry process, fingerBio: true if the PIN supports the digital biometry process false otherwise. } }

Returns:a JSONObject which contains the Pin properties of a specific slot.

getLabel

public String getLabel()

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

Returns:the PIN label.

getMaxTries

public int getMaxTries()

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

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

getRemainingTries

public int getRemainingTries()

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

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

getSo

public Pin getSo()

Returns the Pin SO object of the selected slot.

Returns:the Pin SO object of the selected slot;

getToken

public Token getToken()

Returns Token object this PIN belongs to.

Returns:the Token object.

initCredentialState

public CredentialState initCredentialState()

Returns a CredentialState object which can be used during a login process in order to update the remaining PIN tries and a potential error informations in the PIN dialog.

Returns:a CredentialState object which be able to be re-used with updated token infos during complete login.

initPin

public void initPin(String newValue)

Re-initializes 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 Pin.loginSO(String))}.

Parameters:
  • newValue – The new PIN value. May be null if a protected authentication path exists.

isBlocked

public boolean isBlocked()

Returns true if the PIN is blocked.

Returns:true if the PIN is blocked; false otherwise.

isInitialized

public boolean isInitialized()

Returns true if the PIN has been initialized.

Returns:true if the PIN has been initialized; false otherwise.

isToBeChanged

public boolean isToBeChanged()

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

Returns:true if the PIN need to be changed before use; false otherwise.

isTryCountLow

public boolean isTryCountLow()

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

Returns:true if the PIN try counter is lower than the maximum; false otherwise.

isValidated

public boolean isValidated()

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

Returns:true if the PIN has been successfully verified; false otherwise.

lastTry

public boolean lastTry()

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

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

login

public void login(String value)

Verifies the PIN.

Parameters:

login

public void login(CredentialValue value)

Verifies the PIN with the returned value of requestCredential function.

Parameters:

loginSO

public void loginSO(String value)

Verifies the Security Officer (administrator or unblocking) PIN

Parameters:

logout

public void logout()

Resets the verified status of the PIN (cancels a call to Pin.login(String)).

requestCredential

public static CredentialValue requestCredential(JSONObject credentialProperties, CredentialState state, String readerName, String cardLabel)

Displays a standalone PIN dialog that allows to set the PIN or use biometry process in order to get the necessary credential for a login process.

Use case 1: `A token has been read` and a PIN dialog is used to get `CredentialValue` object.

CredetialState state = pin.initCredentialState();
CredentialValue cred = Pin.requestCredential(pin.getCredentialProperties(),
    state,
    pin.getToken().getReader().getName(),
    pin.getToken().getLabel());
   try {
    pin.login(cred);
} catch (SCMException e) {
    state.setError(e.message);
    state.setRemainingTries(pin.getRemainingTries);
    cred = Pin.requestCredential(pin.getCredentialProperties(),
        state,
        pin.getToken().getReader().getName(),
        pin.getToken().getLabel());
}

Use case 2: `No token has been read` and a PIN dialog is used to get `CredentialValue` object.

// build the JSONObject which contains PIN properties.
JSONObject credentialProperties = new JSONObject();
try {
    JSONObject bio = new JSONObject();
    bio.put("facialBio", false);
    bio.put("fingerBio", false);
    credentialProperties.put("pinLabel", "No token read");
    credentialProperties.put("methods", bio.toString());
} catch (JSONException e) {
    e.printStackTrace();
}
CredentialState state = new CredentialState();
String readerName = "...";
String cardLabel = "...";
CredentialValue cred = Pin.requestCredential(credentialProperties,
    state,
    readerName,
    cardLabel);
try {
    pin.login(cred);
} catch (SCMException e) {
    state.setError(e.message);
    state.setRemainingTries(pin.getRemainingTries);
    cred = Pin.requestCredential(pin.getCredentialProperties(),
        state,
        pin.getToken().getReader().getName(),
        pin.getToken().getLabel());
}
Parameters:
  • credentialProperties – The credential properties represented as a JSONObject. Could be built by the user when no token has been read before opening the PIN dialog or be get by the getPinProperties() methods of this class.
  • state – The CredentialState object which displays the remaining tries & a potential error in the PIN dialog.
  • readerName – The current readerName. Can be set to null if it does not need to be displayed.
  • cardLabel – The current `cardLabel. Can be set to null if it does not need to be displayed.
Returns:

The CredentialValue that can be used in login operation.