smartcard

Smartcard library.

This is a simple wrapper around Santiago Gimeno's great pcsclite library.

Used by Card Spy

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,

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

'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

'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

'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}]`);
});