Card - Reference Documentation

Class to allow access to ICC

Index of Methods

Card() constructor
reset()
getATR()
sendApdu()
plainApdu()
getCardService()
setCredential()
clearCredential()
sendSecMsgApdu()
close()
setCardEventListener()
remoteUpdate()
getReaderList()

Constants

Type	Name	Description
Number	T0	T=0 protocol
Number	T1	T=1 protocol
Number	T14	T=14 protocol
Number	OTHER	Other protocol
Number	PICCA
Number	PICCB
Number	RESET_COLD	Perform cold reset
Number	RESET_WARM	Perform warm reset if supported by reader, otherwise cold reset
Number	CPRO	Usage qualifier for MAC protected command-APDU in sendSecMsgApdu()
Number	CENC	Usage qualifier for encrypted command-APDU in sendSecMsgApdu()
Number	RPRO	Usage qualifier for MAC protected response-APDU in sendSecMsgApdu()
Number	RENC	Usage qualifier for encrypted response-APDU in sendSecMsgApdu()
Number	ALL	All access modes or all usage qualifier in sendSecMsgApdu()

Properties

Type	Name	Description
ByteString	response	Last response APDU received from ICC
Number	SW	Last status word SW1/SW2 received from ICC
Number	SW1	Last status byte SW1 received from ICC
Number	SW2	Last status byte SW2 received from ICC
String	SWMSG	Message for SW1/SW2 (Extension to GP)
opencard.core.terminal.CardTerminal	nativeCardTerminal	OCF Card Terminal
String	readerName	Card terminal name
String	maxReaderCAPDU	Command APDU limit by the card terminal (Optional)
String	maxReaderRAPDU	Command APDU limit by the card terminal (Optional)
String	remoteMessage	Message received from server during remote update
Number	remoteMessageId	Message id received from server during remote update

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

Type	Name	Description
`String`	reader	Card terminal name
`String`	cardProfileName	Name of file containing Global Platform card profile

Exceptions

Name	Value	Description
GPError	GPError.ARGUMENTS_MISSING	Too few arguments in call
GPError	GPError.INVALID_ARGUMENTS	Too many arguments in call
GPError	GPError.INVALID_TYPE	Type of argument is invalid for call
GPError	GPError.CARD_CONNECT_FAILED	Establishing a connection to the card fails as the card is not present or mute
GPError	GPError.CARD_COMM_ERROR	A communication error with the ICC occured

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

Perform a cold or warm reset with the ICC.

Arguments

Type	Name	Description
`Number`	resetMode	Reset mode, either Card.RESET_COLD or Card.RESET_WARM.

Return

Atr ATR returned by ICC

Exceptions

Name	Value	Description
GPError	GPError.ARGUMENTS_MISSING	Too few arguments in call
GPError	GPError.INVALID_ARGUMENTS	Too many arguments in call
GPError	GPError.INVALID_TYPE	Argument must be of type Number and either Card.RESET_COLD or Card.RESET_WARM
GPError	GPError.CARD_COMM_ERROR	A communication error with the ICC occured

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);

getATR()

Prototype

Atr getATR()

Description

Return ATR of last reset

Return

Atr ATR returned by ICC

Exceptions

Name	Value	Description
GPError	GPError.INVALID_ARGUMENTS	Too many arguments in call

Example


card = new Card();
card.reset(Card.RESET_COLD);
atr = card.getATR();
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

Type	Name	Description
`Number`	cla	The CLA byte for the Command-APDU
`Number`	ins	The INS byte for the Command-APDU
`Number`	p1	The P1 byte for the Command-APDU
`Number`	p2	The P2 byte for the Command-APDU
`ByteString`	data	The data bytes to be send in the Command-APDU for case 3 or case 4 commands
`Number`	le	The number of bytes expected in the response. 65536 is encoded as '0000' in extended format.
`Number[]`	sw	Array of acceptable SW1/SW2 return codes

Return

ByteString Response APDU received from ICC

Exceptions

Name	Value	Description
GPError	GPError.ARGUMENTS_MISSING	Too few arguments in call
GPError	GPError.INVALID_ARGUMENTS	Too many arguments in call
GPError	GPError.INVALID_TYPE	Type of argument is invalid for call or SW array contain a type other than Number
GPError	GPError.CARD_COMM_ERROR	A communication error with the ICC occured
GPError	GPError.CARD_INVALID_SW	The status word return by the ICC does not match one of the expected result
GPError	GPError.DATA_TOO_LARGE	The data for the command APDU exceeds 65536
GPError	GPError.INVALID_LENGTH	The value given for Le is out of range

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

Type	Name	Description
`ByteString`	apdu	Command-APDU in plain format consisting of CLA\|INS\|P1\|P2\|Lc\|Data\|Le
`Number[]`	sw	Array of acceptable SW1/SW2 return codes
`Number`	usageQualifier	Usage qualifier to be passed to secure messaging transformation

Return

ByteString Response APDU received from ICC

Exceptions

Name	Value	Description
GPError	GPError.ARGUMENTS_MISSING	Too few arguments in call
GPError	GPError.INVALID_ARGUMENTS	Too many arguments in call
GPError	GPError.INVALID_TYPE	Type of argument is invalid for call or SW array contain a type other than Number
GPError	GPError.CARD_COMM_ERROR	A communication error with the ICC occured
GPError	GPError.INVALID_SW	The status word return by the ICC does not match one of the expected result

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);

getCardService()

Prototype

Object getCardService(String className)

Description

Obtain OCF card service for API given in className

Arguments

Type	Name	Description
`String`	className	OCF Card Service class or interface name

Return

Object The native Java class providing the service

Exceptions

Name	Value	Description
GPError	GPError.ARGUMENTS_MISSING	Too few arguments in call
GPError	GPError.INVALID_ARGUMENTS	Too many arguments in call
GPError	GPError.INVALID_TYPE	Type of argument is invalid for call
GPError	GPError.INVALID_DATA	Card service not found

Example


// var cs = card.getCardService("de.cardcontact.opencard.service.smartcardhsm.SmartCardHSMCardService");

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

Type	Name	Description
`Object`	credential	Object to be used as credential.

Return

Method does not return a value

Exceptions

Name	Value	Description
GPError	GPError.ARGUMENTS_MISSING	Too few arguments in call
GPError	GPError.INVALID_ARGUMENTS	Too many arguments in call
GPError	GPError.INVALID_TYPE	Type of argument is invalid for call
GPError	GPError.CARD_COMM_ERROR	An error occured while talking to the ICC

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);

clearCredential()

Prototype

clearCredential()

Description

Clear credential for card service

Return

Method does not return a value

Exceptions

Name	Value	Description
GPError	GPError.INVALID_ARGUMENTS	Too many arguments in call

Example

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 255.

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

Arguments

Type	Name	Description
`Number`	usageQualifier	Usage qualifier for secure messaging transformation. Can be a combination of Card.CPRO, Card.CENC, Card.RPRO, Card.RENC and Card.ALL.
`Number`	cla	The CLA byte for the Command-APDU
`Number`	ins	The INS byte for the Command-APDU
`Number`	p1	The P1 byte for the Command-APDU
`Number`	p2	The P2 byte for the Command-APDU
`ByteString`	data	The data bytes to be send in the Command-APDU for case 3 or case 4 commands
`Number`	le	The number of bytes expected in the response. 255 is encoded as '00' in short format. 65536 is encoded as '0000' in extended format.
`Number[]`	sw	Array of acceptable SW1/SW2 return codes

Return

ByteString Response APDU received from ICC

Exceptions

Name	Value	Description
GPError	GPError.ARGUMENTS_MISSING	Too few arguments in call
GPError	GPError.INVALID_ARGUMENTS	Too many arguments in call
GPError	GPError.INVALID_TYPE	Type of argument is invalid for call or SW array contain a type other than Number
GPError	GPError.CARD_COMM_ERROR	A communication error with the ICC occured
GPError	GPError.CARD_INVALID_SW	The status word return by the ICC does not match one of the expected result
GPError	GPError.DATA_TOO_LARGE	The data for the command APDU exceeds 65536
GPError	GPError.INVALID_LENGTH	The value given for Le is out of range

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

Name	Value	Description
GPError	GPError.INVALID_ARGUMENTS	Too many arguments in call

Example


card.close();

setCardEventListener()

Prototype

setCardEventListener(Object handler)

Description

Static method to register a script object that receives cardInserted and cardRemoved events.

The cardInserted and cardRemoved methods provide the reader name as argument.

The handler must implement both methods.

The cardNotification method is optional and called when the properties remoteMessage and remoteMessageId are updated during remote update processing.

Arguments

Type	Name	Description
`Object`	handler	The event handler

Return

Exceptions

Name	Value	Description
GPError	GPError.INVALID_ARGUMENTS	Too many arguments in call

Example


var handler = {
	cardInserted: function(readerName) {
		print("Card inserted into " + readerName);
	},
	cardRemoved: function(readerName) {
		print("Card removed from " + readerName);
	}
	cardNotification: function(readerName) {
		print("Notification for " + readerName);
	}
}
Card.setCardEventListener(handler);

remoteUpdate()

Prototype

remoteUpdate(String url)

remoteUpdate(String url, String sessionId)

Description

Update the card using the remote update service located at the given URL.

The sessionId can be used to link the card update to a current user session with the server.

Remote notifications are made available in the remoteMessageId and remoteMessage property of the card object.

Arguments

Type	Name	Description
`String`	url	The URL of the remote terminal endpoint on the server
`String`	sessionId	The sessionId used in the session cookie

Return

Exceptions

Name	Value	Description
GPError	GPError.INVALID_ARGUMENTS	Too many arguments in call

Example

getReaderList()

Prototype

Card.getReaderList()

Description

Return the list of attached card readers

Return

String[] The list of reader names

Exceptions

Name	Value	Description
GPError	GPError.INVALID_ARGUMENTS	Too many arguments in call

Example


var list = Card.getReaderList();

Smart Card Shell

Card - Reference Documentation

Index of Methods

Constants

Properties

Constructor

Prototype

Description

Arguments

Exceptions

Example

reset()

Prototype

Description

Arguments

Return

Exceptions

Example

getATR()

Prototype

Description

Return

Exceptions

Example

sendApdu()

Prototype

Description

Arguments

Return

Exceptions

Example

plainApdu()

Prototype

Description

Arguments

Return

Exceptions

Example

getCardService()

Prototype

Description

Arguments

Return

Exceptions

Example

setCredential()

Prototype

Description

Arguments

Return

Exceptions

Example

clearCredential()

Prototype

Description

Return

Exceptions

Example

sendSecMsgApdu()

Prototype

Description

Arguments

Return

Exceptions

Example

close()

Prototype

Description

Return

Exceptions

Example

setCardEventListener()

Prototype

Description

Arguments

Return

Exceptions

Example

remoteUpdate()

Prototype