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(String value)

Verifies the PIN.

Parameters:

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:

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.