API Spec Proposal

[jarodium]

Proposal v.0.01 - Base Class

Constants

(taken from Open Smart Card Development Platform (www.openscdp.org)) (Implementation of ISO 7816-4 APDU processing )

APDU.INS_DEACTIVATE = 0x04;

APDU.INS_VERIFY = 0x20;

APDU.INS_MANAGE_SE = 0x22;

APDU.INS_CHANGE_REFERENCE_DATA = 0x24;

APDU.INS_PSO = 0x2A;

APDU.INS_RESET_RETRY_COUNTER = 0x2C;

APDU.INS_ACTIVATE = 0x44;

APDU.INS_GENERATE_KEY_PAIR = 0x46;

APDU.INS_EXTERNAL_AUTHENTICATE = 0x82;

APDU.INS_GET_CHALLENGE = 0x84;

APDU.INS_GENERAL_AUTHENTICATE = 0x86;

APDU.INS_COMPUTE_DIGITAL_SIGN = 0x9E;

APDU.INS_SELECT = 0xA4;

APDU.INS_READBINARY = 0xB0;

APDU.INS_READ_BINARY = 0xB0;

APDU.INS_READ_RECORD = 0xB2;

APDU.INS_VERIFY_CERTIFICATE = 0xBE;

APDU.INS_UPDATE_BINARY = 0xD6;

APDU.INS_TERMINATE = 0xE6;

APDU.SW_OK = 0x9000;

Process completed

APDU.SW_TIMEOUT = 0x6401;

Exec error: Command timeout

APDU.SW_OKMOREDATA = 0x6100;

Process completed, more data available

APDU.SW_WARNING = 0x6200;

Warning: NV-Ram not changed

APDU.SW_WARNING1 = 0x6201;

Warning: NV-Ram not changed 1

APDU.SW_DATAINV = 0x6281;

Warning: Part of data corrupted

APDU.SW_EOF = 0x6282;

Warning: End of file reached

APDU.SW_INVFILE = 0x6283;

Warning: Invalidated file

APDU.SW_INVFORMAT = 0x6284;

Warning: Invalid file control

APDU.SW_WARNINGNVCHG = 0x6300;

Warning: NV-Ram changed

APDU.SW_WARNINGCOUNT = 0x63C0;

Warning: Warning with counter

APDU.SW_WARNING0LEFT = 0x63C0;

Warning: Verify fail, no try left

APDU.SW_WARNING1LEFT = 0x63C1;

Warning: Verify fail, 1 try left

APDU.SW_WARNING2LEFT = 0x63C2;

Warning: Verify fail, 2 tries left

APDU.SW_WARNING3LEFT = 0x63C3;

Warning: Verify fail, 3 tries left

APDU.SW_EXECERR = 0x6400;

Exec error: NV-Ram not changed

APDU.SW_MEMERR = 0x6501;

Exec error: Memory failure

APDU.SW_MEMERRWRITE = 0x6581;

Exec error: Memory failure

APDU.SW_WRONGLENGTH = 0x6700;

Checking error: Wrong length

APDU.SW_CLANOTSUPPORTED = 0x6800;

Checking error: Function in CLA byte not supported

APDU.SW_LCNOTSUPPORTED = 0x6881;

Checking error: Logical channel not supported

APDU.SW_SMNOTSUPPORTED = 0x6882;

Checking error: Secure Messaging not supported

APDU.SW_LASTCMDEXPECTED = 0x6883;

Checking error: Last command of the chain expected

APDU.SW_CHAINNOTSUPPORTED = 0x6884;

Checking error: Command chaining not supported

APDU.SW_COMNOTALLOWED = 0x6900;

Checking error: Command not allowed

APDU.SW_COMINCOMPATIBLE = 0x6981;

Checking error: Command incompatible with file structure

APDU.SW_SECSTATNOTSAT = 0x6982;

Checking error: Security condition not satisfied

APDU.SW_AUTHMETHLOCKED = 0x6983;

Checking error: Authentication method locked

APDU.SW_REFDATANOTUSABLE = 0x6984;

Checking error: Reference data not usable

APDU.SW_CONDOFUSENOTSAT = 0x6985;

Checking error: Condition of use not satisfied

APDU.SW_COMNOTALLOWNOEF = 0x6986;

Checking error: Command not allowed (no current EF)

APDU.SW_SMOBJMISSING = 0x6987;

Checking error: Expected secure messaging object missing

APDU.SW_INCSMDATAOBJECT = 0x6988;

Checking error: Incorrect secure messaging data object

APDU.SW_INVPARA = 0x6A00;

Checking error: Wrong parameter P1-P2

APDU.SW_INVDATA = 0x6A80;

Checking error: Incorrect parameter in the command data field

APDU.SW_FUNCNOTSUPPORTED = 0x6A81;

Checking error: Function not supported

APDU.SW_NOAPPL = 0x6A82;

Checking error: File not found

APDU.SW_FILENOTFOUND = 0x6A82;

Checking error: File not found

APDU.SW_RECORDNOTFOUND = 0x6A83;

Checking error: Record not found

APDU.SW_OUTOFMEMORY = 0x6A84;

Checking error: Not enough memory space in the file

APDU.SW_INVLCTLV = 0x6A85;

Checking error: Nc inconsistent with TLV structure

APDU.SW_INVACC = 0x6A85;

Checking error: Access cond. n/f

APDU.SW_INCP1P2 = 0x6A86;

Checking error: Incorrect P1-P2

APDU.SW_INVLC = 0x6A87;

Checking error: Lc inconsistent with P1-P2

APDU.SW_RDNOTFOUND = 0x6A88;

Checking error: Reference data not found

APDU.SW_FILEEXISTS = 0x6A89;

Checking error: File already exists

APDU.SW_DFNAMEEXISTS = 0x6A8A;

Checking error: DF name already exists

APDU.SW_INVP1P2 = 0x6B00;

Checking error: Wrong parameter P1-P2

APDU.SW_INVLE = 0x6C00;

Checking error: Invalid Le

APDU.SW_INVINS = 0x6D00;

Checking error: Wrong instruction

APDU.SW_INVCLA = 0x6E00;

Checking error: Class not supported

APDU.SW_ACNOTSATISFIED = 0x9804;

Access conditions not satisfied

APDU.SW_NOMORESTORAGE = 0x9210;

No more storage available

APDU.SW_GENERALERROR = 0x6F00;

Checking error: No precise diagnosis

---

Methods/Functions

public setPin(int pin)

Send PIN for validation

Should return true or false

public setPuk(int puk)

Send PUK for validation

Should return true or false

public isVerified(string context)

Check if context is verified.

Should accept PIN or PUK as valid contextes.

Should return true or false

public getRetriesAvail(string context)

Check how many retries are available for a given context

Should accept PIN or PUK as valid contextes.

Should return true or false

public setCardType(string type)

Sets a SmartCard type ( EID, Credit Card, etc... )

public getCardType()

self explaining

Public getCardContents()

Gets all card contents for external storage. This method does imply legal issues for many cases like EID, Credit Cards, but for the sake of caching the data, I have added this method.

public getFS()

Gets the file system structure on the card.

This method should be ajusted for some spec for some CardTypes, since they may have different structs.

private sendAPDU(byte_array buffer)

self explaining

private decode(string data, string from, string to)

self explaining

decode a Hex to Ascii for example

private encode(string data, string from, string to)

self explaining

---

SubClass - EID

This describes an object to interact with a eID card.

Note: This was built on information I can read from the eID using my country's own middleware. Each country object should be able to provide more information, but I think these are most common

Methods/Functions

public setCountry(string country-code, string iso=’DEFAUL_ISO’)

sets a eID card profile for a given country and their card's ISO

public getPkiCert()

gets Public key certificate for Authentication purproses

public getSignCert()

gets Document Signing certificate.

public getName()

gets Name field

public getAddress()

gets Address field

public getID(string context);

get ID from a given context

Allowed values should be : Citizen, VAT, Voter, SocialSec, HealthCare

public getParentage();

get Mother and Father's names.

public getDateofBirth()

get date of birth

public getFingerPrints()

get fingerprint data

public getPhoto()

get photo

public getFreeField

Get the free text field available on the card

public setFreeField

Sets the free text field available on the card

[jarodium]

Hello @santigimeno

Here is a preliminary API spec. This may have to change in the future, but I think as a draft its makes the base class a simple one and I have added an eID child class in the proposal as well, due to my own needs

Regards

[LudovicRousseau]

@jarodium You should first read ISO 7816-4 document.

You can get an idea of what the document contains at http://www.cardwerk.com/smartcards/smartcard_standard_ISO7816-4.aspx and in particular http://www.cardwerk.com/smartcards/smartcard_standard_ISO7816-4_6_basic_interindustry_commands.aspx

[jarodium]

@LudovicRousseau Thank you for pointing me out the spec. I already had taken a look on the Spec, when I was researching APDU. Please refer to #58 in which I "complain" about how hard is for me to build apdu's. I come from a web environment and I am slowy making incursions on the physical world.

The intent of the API, is to have node-pcsclite handle higher level functions, without having developers like myself, bashing around to get APDU's working properly.

I believe node-pcslite will become more powerful in the future and will provide a solid base for IOT and specialized devices.

Best regards

[LudovicRousseau]

The problem is that the APDU commands understood by a smart card is not standard. Each smart card family (EMV card, SIM card, etc.) have its own set of commands and parameters.

[jarodium]

I see, but with the setCardType method one can set one of those types and load their own set of APDU commands. Maybe I should remove the APDU constants and let the methods stay. I think the methods are abstract enough for most card types... What do you think @LudovicRousseau ?

[LudovicRousseau]

I think node-pcsclite is a low level API. You should create another (or more) library to provide a higher level API.

[santigimeno]

I think node-pcsclite is a low level API. You should create another (or more) library to provide a higher level API.

@jarodium I agree with @LudovicRousseau. I see node-pcsclite as a building block to create more complex API's. For example, I created node-pcsclitebecause I needed to operate with SLE4442 cards, but I don't use it directly. I have created a module on top of it with a higher level API specific for this kind of cards: read_main_memory(), read_security_memory(), read_protection_memory(), etc. In fact, I have created multiple modules that implement this interface because different card reader models sometimes access the same kind of cards using different commands.

[jarodium]

Now I have understood the goal of this module. I thought i could evolve into a higher level api, from the current status, but if the goal is to keep it low level, I will no longer pursue this matter, but I will try to build a higher level api, but like I said in #58 , that will consume a lot of my time, since I should do lots of trial and error with the ptEID cards... @santigimeno is it possible to share those modules into repos?

Thank you for your time Regards

[santigimeno]

@jarodium Sorry, at the moment they're private :(

[jarodium]

No problem

[santigimeno]

I'm closing this for the moment. Feel free to reopen though.