Bondi logo

The Bondi apdu Module - Version 1.5

February 2010

Authors

© 2009-2010 OMTP Ltd. All rights reserved. OMTP and OMTP BONDI are registered trademarks of OMTP Ltd.

Abstract

BONDI APDU module

Table of Contents

Summary of Methods

Interface Method
APDUManager APDUConnection createConnection(APDUSlot slot)
APDUConnection boolean isCardPresent()
PendingOperation openLogicalChannel(OpenSuccessCallback successCallback, ErrorCallback errorCallback, DOMString aid)
PendingOperation openDefaultChannel(SuccessCallback successCallback, ErrorCallback errorCallback)
void close()
ByteArray GetAnswerToReset()
PendingOperation transmit(TransmitSuccessCallback successCallback, ErrorCallback errorCallback, Byte Class, Byte Instruction, Byte P1, Byte P2, unsigned short Lc, ByteArray message, unsigned short Le)
APDUSlot

1. Introduction

This module allows the communication between web application and a smart card by using the Application Protocol Data Units (APDUs). An APDU is a short message represented by bytes. APDU messages are either commands or responses. APDU protocol is defined by ISO 7816-4

1.2. Features

This is the list of URIs used to declare this API's features, for use in bondi.requestFeature. For each URL, the list of functions covered is provided.

http://bondi.omtp.org/api/1.5/apdu.access

Access to opening APDU Slot connection, used by APDUManager.createConnection

Device capabilities:

  • apdu.access
http://bondi.omtp.org/api/1.5/apdu.openLogicalChannel

Access to opening APDU connection to a card application using a logical channel, used by APDUConnection.openLogicalChannel

Device capabilities:

  • apdu.openLogicalChannel
http://bondi.omtp.org/api/1.5/apdu.openDefaultChannel

Access to opening APDU connection to a card the default channel, used by APDUConnection.openDefaultChannel

Device capabilities:

  • apdu.openDefaultChannel
http://bondi.omtp.org/api/1.5/apdu.transmit

Access to sending an APDU command, used by APDUConnection.transmit

Device capabilities:

  • apdu.transmit

1.3. Device capabilities

apdu.access

Opens an connection between the device and a slot.

Security parameters:

  • slot: string representing the slot (e.g."slot0")
apdu.openLogicalChannel

Opens an APDU connection between the device and an application in the UICC or any other secure element.

Security parameters:

  • slot: string representing the slot (e.g."slot0")
  • aid: string representing the card application (e.g. "a0 00 00 00 62 03 01 0c 02 01")
apdu.openDefaultChannel

Opens an APDU connection between the device and the UICC or any other secure element.

Security parameters:

  • slot: string representing the slot (e.g."slot0")
apdu.transmit

Send an APDU command.

Security parameters:

  • Class: Class of the command
  • ins: Command instruction
  • P1: First parameter of the command
  • P2: Second parameter of the command

2. Type Definitions

2.1. APDUSlotArray

Array of smart cards or secure elements slots. 

        typedef sequence<APDUSlot> APDUSlotArray;

3. Interfaces

3.4. APDUManager

Management of the APDU communication. 

        interface APDUManager {

                readonly attribute APDUSlotArray availableSlots;

                APDUConnection createConnection(in APDUSlot slot)
                        raises(SecurityError, DeviceAPIError);
        };

Provides a way to open communication with a smart card or secure element slot.

Code example
  var slot = availableSlots[0];
  var cnx;
  cnx = APDUManager.createConnection(slot);

Attributes

readonly APDUSlotArray availableSlots

The list of available slots on the device.

Might be updated if a new slot appears (e.g. a bluetooth enabled card reader)

Methods

createConnection

Creates an instance of the APDUConnection interface

Signature
APDUConnection createConnection(in APDUSlot slot);
Parameters
  • slot: is one of the slots referenced by availableSlots.
Return value
the object containing the reference to the APDU Connection
Exceptions
  • SecurityError:

    PERMISSION_DENIED_ERROR when access is denied by the security policy.

  • DeviceAPIError:

    INVALID_ARGUMENT_ERROR if an invalid slot is passed

API features
http://bondi.omtp.org/api/apdu.access

3.5. APDUConnection

Interface to communicate through APDU commands. 

        interface APDUConnection {

                readonly attribute APDUSlot slot;

                readonly attribute DOMString aid;

                readonly attribute short channel;

                boolean isCardPresent();

                PendingOperation openLogicalChannel(in OpenSuccessCallback successCallback, in ErrorCallback errorCallback, in DOMString aid);

                PendingOperation openDefaultChannel(in SuccessCallback successCallback, in ErrorCallback errorCallback);

                void close()
                        raises(DeviceAPIError, APDUError);

                ByteArray GetAnswerToReset();

                PendingOperation transmit(in TransmitSuccessCallback successCallback, in ErrorCallback errorCallback, in Byte Class, in Byte Instruction, in Byte P1, in Byte P2, in unsigned short Lc, in ByteArray message, in unsigned short Le);
        };
Code example
  var cnx;

  // Define the APDUExchange success callback.
  function APDUSuccess(response) {
    alert("APDU Response is " + response);
  }

  // Define the APDUExchange failure callback.
  function APDUFailure(e) {
    alert("Error while executing the APDU Command");
  }

  // Define the open success callback.
  function openSuccess() {
    alert("APDU Connection opened successfully");

      // send a select file ( selection of 3F00)
      var data = new ByteArray(1);

      data[0] = 0x3F;
      data[1] = 0x00;

     cnx.transmit(APDUSuccess, APDUFailure, 0x00, 0xA4, 0x00, 0x02, data, 0x00);
   }

  // Define the open failure callback.
  function openFailure(e) {
    alert("Cannot open the APDUSlot connection");
  }

  var slot = availableSlots[0];
  var aid = "a0 00 00 00 62 03 01 0c 02 01";

  cnx = APDUManager.createConnection(slot);
  // Get ATR
  var ATR = cnx.GetAnswerToReset();
  cnx.openLogicalChannel(openSuccess, openFailure, aid);

Attributes

readonly APDUSlot slot

The slot used by this connection

readonly DOMString aid

Card application identifier

readonly short channel

The logical channel used by this connection

Methods

isCardPresent

Tells whether a card is present in this slot

Signature
boolean isCardPresent();
Return value
true if a card is present, or false.
openLogicalChannel

Opens the APDU Connection to a card application, using a logical channel chosen by the system.

Signature
PendingOperation openLogicalChannel(in OpenSuccessCallback successCallback, in ErrorCallback errorCallback, in DOMString aid);

Errors that can be returned in the ErrorCallback: SecurityError PERMISSION_DENIED_ERROR when access is denied by the security policy. DeviceAPIError IO_ERROR if the communication with the slot fails DeviceAPIError INVALID_ARGUMENT_ERROR if an invalid aid is passed DeviceAPIError PENDING_OPERATION_ERROR if another Open APDU operation is being processed APDUError CHANNEL_OPEN_ERROR if the channel is already open

Parameters
  • successCallback: Callback issued when the opening is correctly finished.
  • errorCallback: Callback issued if an error occurs during the opening.
  • aid: the application identifier of the application (e.g. "a0 00 00 00 62 03 01 0c 02 01").
Return value
PendingOperation enabling the requester to cancel this request.
API features
http://bondi.omtp.org/api/1.5/apdu.openLogicalChannel
openDefaultChannel

Opens the APDU Connection to a card in a slot using the default logical channel if available.

Signature
PendingOperation openDefaultChannel(in SuccessCallback successCallback, in ErrorCallback errorCallback);

Errors that can be returned in the ErrorCallback: SecurityError PERMISSION_DENIED_ERROR when access is denied by the security policy. DeviceAPIError IO_ERROR if the communication with the slot fails DeviceAPIError PENDING_OPERATION_ERROR if another Open APDU operation is being processed APDUError CHANNEL_OPEN_ERROR if the channel is already open

Parameters
  • successCallback: Callback issued when the opening is correctly finished.
  • errorCallback: Callback issued if an error occurs during the opening.
Return value
PendingOperation enabling the requester to cancel this request.
API features
http://bondi.omtp.org/api/1.5/apdu.openDefaultChannel
close

Closes the APDU Connection

Signature
void close();

Closes the APDU Connection.

Exceptions
  • DeviceAPIError:

    IO_ERROR if the communication with the slot fails

    PENDING_OPERATION_ERROR if an Open APDU operation is being processed

  • APDUError:

    CHANNEL_NOT_OPEN_ERROR if the channel is not open

GetAnswerToReset

Get Answer To Reset

Signature
ByteArray GetAnswerToReset();

Get Answer To Reset.

Return value
ATR if successful
transmit

Sends an APDU command

Signature
PendingOperation transmit(in TransmitSuccessCallback successCallback, in ErrorCallback errorCallback, in Byte Class, in Byte Instruction, in Byte P1, in Byte P2, in unsigned short Lc, in ByteArray message, in unsigned short Le);

Sends the APDU command to the card. When the card sends its response APDU, the successCallback is invoked containing the response as another byte array.

Errors that can be returned in the ErrorCallback: DeviceAPIError IO_ERROR if the communication with the slot fails DeviceAPIError INVALID_ARGUMENT_ERROR if any of the parameters is not valid DeviceAPIError PENDING_OPERATION_ERROR if another open or transmit operation is being processed APDUError CHANNEL_NOT_OPEN_ERROR if the channel is not open

Parameters
  • successCallback: Callback issued when the operation is correctly finished.
  • errorCallback: Callback issued if an error occurs during the operation.
  • Class: Class of the APDU command as defined in ISO 7816-4
  • Instruction: Command Instruction as defined in ISO 7816-4
  • P1: First Parameter of the APDU command as defined in ISO 7816-4
  • P2: Second Parameter of the APDU command as defined in ISO 7816-4
  • Lc: Length of the APDU message
  • message: APDU message data to sent
  • Le: Length of the expected answer
Return value
PendingOperation enabling the requester to cancel this request.
API features
http://bondi.omtp.org/api/1.5/apdu.transmit

3.6. APDUSlot

Definition of a card or secure element Slot. 

        interface APDUSlot {

                readonly attribute short id;

                readonly attribute DOMString description;
        };

Attributes

readonly short id

the numerical identifier of the slot. Used internally only.

readonly DOMString description

a human-readable description of the slot (e.g. "(U)SIM Slot". May be displayed to the user in a list so he can select which slot to use.