Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.
Awesome Lists | Featured Topics | Projects
https://github.com/tomkp/smartcard

PCSC smartcard reader library for nodejs
https://github.com/tomkp/smartcard
card-reader emv iso7816 nodejs pcsc smartcard
Last synced: 6 days ago
JSON representation
PCSC smartcard reader library for nodejs
Host: GitHub
URL: https://github.com/tomkp/smartcard
Owner: tomkp
License: mit
Created: 2016-03-26T08:57:38.000Z (over 8 years ago)
Default Branch: master
Last Pushed: 2023-01-07T04:20:40.000Z (almost 2 years ago)
Last Synced: 2024-12-08T05:30:41.963Z (14 days ago)
Topics: card-reader, emv, iso7816, nodejs, pcsc, smartcard
Language: JavaScript
Homepage:
Size: 396 KB
Stars: 134
Watchers: 9
Forks: 56
Open Issues: 14
Metadata Files:
- Readme: README.MD
- License: LICENSE
Awesome Lists containing this project

README

        # smartcard

Smartcard library.

This is a simple wrapper around [Santiago Gimeno's](https://www.npmjs.org/~sgimeno) great [pcsclite](https://github.com/santigimeno/node-pcsclite) library.

Used by [Card Spy](http://card-spy.surge.sh)

## API

The following objects are defined by the `smartcard` library, each contains its own set of methods and events.

### Class: Devices

A general object that provides access to all smartcard related devices.

#### Events

The `devices` object emits the following events

##### Event: 'device-activated'

Emitted when a card reader is attached.

Returns:

* `Object`

  * `Device`

  * `Array`: List of all devices, returned via `devices.listDevices()`

##### Event: 'device-deactivated'

Emitted when a card reader is detached.

Returns:

* `Object`

  * `Device`

  * `Array`: List of all devices, returned via `devices.listDevices()`

##### Event: 'error'

Emitted when an error occurs

Returns `Object`:

* _error_ `Error`

#### Methods

The following methods are available within the `devices` class.

##### Constructor

The constructor for a devices object takes no arguments,

```javascript

devices = new Devices();

```

##### `devices.onActivated()`

Returns `Promise`

* Resolves with activation _event_

##### `devices.onDeactivated()`

Returns `Promise`

* Resolves with deactivation _event_

##### `devices.listDevices()`

Returns `Object` a list of the different devices attached, each a `device` object

##### `devices.lookup(name)`

* _name_ `String`: The text name of a device

* Returns `Device`

### Class: Device

An object representing a specific card reader (device).

#### Methods

The following methods are available within the `device` class.

##### `device.getName()`

Returns the name of the attached device.

##### `device.transmit(data, res_len, protocol, cb)`

Sends a command to the connected device

* _data_ `Buffer`: data to be transmitted

* _res_len_ `Number`: Maximum length of the expected response, includes the 2 byte response (sw1 and sw2)

* _protocol_ `Number`: Protocol to be used in the transmission

* _cb(error,response)_ `Function`: Called when transmit function completes

  * _error_ `Error`

  * _output_ `Buffer`

#### Events

The `device` object emits the following events

##### Event: 'card-inserted'

Emitted when a smartcard is inserted into a card reader

Returns `Object`:

* _device_ `Device`

* _card_ `Card`

##### Event: 'card-removed'

Emitted when a smartcard is removed from a card reader

Returns `Object`:

* _name_ `String`

* _card_ `Card`

### Class: Card

An object representing an attached smart card.

#### Methods

The following methods are available within the `card` class.

##### `card.getAtr()`

Returns `String` containing the atr of the card

##### `card.issueCommand(commandApdu, callback)`

Sends a command to the card

* _commandApdu_: The command to be sent to the card

  * `String`

  * `Buffer`

  * `Array`

  * `CommandApdu`

* _callback(error,response)_: (optional) Function to call upon completion of the command

  * _error_ `Error`

  * _response_ `Buffer`

Returns `Promise`

  * Resolves with _response_ `Buffer`

  * Rejects with _error_ `Error`

If no callback is specified, returns a `Promise`

*

#### Events

The `card` object emits the following events

##### Event: 'command-issued'

Emitted when a command is sent to the smartcard.

Returns `Object`:

* _card_ `Card`

* _command_ `Buffer`

##### Event: 'response-received'

Emitted when a response is received from the card.

Returns `Object`:

* _card_ `Card`

* _command_ `Buffer`

* _response_ `ResponseApdu`

### Class: CommandApdu

An object representing a command to send to a smart card

#### Methods

The `CommandApdu` class has the following methods.

##### Constructor `CommandApdu(obj)`

Creates a new instance and sets the appropriate items

* _obj_ `Object`

  * _cla_ `Number`: The class of the command, typically 0

  * _ins_ `Number`: The instruction

  * _p1_ `Number`: The value of p1

  * _p2_ `Number`: The value of p2

  * _data_ `Array` (optional): The value of data

  * _le_ `Number` (optional): The value of le

OR

* _obj_ `Array`: Byte array representing the whole command

##### `CommandApdu.toBuffer()`

Converts the command to a Buffer

* Returns `Buffer`

##### `CommandApdu.toString()`

Converts the command to a hex string

* Returns `String`

##### `CommandApdu.toByteArray()`

Converts the command to a byte array

* Returns `Array`

##### `CommandApdu.setLe(le)`

Updates the le value of the command

* _le_ `Number`: The new le value

### Class: ResponseApdu

Class representing a response from the card

#### Methods

The `ResponseApdu` class has the following methods.

##### Constructor

##### `ResponseApdu.meaning()`

Interprets the return code and attempts to provide a text translation.

* Returns `String`

##### `ResponseApdu.getDataOnly()`

Returns the response data without including the status code

* Returns `String`

##### `ResponseApdu.getStatusCode()`

Returns only the status code

* Returns `String`

##### `ResponseApdu.isOk()`

Check if the status code is 9000

* Returns `Boolean`

##### `ResponseApdu.buffer()`

Returns the whole buffer, status code and data

* Returns `Buffer`

##### `ResponseApdu.hasMoreBytesAvailable()`

Reads the status code and looks for a 61 as sw1, meaning more data is available

* Returns `Boolean`

##### `ResponseApdu.numberOfBytesAvailable()`

Reads sw2 staus code to return number of bytes left, when sw1 is 61. A value of 0 means there are more than 256 bytes remaining.

* Returns `Number`

##### `ResponseApdu.isWrongLength()`

Checks status code for 6c as sw1

* Returns `Boolean`

##### `ResponseApdu.correctLength()`

If sw1 is 6c, returns the correct length from sw2. A value of 0 means there are more than 256 bytes remaining.

* Returns `Number`

### Class: Iso7816Application

An object offering general commands to most ISO7816 compliant smart cards.

#### Methods

##### Constructor `Iso7816Application(card)`

Sets up the `Iso7816Application` object

* _card_ `Card`: The card to communicate with using ISO7816 standards

##### `Iso7816Application.issueCommand(commandApdu)`

Sends the provided command to the card. Automatically retrieve the full response, even if it requires multiple GET_RESPONSE commands

* _commandApdu_ `CommandApdu`: Command to send to the card

Returns

* `ResponseApdu` Complete response from card

##### `Iso7816Application.selectFile(bytes, p1, p2)`

Sends the SELECT command to the card, often called selecting an application

* _bytes_ `Buffer`: The resource locater (AID, etc)

* _p1_ `Number`: Value to specify as the p1 value

* _p2_ `Number`: Value to specify as the p2 value

Returns

* `ResponseApdu` Complete response from card

##### `Iso7816Application.getResponse(length)`

Sends a single GET_RESPONSE command to the card

* _length_ `Number`: The length of the response expected, maximum is 0xFF

Returns

* `ResponseApdu` Complete response from card

##### `Iso7816Application.getResponse(sfi,record)`

Sends a READ_RECORD command to the card

* _sfi_ `Number`: The sfi

* _record_ `Number`: The record

Returns

* `ResponseApdu` Complete response from card

##### `Iso7816Application.getData(p1, p2)`

Sends a GET_DATA command to the card

* _p1_ `Number`: Value to specify as the p1 value

* _p2_ `Number`: Value to specify as the p2 value

Returns

* `ResponseApdu` Complete response from card

#### Events

The `Iso7816Application` class emits the following events

##### Event: 'application-selected'

Emitted when a successful reply to a `selectFile()` command is received.

Returns `Object`:

* _application_ `String`

## Examples

### With event emitter

```javascript

'use strict';

const smartcard = require('smartcard');

const Devices = smartcard.Devices;

const devices = new Devices();

devices.on('device-activated', (event => {

    console.log(`Device '${event.device}' activated`);

    event.devices.map((device, index) => {

        console.log(`Device #${index + 1}: '${device.name}'`);

    });

}));

```

### Using promises

```javascript

'use strict';

const smartcard = require('smartcard');

const Devices = smartcard.Devices;

const devices = new Devices();

devices.onActivated().then(event => {

    console.log(`Device '${event.device}' activated`);

    event.devices.map((device, index) => {

        console.log(`Device #${index + 1}: '${device.name}'`);

    });

});

```

### Selecting the Payment Systems Environment on an EMV (Chip & Pin) card

```javascript

'use strict';

const smartcard = require('smartcard');

const Devices = smartcard.Devices;

const Iso7816Application = smartcard.Iso7816Application;

const devices = new Devices();

devices.on('device-activated', event => {

    const currentDevices = event.devices;

    let device = event.device;

    console.log(`Device '${device}' activated, devices: ${currentDevices}`);

    for (let prop in currentDevices) {

        console.log("Devices: " + currentDevices[prop]);

    }

    device.on('card-inserted', event => {

        let card = event.card;

        console.log(`Card '${card.getAtr()}' inserted into '${event.device}'`);

        card.on('command-issued', event => {

            console.log(`Command '${event.command}' issued to '${event.card}' `);

        });

        card.on('response-received', event => {

            console.log(`Response '${event.response}' received from '${event.card}' in response to '${event.command}'`);

        });

        const application = new Iso7816Application(card);

        application.selectFile([0x31, 0x50, 0x41, 0x59, 0x2E, 0x53, 0x59, 0x53, 0x2E, 0x44, 0x44, 0x46, 0x30, 0x31])

            .then(response => {

                console.info(`Select PSE Response: '${response}' '${response.meaning()}'`);

            }).catch(error => {

                console.error('Error:', error, error.stack);

            });

    });

    device.on('card-removed', event => {

        console.log(`Card removed from '${event.name}' `);

    });

});

devices.on('device-deactivated', event => {

    console.log(`Device '${event.device}' deactivated, devices: [${event.devices}]`);

});

```