PINs¶

The PINs of a given token are retrieved using the Token.pins property. They can then be manipulated using the methods described below.

class SCWS.Pin()¶: Represents a PIN that protects smart card contents.

Pin.token¶: The SCWS.Token() object this PIN belongs to.

Pin.label¶: The PIN label. Can be undefined if the card has a single PIN without explicit label defined.

Pin.initialized¶: Boolean indicating if the PIN has been initialized.

Pin.toBeChanged¶: Boolean indicating if the PIN need to be changed before use.

Pin.blocked¶: Boolean indicating if the PIN is blocked.

Pin.tryCountLow¶: Boolean indicating if the PIN try counter is lower than the maximum (an unsuccessful verification attempt has been made).

Pin.lastTry¶: Boolean indicating if the PIN try counter shows only one attempt remaining.

Pin.remainingTries¶: Number of remaining tries for the PIN verification. Can be undefined if the information is unavailable.

Pin.maxTries¶: Number of maximum tries for the PIN verification. Can be undefined if the information is unavailable.

Pin.soRemainingTries¶

Number of remaining tries for the SO PIN verification. Can be undefined if the information is unavailable.

Available on SCWSAPI version 2.13 and later.

Pin.soMaxTries¶

Number of maximum tries for the SO PIN verification. Can be undefined if the information is unavailable.

Available on SCWSAPI version 2.13 and later.

Pin.puksAvailable¶: 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.

Pin.validated¶: Boolean indicating if the PIN has been successfully verified (access to the private objects is granted).

Pin.initSubmissionsState¶: SCWS.CredentialState() object which can be used during a requestCredential()/login() process in order to update the information (remaining tries, a potential error…) in the PIN dialog.

Pin.credentialProperties¶

Javascript object containing PIN properties, with the following fields:

pinLabel: The pin label as a string.

methods: The supported methods by the corresponding slot, as a Javascript object. This object has itself the following fields:

facialBio: Boolean indicating if facial biometry is supported. If true and supported on this platform, a facial biometry verification can be done through Pin.requestCredential().

fingerBio: Boolean indicating if fingerprint biometry is supported. If true and supported on this platform, a fingerprint biometry verification can be done through Pin.requestCredential().

fingerBioIsOneToManySupported: Boolean indicating if fingerprint one to many match on card is supported by the token. This value is used only if fingerBio equals true.

Pin.requestCredential(credentialProperties, credentialState, readerName, cardLabel)¶

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() process, against the user PIN.

If a secure biometric reader (SBR2 reader) is used for fingerprint verification, credentialProperties parameter must be created using Pin.credentialProperties from a valid SCWS.Pin() object. The corresponding SCWS.Token() must exist and be available. This feature is available from middleware version 6.23.1.0.

Arguments:

credentialProperties – the credential properties as a Javascript object. If a token has been read previously, value of Pin.credentialProperties can be used from a specific SCWS.Pin() object. If no token has been read before opening the PIN dialog, this parameter can be build respecting Pin.credentialProperties format. In the case of facial or finger biometry, the value of Pin.credentialProperties must be used.
credentialState – the SCWS.CredentialState() object which displays the current credential state (remaining tries, a potential error…) in the PIN dialog. At the beginning of a Pin.requestCredential()/Pin.login() sequence, credentialState can be created through Pin.initSubmissionsState or SCWS.CredentialState() if no token was read before.
readerName – the reader name to display, as a string. Optional.
cardLabel – the card label to display, as a string. Optional.

Returns:

A Promise resolving to a SCWS.CredentialValue() object. This object can be directlty used in Pin.login() operation. If requesting credential is cancelled by the user, resolved value is undefined. If an error occured while requesting credential, returned Promise is rejected with a SCWS.Error().

Examples:

const NO_CRITICAL_ERRORS = [
    "CKR_PIN_INCORRECT",
    "CKR_PIN_LEN_RANGE",
    "CKR_PIN_INVALID"
];

const loginLoop = function() {
    SCWS.Pin.prototype.requestCredential(credentialProperties, credentialState, readerName, cardLabel).then(
        function(credential) {
            pin.login(credential, credentialState).then(
                function() {
                    console.log("Successful login");
                },
                function(error) {
                    // re-launch request credential/login process on no critical errors
                    if (NO_CRITICAL_ERRORS.indexOf(error.code) !== -1)
                        loginLoop();
                    else
                        console.log("failed to login: " + error);
                }
            );
        },
        function(error) {
            console.log("failed to request credential: " + error);
        }
    );
};

// Use case 1: A token has been read and a PIN dialog is used to get `CredentialValue` object.
// we assume `pin` object is correctly set
var credentialProperties = pin.credentialProperties;
var credentialState      = pin.initSubmissionsState;
var readerName           = pin.token.reader.name;
var cardLabel            = pin.token.label;

loginLoop();

// Use case 2: No token has been read and a PIN dialog is used to get `CredentialValue` object.
// User creates the credentialProperties object in order to display the wanted information in the PIN dialog
var credentialProperties = {
    pinLabel: "My PIN label",
    methods: {
        facialBio: false,
        fingerBio: false
    }
};
var credentialState      = new SCWS.CredentialState();
var readerName           = "My reader name";
var cardLabel            = "My card label";

loginLoop();

Pin.startAutoLogin(counter)¶

Starts a PIN cache session.

On the next call to SCWS.Pin.login() with false value, the value of the PIN will be saved for use on subsequent calls.

Signatures with non-repudiable keys (see SCWS.Key.alwaysAuthenticate) through SCWS.Key.sign() and SCWS.Key.hashAndSign() can also be repeated without an explicit call to SCWS.Pin.login(). In this case, the login will be made implicitly if the user is no longer logged in.

This feature is available from 6.23.21.0 middleware version.

Arguments:

counter – (optional) Maximum number of signatures accepted in the session. When this number is reached, the PIN value is removed from the cache. On the next call to SCWS.Pin.login(), the value of the PIN will not be saved.

Returns:

A Promise resolved when the operation has been made (the resolution value is undefined).

Pin.stopAutoLogin()¶

Stops a PIN cache session.

The value of the PIN is removed from the cache. From this point, an explicit call to SCWS.Pin.login() is required before any signature.

On the next call to SCWS.Pin.login() with false value parameter, the PIN value will not be saved anymore.

This feature is available from 6.23.21.0 middleware version.

Returns:: A Promise resolved when the operation has been made (the resolution value is undefined).

Pin.login(value, state)¶

Verifies the PIN.

The value parameter can have the following values/types:

the PIN value as a string.

a SCWS.CredentialValue() object. From 6.23.1.0 middleware version, a SCWS.CredentialValue() object can be created using Pin.requestCredential().

null or undefined if a protected authentication path exists (see Token.protectedAuthPath).

false, in which case the pin entering is delegated to the middleware through its own graphical interface, which is the recommended option: this guarantees that the pin does not go through to the browser.

The state parameter can take the following values:

true indicating that the verification operation must be made against the security officer (administrator or unblocking) PIN. Otherwise, targets the user PIN.

a SCWS.CredentialState() to use with Pin.requestCredential(). In this case, given state will be updated by this function call. A further call of Pin.requestCredential() with the state parameter will display a PIN dialog with updated information.

Arguments:

value – The PIN value.
state – (optional) the credential state or true if login must be made against the security officer.

Returns:

A Promise resolved when the operation has been made (the resolution value is undefined).

Pin.change(oldCredential, newCredential)¶

Changes the PIN. By default, the operation is made against the user PIN. If the security officer (SO) is logged (using PIN.login()), and the standard user is not logged, the change operation is made against the SO PIN.

Arguments:

oldCredential – The current PIN value. May be null or undefined if a protected authentication path exists (see Token.protectedAuthPath).
newCredential – The new PIN value. May be null or undefined if a protected authentication path exists.

Returns:

A Promise resolved when the operation has been made (the resolution value is undefined).

Pin.init(newValue)¶

Reinitializes the PIN value (unblocking it if required). The operation can only be made against the user PIN, and requires the security officer PIN to be verified (see Pin.login()).

Arguments:

newValue – The new PIN value. May be null or undefined if a protected authentication path exists.

Returns:

A Promise resolved when the operation has been made (the resolution value is undefined).

Pin.bioEnroll()¶

Performs a bio fingerprint enrollment.

The whole operation is managed by the middleware through a dialog. Several fingerprints can be enrolled by the user in a single process. This feature is available for desktop only and from 6.23.33.3 middleware version.

Returns:: A Promise resolved when the operation has been made (the resolution value is undefined).

Pin.logout()¶

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

Returns:: A Promise resolved when the operation has been made (the resolution value is undefined).

Pin.getConstraints()¶

Returns the format constraints of the PIN (which must be enforced when changing the PIN value).

The constraints are returned as an array of JavaScript objects, one for each constraint. The objects describing a constraint all have a type field, indicating the type of constraint, and optionally, some additional fields providing the parameters for the constraint. The type can be one of the following (this list may be extended in the future):

"minLength": The number of characters in the PIN must be at least the value given in the minLength field.
"exactLength": The number of characters in the PIN must be exactly the value given in the length field.
"minMaxLength": The number of characters in the PIN must be between the value given in the minLength field and the value given in the maxLength field (inclusive).
"numeric": The PIN must contain only numeric characters (0 to 9).
"minAlphabetic": The PIN must contain at least count alphabetic characters.
"minAlphanumeric": The PIN must contain at least count alphanumeric characters.
"minDigits": The PIN must contain at least count digits characters.
"minUpperCase": The PIN must contain at least count uppercase letters.
"minSpecial": The PIN must contain at least count special characters.
"minLowerCase": The PIN must contain at least count lowercase letters.
"newOldDifferent": The new PIN value must be different from the old PIN value.
"newOldDissimilar": At least threshold percent of the characters must differ between the new PIN and the old PIN value.
"maxIdenticalSequence": There must be no sequences of count identical characters.
"maxIncDecSequence": There must be no sequences of count increasing/decreasing characters”

Returns:: A Promise resolving to the constraints description, as described above.

Pin.checkConstraints(oldPin, newPin)¶

Checks the format constraints of the PIN.

The constraints (obtained using the Pin.getConstraints() method) are checked against the provided old and new PIN values. This method can be used to provide feedback to the user when changing their PIN value.

The result of the check is returned as an array of boolean, each value indicating whether the constraint is fulfilled or not (in the same order as the array returned from getConstraints).

Arguments:

oldPin – The current PIN value (only used to check the "newOldDifferent" and "newOldDissimilar" constraints).
newPin – The new PIN value to be checked.

Returns:

A Promise resolving to the result array.

class SCWS.CredentialState()¶: Represents the credential state during a Pin.requestCredential()/Pin.login() sequence.

class SCWS.CredentialValue()¶: Represents the credential value that can be used for login operation against the user PIN. It can be obtained by using Pin.requestCredential().

PINs¶

SCWS API

Table of contents

Related Topics