@ieskel/smartcard v0.0.49

About

This library is a refactoring with added typings of smartcard library by tomkp and is built around pcsclite library by Santiago Gimeno
Original smartcard package on NPM
pcsclite package on NPM

Tested with ACR39U and ACR122U readers

Dependencies and problems (Debian/Ubuntu)

PCSC

Install basic dependencies by running
sudo apt install libpcsclite1 libpcsclite-dev pcscd
and check pcscd service status for any error with
service pcscd status

Optionally install pcsc tools package
sudo apt install pcsc-tools
and check if your reader(s) and card(s) are working by executing
pcsc_scan
This should show all (contact and NFC) readers recognized by your system and print info about inserted cards (if any).

NFC issues

Sometimes NFC readers won't work because of other drivers blocking the usb bus. Plug in your reader and check pcscd service logs:

$ journalctl -u pcscd.service
...
xxx XX XX:XX:XX xxxxxx pcscd[5465]: 29870365 ccid_usb.c:672:OpenUSBByName() Can't claim interface 1/10: LIBUSB_ERROR_BUSY
...

LIBUSB_ERROR_BUSY tells that the interface is used by something else.

Check what driver is using the device:

$ lsusb -t
/:  Bus 01.Port 1: Dev 1, Class=root_hub, Driver=xhci_hcd/16p, 480M
    |__ Port 1: Dev 23, If 0, Class=Chip/SmartCard, Driver=pn533, 12M

Then view the dependency tree of that driver (pn533 in this case)

$ lsmod | grep pn533
Module                  Size  Used by
pn533_usb              20480  0
pn533                  49152  1 pn533_usb
nfc                   147456  1 pn533

in this case we have following dependency tree

pn533_usb
  └pn533
    └nfc

There are two possible ways to disable those drivers:

1. Unload modules from kernel:
   sudo rmmod pn533_usb pn533 nfc
   In case you need to reenable them again just run:
   sudo modprobe pn533_usb pn533 nfc

   > No system reboot required

2. Add drivers to blacklist
   Open(create) file /etc/modprobe.d/nfc-blacklist.conf and add following lines:

   ```
   blacklist pn533_usb
   blacklist pn533
   blacklist nfc
   ```
   >System reboot required

Now install libnfc:
sudo apt install libnfc-bin

And finally restart pcscd:
sudo service pcscd restart

Use one of the following tools to check if the reader is working:

$ nfc-scan-device
nfc-scan-device uses libnfc 1.8.0
1 NFC device(s) found:
- ACS / ACR122U PICC Interface:
    acr122_usb:001:023

$ nfc-list
nfc-list uses libnfc 1.8.0
NFC device: ACS / ACR122U PICC Interface opened

$ pcsc_scan
Using reader plug'n play mechanism
Scanning present readers...
0: ACS ACR122U PICC Interface 00 00
 
Fri Aug 23 16:47:33 2024
 Reader 0: ACS ACR122U PICC Interface 00 00
  Event number: 0
  Card state: Card removed,

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