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 resetReturn
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();
© Copyright 2003 - 2013 CardContact Software & System Consulting, Minden, Germany