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.

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(CredentialValue value)¶

Verifies the PIN with the returned value of requestCredential function.

Parameters:	value – The `CredentialValue` object returned by the requestCredential function. May be `null` if a protected authentication path exists(`Token.hasProtectedAuthPath()`).

loginSO¶

public void loginSO(String value)¶

Verifies the Security Officer (administrator or unblocking) PIN

Parameters:	value – the PIN value. May be `null` if a protected authentication path exists(`Token.hasProtectedAuthPath()`).

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.

As this function waits for a credential through an user interface, this can NOT be called from UI thread.

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

CredentialState 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.