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.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 login() process in order to update the remaining PIN tries and a potential error informations 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.

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.
credentialState – the SCWS.CredentialState() object which displays the current credential state (remaining tries, a potential error…) in the PIN dialog.
readerName – the current readerName. Optional.
cardLabel – the current cardLabel. 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:

// 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 state = pin.initSubmissionsState;
pin.requestCredential(
    pin.credentialProperties,
    state,
    pin.token.reader.name,
    pin.token.label).then(function(credential) {
        pin.login(credential).then(function() {
            console.log("Login successful");
        });
    }
);

// Use case 2: No token has been read and a PIN dialog is used to get `CredentialValue` object.
// User creates the pinProperties object in order to display the wanted informations in the PIN dialog
var pinProperties = {
    pinLabel: "...",
    methods: {
        facialBio: false,
        fingerBio: false
    }
};
var readerName = "My reader name";
var cardLabel = "My card label";
var state = new SCWS.CredentialState();
SCWS.Pin.prototype.requestCredential(
    pinProperties,
    state,
    readerName,
    cardLabel).then(function(credential) {
        // ...
        // ask the user to present a card if needed
        // we assume a `pin` object has been retrieved from connected token
        pin.login(credential).then(function() {
            console.log("Login successful");
        });
    }
);

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, so)¶

Verifies the PIN.

Arguments:

value – The PIN value or a SCWS.CredentialValue() object. From 6.23.1.0 middleware version, a SCWS.CredentialValue() object can be created using Pin.requestCredential(). May be null or undefined if a protected authentication path exists (see Token.protectedAuthPath). May also be set to 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.
so – (optional) Boolean indicating if the verification operation must be made against the security officer (admnistrator or unblocking) PIN. If false or undefined, targets the user PIN.

Returns:

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

Pin.change(oldCredential, newCredential)¶

Changes the PIN or more generally the credential defined by newCredential parameter. In the case of standard PIN, the operation can only be made against the user PIN. Using a SCWS.CredentialValue() object for newCredential parameter is only available since 6.23.1.0 middleware version.

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 or a credential value using SCWS.CredentialValue(). Using Pin.requestCredential() to create a SCWS.CredentialValue() is not supported. 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.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).
"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 specific operation. See Pin.requestCredential() function.

The constructor takes two parameters: state and a potential error. The state argument is a Javascript object with the following fields:

pinTriesLeft: the PIN remaining tries. Can be obtained with Pin.remainingTries.

bioFingerprint (optional) : fingerprint authentication object information as a Javascript object with the following fields:

triesLeft: the remaining tries of the fingerprint authentication object.

fingers: an Array of 10 Booleans, indicating if corresponding finger is enrolled or not. Position 0 stands for left little finger, position 9 stands for right little finger.

bioFacial (optional) : facial authentication object information as a Javascript object with the following fields:

triesLeft: the remaining tries of the facial authentication object.

Arguments:

state – the pin state as a Javascript object as defined above.
error – a potential error message as a string that can be displayed in the PIN dialog during a specific process.

CredentialState.remainingTries¶: Number of remaining tries for the PIN verification to be displayed in the PIN Dialog. Can be set to null to not display this information.

CredentialState.fingerprintRemainingTries¶: If applicable, number of remaining tries for the fingerprint authentication object to be displayed in the PIN Dialog. Can be set to null to not display this information.

CredentialState.fingerprintFingers¶: If applicable, an Array containing 10 Booleans. Each Boolean indicates if corresponding finger is enrolled or not. Position 0 stands for left little finger, position 9 stands for right little finger.

CredentialState.facialRemainingTries¶: If applicable, number of remaining tries for the facial authentication object to be displayed in the PIN Dialog. Can be set to null to not display this information.

CredentialState.error¶: Potential error message that can be displayed in the PIN Dialog. Can be set to null to not display this information.

class SCWS.CredentialValue()¶

Represents the credential value that can be used for token operations. It can be obtained by using Pin.requestCredential() or created using this constructor. The constructor takes one parameter: value which is an object with the following fields:

type: the credential type as a string. Can be "pin", "finger" or "facial".

subtype: for finger credential type, the subtype is the finger index as an integer. It must be undefined otherwise.
0 stands for left little finger, 9 stands for right little finger.

data: the credential value as an ArrayBuffer.

CredentialValue.value¶: Credential value that can be provided to Pin.login() process. This can obtained by using requestCredential() function.

PINs¶

SCWS API

Table Of Contents

Related Topics