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 usingSCWS.createEnvironment()
.
- static 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 updatedSCWS.readers
array itself.
- static 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 aPromise
).
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 theSCWS.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 ofSCWS.Object()
items.
Software token¶
A virtual token associated to the software certificates available on the local machine can be obtained using this function:
- static 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 theirObject.ckId
property (which is dynamically simulated).- Returns:
A
Promise
resolving to theSCWS.Token()
object resulting from the operation.