Readers and tokens

Obtaining readers

The smart card readers (whether virtual of physical) can be obtained through the following means:

SCWS.readers

Maintains the list of all known smart card readers in the system, as an array of SCWS.Reader() objects. This list is initially empty when the page loads, until the environment is established using SCWS.createEnvironment().

SCWS.updateReaderList()

Fills in or forces the update of the SCWS.readers array.

If updates are made to the reader list within the processing, the appropriate event callbacks are called.

Returns

A Promise resolved when the operation is complete. The resulting value is the updated SCWS.readers array itself.

SCWS.getReader(name)

Returns the reader with the given name.

Arguments
  • name – The reader name, as a string.

Returns

The requested SCWS.Reader() object (the result is returned immediately, not through a Promise).

Reader events

Reader events can be monitored by providing the following callback functions:

SCWS.onreaderadded

Callback (can be assigned to a user function) used to receive notifications when a reader is plugged in the computer.

The new SCWS.Reader() object is given as a parameter to the callback function.

SCWS.onreaderremoved

Callback (can be assigned to a user function) used to receive notifications when a reader is unplugged from the computer.

The removed SCWS.Reader() object is given as a parameter to the callback function.

SCWS.onreaderstatechanged

Callback (can be assigned to a user function) used to receive notifications when the state of a reader changes (e.g. insertion or withdrawal of a card, …).

The affected SCWS.Reader() object is given as a parameter to the callback function. Its properties can be consulted (e.g. Reader.status, Reader.cardPresent, …) to obtain more information about the event.

Manipulating readers

The Reader class is described below:

class SCWS.Reader()

Represents a smart card reader (either a physical, hardware reader, or a virtual smart card reader).

Reader.name

The name of the reader.

Reader.cardPresent

Boolean indicating if a card is inserted in the reader.

Reader.status

Status of the reader, as a string. The following status strings can be returned:

  • "unavailable": Indicates the reader has been removed (unplugged from the computer).

  • "mute": The inserted card is mute (no answer on reset), the connection is therefore impossible.

  • "exclusive": The reader is being used in exclusive mode by another process, the connection is impossible yet.

  • "ok": The reader is in a normal state (whether a card is inserted or not).

  • Any other value indicates a problem with an indeterminate cause (driver problem, or malfunction).

Reader.dongle

Boolean indicating if the reader is known as a USB dongle type (as opposed to a standard ID-1 format card reader). Note that this is indicative, and based on an internal registry of reader names.

Reader.virtual

Boolean indicating if the reader is a virtual smart card.

Reader.connect()

Connects to the card inserted in the reader. This method succeeds only if the card is supported by the middleware.

Returns

A Promise resolving to the SCWS.Token() object resulting from the operation.

Reader.requiresNfcTagReaderSession()

Boolean indicating if the device supports iOS NFC Tag Reader Session.

Manipulating tokens

The Token class is described below:

class SCWS.Token()

Represents connection to a smart card (or more generally, any cryptographic device). Token objects are obtained by calling the Reader.connect() method.

Token.reader

The SCWS.Reader() object from which this token is issued.

Token.manufacturer

String containing the token manufacturer name.

Token.model

String containing the token model name.

Token.serialNumber

String containing the token serial number.

Token.label

String containing the token label.

Token.initialized

Boolean indicating whether this token has been initialized.

Token.protectedAuthPath

Boolean idicating whether this token allows user authentication through a hardware protected path (like a PIN pad reader, or using biometric recognition).

Token.pins

Array of SCWS.Pin() objects decribing all the PINs available with this card.

Token.disconnect()

Disconnects from the token. Must be called when the application terminates (e.g. from the onbeforeunload/onunload events), or before.

Returns

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

Token.updateInfos(slot)

Forces the update of the internally cached state of the token (e.g. PIN status).

For all operations that are likely to invalidate the cached state (like PIN verification operations), this is done automatically. You normally don’t need to call this method explicitly.

Returns

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

Token.getObjects()

Retrieves all objects found in the token (certificates and keys). Note that private objects may not be returned if the associated PIN has not been verified previously.

Each call to this method generates a list of newly created objects, even if the objects have been previously obtained. To check whether a new object corresponds to a previously obtained one, the Object.handle property can be used. This value is guaranteed to be the same for two items referring to the same physical object in the token.

Returns

A Promise resolving to the array of SCWS.Object() items.

Software token

A virtual token associated to the software certificates available on the local machine can be obtained using this function:

SCWS.getSoftToken()

Returns the “software” token.

The software token is a virtual cryptographic token containing the certificates and keys that are available on the local machine. On Windows, the objects comes from the contents of the “Personal” certificate store. On MacOS, the objects come from the contents of the “Session” keychain. On Linux, this function is currently unavailable.

The usage of the software token is similar to a physical cryptographic token: keys and certificates can be obtained using the Token.getObjects() functions, and they are linked together through their Object.ckId property (which is dynamically simulated).

Returns

A Promise resolving to the SCWS.Token() object resulting from the operation.