SSE4E

Card - Reference Documentation

Class to allow access to ICC

Index of Methods

• Card() constructor
• reset()
• sendApdu()
• plainApdu()
• setCredential()
• sendSecMsgApdu()
• close()

Constants

Properties

Constructor

Prototype

Card()

Card(String reader)

Card(String reader, String cardProfileName)

Description

Create an object representing an ICC in a reader.

The name of the card terminal can be passed as argument reader. If the card reader supports multiple slots, then the slot number can be specified by appending a hash '#' and the slot number. Slot numbers start at 1, 0 means any slot and is the default value (e.g. "MCT#2" selects the card reader "MCT" and the card in slot 2).

Arguments

Exceptions

Example

card = new Card();
assert(card instanceof Card);

card = new Card("");
assert(card instanceof Card);

card = new Card(_scsh3.reader);
assert(card instanceof Card);

card = new Card("", "profiles/cp_jcop41.xml");
assert(card instanceof Card);

dumpxml(card.profile, "");

reset()

Prototype

Atr reset(Number resetMode)

Description

Arguments

Return

Exceptions

Example

card = new Card();
atr = card.reset(Card.RESET_COLD);
print("Format Byte     : " + atr.formatByte.toString(16));
print("Interface Bytes : " + atr.interfaceBytes);
print("Historical Bytes: " + atr.historicalBytes);
print("Check Bytes     : " + atr.tckByte.toString(16));
print(atr);

sendApdu()

Prototype

ByteString sendApdu (Number cla, Number ins, Number p1, Number p2)

ByteString sendApdu (Number cla, Number ins, Number p1, Number p2, Number[] sw)

ByteString sendApdu (Number cla, Number ins, Number p1, Number p2, ByteString data)

ByteString sendApdu (Number cla, Number ins, Number p1, Number p2, ByteString data, Number[] sw)

ByteString sendApdu (Number cla, Number ins, Number p1, Number p2, Number le)

ByteString sendApdu (Number cla, Number ins, Number p1, Number p2, Number le, Number[] sw)

ByteString sendApdu (Number cla, Number ins, Number p1, Number p2, ByteString data, Number le)

ByteString sendApdu (Number cla, Number ins, Number p1, Number p2, ByteString data, Number le, Number[] sw)

Description

Transmit a Command-APDU to the ICC and receive the Response-APDU.

The method updates the fields SW, SW1, SW2 and response with the values received from the ICC.

An array of valid return codes can be passed as argument sw. If the SW1/SW2 from the ICC does not match with one of the entries in the array, then an GPError.CARD_COMM_ERROR exception is raised.

The method supports ISO7816-4 extended format. This is automatically used, if the length of the data argument exceeds 255 or if the argument le exceeds 256.

Arguments

Return

Exceptions

Example

// Case 1: 0022F3A4 - MANAGE SE

resp = card.sendApdu(0x00, 0x22, 0xF3, 0xA4);
print(card.SW.toString(16) + " - " + resp);

// Must return ByteString, null or undefined ?
assert(card.SW == 0x9000);
assert(card.SW1 == 0x90);
assert(card.SW2 == 0x00);

resp = card.sendApdu(0x00, 0x22, 0xF3, 0xA4, [0x9000]);
// Must return ByteString, null or undefined ?


// Case 2: 00B201F400 - READ RECORD from EF_DIR

resp = card.sendApdu(0x00, 0xB2, 0x01, 0xF4, 0);
print(card.SW.toString(16) + " - " + resp);

assert(resp.length > 0);
assert(card.SW == 0x9000);
assert(card.response.equals(resp));

resp = card.sendApdu(0x00, 0xB2, 0x01, 0xF4, 0, [0x9000]);
assert(resp.length > 0);


// Case 3: 002A90A008 - HASH

resp = card.sendApdu(0x00, 0x2A, 0x90, 0xA0, new ByteString("9000800431323334", HEX));
print(card.SW.toString(16) + " - " + resp);

assert(card.SW == 0x9000);

resp = card.sendApdu(0x00, 0x2A, 0x90, 0xA0, new ByteString("9000800431323334", HEX),[0x9000]);


// Case 4: 00A40204022F0000 - SELECT EF_DIR

resp = card.sendApdu(0x00, 0xA4, 0x02, 0x04, new ByteString("2F00", HEX), 0);
print(card.SW.toString(16) + " - " + resp);

assert(card.SW == 0x9000);
assert(resp.length > 0);

resp = card.sendApdu(0x00, 0xA4, 0x02, 0x04, new ByteString("2F00", HEX), 0, [0x9000]);
assert(resp.length > 0);

plainApdu()

Prototype

ByteString sendApdu (ByteString apdu)

ByteString sendApdu (ByteString apdu, Number[] sw)

ByteString sendApdu (ByteString apdu, Number[] sw, Number usageQualifier)

Description

Transmit a Command-APDU to the ICC and receive the Response-APDU.

The method updates the fields SW, SW1, SW2 and response with the values received from the ICC.

An array of valid return codes can be passed as argument sw. If the SW1/SW2 from the ICC does not match with one of the entries in the array, then an GPError.CARD_COMM_ERROR exception is raised.

This method is an extension to the Global Platform Scripting specification.

Arguments

Return

Exceptions

Example

// Case 1: 0022F3A4 - MANAGE SE

resp = card.plainApdu(new ByteString("0022F3A4", HEX));
print(card.SW.toString(16) + " - " + resp);

// Must return ByteString, null or undefined ?
assert(card.SW == 0x9000);
assert(card.SW1 == 0x90);
assert(card.SW2 == 0x00);

resp = card.plainApdu(new ByteString("0022F3A4", HEX), [0x9000]);
// Must return ByteString, null or undefined ?


// Case 2: 00B201F400 - READ RECORD from EF_DIR

resp = card.plainApdu(new ByteString("00B201F400", HEX));
print(card.SW.toString(16) + " - " + resp);

assert(resp.length > 0);
assert(card.SW == 0x9000);
assert(card.response.equals(resp));

resp = card.plainApdu(new ByteString("00B201F400", HEX), [0x9000]);
assert(resp.length > 0);


// Case 3: 002A90A008 - HASH

resp = card.plainApdu(new ByteString("002A90A0089000800431323334", HEX));
print(card.SW.toString(16) + " - " + resp);

assert(card.SW == 0x9000);

resp = card.plainApdu(new ByteString("002A90A0089000800431323334", HEX), [0x9000]);


// Case 4: 00A40204022F0000 - SELECT EF_DIR

resp = card.plainApdu(new ByteString("00A40204022F0000", HEX));
print(card.SW.toString(16) + " - " + resp);

assert(card.SW == 0x9000);
assert(resp.length > 0);

resp = card.plainApdu(new ByteString("00A40204022F0000", HEX), [0x9000]);
assert(resp.length > 0);

setCredential()

Prototype

setCredential(Object credential)

Description

Provide an object that contains the credential required to transform the APDU when using sendSecMsgApdu().

Currently only a secure channel credential can be supplied. A secure channel credential is a JavaScript object that supplies a wrap() and optionally an unwrap() method. The wrap() method is called to transform the command-APDU, the unwrap() method is called to transform the response-APDU.

The usage qualifier in the sendSecMsgApdu() determins, which part of the command and response APDU are to be protected and how. Any of the following four options can be combined: MAC protected command APDU (CPRO), encrypted command APDU (CENC), MAC protected response APDU (RPRO) and encrypted response APDU (RENC).

The usage qualifier controls the transformation of command and reponse APDU. It is passed to the wrap() and unwrap() method as the second parameter.

The usage qualifier can be defined by or'ing the constants Card.CPRO, Card.CENC, Card.RPRO or Card.RENC. Use Card.ALL as a combination of the above.

Subsequent calls to this method will overwrite the previous credential.

This method is an extension to the Global Platform Scripting specification.

Arguments

Return

Exceptions

Example

//
// Define SecureChannelCredential class constructor
//
function SecureChannelCredential() {
}

//
// Wrap command-APDU with secure messaging
//
SecureChannelCredential.prototype.wrap = function(apduToWrap, usageQualifier) {
	print("APDU to wrap with usageQualifier " + usageQualifier + " :");
	print(apduToWrap);
	
	// Put secure messaging transformation here
	
	return(apduToWrap);
}


//
// Unwrap response-APDU with secure messaging
//
SecureChannelCredential.prototype.unwrap = function(apduToUnwrap, usageQualifier) {
	print("APDU to unwrap with usageQualifier " + usageQualifier + " :");
	print(apduToUnwrap);
	
	// Put secure messaging transformation here
	
	return(apduToUnwrap);
}

card.reset(Card.RESET_COLD);

// Allocate a secure channel credential
var sc = new SecureChannelCredential();

card.setCredential(sc);

// Allocate a cardfile object

var response = card.sendSecMsgApdu(Card.ALL, 0x00, 0xA4, 0x02, 0x04, new ByteString("2F00", HEX), 0, [0x9000]);
print(response);

sendSecMsgApdu()

Prototype

ByteString sendSecMsgApdu(Number usageQualifier, Number cla, Number ins, Number p1, Number p2)

ByteString sendSecMsgApdu(Number usageQualifier, Number cla, Number ins, Number p1, Number p2, Number[] sw)

ByteString sendSecMsgApdu(Number usageQualifier, Number cla, Number ins, Number p1, Number p2, ByteString data)

ByteString sendSecMsgApdu(Number usageQualifier, Number cla, Number ins, Number p1, Number p2, ByteString data, Number[] sw)

ByteString sendSecMsgApdu(Number usageQualifier, Number cla, Number ins, Number p1, Number p2, Number le)

ByteString sendSecMsgApdu(Number usageQualifier, Number cla, Number ins, Number p1, Number p2, Number le, Number[] sw)

ByteString sendSecMsgApdu(Number usageQualifier, Number cla, Number ins, Number p1, Number p2, ByteString data, Number le)

ByteString sendSecMsgApdu(Number usageQualifier, Number cla, Number ins, Number p1, Number p2, ByteString data, Number le, Number[] sw)

Description

Transmit a Command-APDU to the ICC and receive the Response-APDU.

If a secure channel is set with the setCredential() method, then this credential will be used to tranform the command and response APDU accordingly. During this transformation process, the usageQualifier is passed to the wrapping / unwrapping methods.

The method updates the fields SW, SW1, SW2 and response with the values received from the ICC.

An array of valid return codes can be passed as argument sw. If the SW1/SW2 from the ICC does not match with one of the entries in the array, then an GPError.CARD_COMM_ERROR exception is raised.

The method supports ISO7816-4 extended format. This is automatically used, if the length of the data argument exceeds 255 or if the argument le exceeds 256.

This method is an extension to the Global Platform Scripting specification.

Arguments

Return

Exceptions

Example

// See sendApdu() and setCredential() for an example

close()

Prototype

close()

Description

Release card object, closing communication channel with the card

If close() is not explicitly called for a card object, then the smart card communication channel will be closed during garbage collection at latest

The method is usefull to ensure, that other applications can get access to the card.

Return

Exceptions

Example

card.close();

© Copyright 2003 - 2010 CardContact Software & System Consulting, Minden, Germany