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, to be used in requestCredential(JSONObject,CredentialState) function.

This object can be created without this function; in that case it has to be created manually and must have the following fields:

pinLabel as a String, representing the PIN label.
methods as a JSONObject representing the supported mechanisms by the slot. The following field must be defined:
- facialBio as a boolean. Equals true if the PIN supports facial biometry process

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.

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 requestCredential(JSONObject,CredentialState) / login(CredentialValue,CredentialState) process in order to update the information (remaining tries, a potential error…) in the PIN dialog.

Returns:	a `CredentialState` object.

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, CredentialState state)¶

Verifies the PIN after getting CredentialValue object by using requestCredential(JSONObject,CredentialState) function.

Parameters:	value – The credential value. state – The credential state. This object will be updated by this function call. A further call to `requestCredential(JSONObject,CredentialState)` with this `state` object will display a PIN dialog with updated information.

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 properties, CredentialState state)¶

Displays a standalone PIN dialog that allows the user to set the PIN or use biometry process, in order to get the necessary credential for a login(CredentialValue,CredentialState) process.

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

Examples

void loginLoop(JSONObject properties, CredentialState state) throws SCMException {
    boolean retry = false;
    do {
        try {
            // request credential ...
            CredentialValue credential = Pin.requestCredential(properties, state);

            // ... and try to login. Assuming a pin object is correctly defined and initialized
            pin.login(credential, state);
            Log.d("login_example", "login is successful");
            return;
        }
        catch (SCMException exception) {
            // on no fatal errors, retry requesting credential/login process
            long errorCode = exception.getErrorCode();
            retry = (errorCode == SCMException.CKR_PIN_INCORRECT ||
                errorCode == SCMException.CKR_PIN_INVALID ||
                errorCode == SCMException.CKR_PIN_LEN_RANGE);
            Log.d("login_example", "failed to login", exception);
            if (!retry) {
                Log.d("login_example", "exiting from loginLoop");
                throw exception;
            }
        }

    }
    while(retry);
}

Use case 1: A token has been read

// assuming pin object is defined
JSONObject credentialProperties = pin.getCredentialProperties();
CredentialState credentialState = pin.initCredentialState();

loginLoop(credentialProperties, credentialState);

Use case 2: No token has been read

JSONObject credentialProperties = new JSONObject("{pinLabel: "My PIN label", methods: {facialBio: false}}");
CredentialState credentialState = new CredentialState();

loginLoop(credentialProperties, credentialState);

Parameters:

properties – the credential properties. If a token has been previously read, value of getCredentialProperties() can be used. Otherwise, this parameter can be build respecting the format detailed in getCredentialProperties().
state – an object which is used to display the current credential state (remaining tries, a potential error…) in the PIN dialog. At the beginning of a requestCredential / login sequence, state can be created through initCredentialState() or CredentialState.CredentialState() if no token was read before.

Returns:

The CredentialValue to use in login(CredentialValue,CredentialState) operation.