SSE4E

Home

GPError
GPSystem
ByteString
ByteBuffer
TLV
TLVList
Card
Atr
Key
Crypto
Application GPApplication GPSecDomain

ASN1
CardFile
IsoSecureChannel
ApplFactory
GPXML
JsScript
CardSim

X509
CRL
KeyStore
CMSSignedData
CMSGenerator
XMLSignature
OCSPQuery
LDAP
SOAP
URLConnection

PKCS11Provider
PKCS11Session
PKCS11Object

OutlineNode

OpenSCDP

GPApplication - Reference Documentation

An instance of the GPApplication class represents an application on a Global Platform card.

Instances of this class are created using the getApplicationInstance() method of the application factory.

Index of Methods

Properties

TypeNameDescription
ByteStringaidApplication identifier for this application.
CardcardCard object associated with application.
CardcryptoCrypto object associated with application.
Arraydata[]Associative array of data elements.
Arraykey[]Associative array of keys.
ObjectprofileDeserialized application profile.

Constructor

Prototype

GPApplication(String profile)

GPApplication(String profile, ByteString aid, Card card, Crypto crypto, Object dataMapper)

Description

Create a GPApplication object and initialize from profile.

This constructor is provided for special development and testing purposes. The preferred method is to use the getApplicationInstance() method of the ApplicationFactory.

Arguments

TypeNameDescription
StringprofileName of file containing Global Platform Application profile. The file name will be mapped to the file system of the runtime environment.
ByteStringaidApplication identifier for application.
CardcardCard object to associate Application with or null if none defined.
CryptocryptoCrypto object to associate Application with.
ObjectdataMapperData mapper object to be used for external data elements or null if none defined.

Exceptions

NameValueDescription
GPErrorGPError.INVALID_ARGUMENTSToo many arguments given
GPErrorGPError.INVALID_TYPEOn or more arguments are not of the expected type

Example


var sd = new GPApplication("profiles/ap_sample.xml");

assert(sd != null);

run()

Prototype

Void run(String scriptName)

Description

Locate and execute script fragment in application profile.

This method does the complete initialization of the key and data properties according to the declarations for this script fragment

Key profiles are obtained from the ApplicationFactory that created the Application object.

External data elements are mapped using the data mapper defined in the constructor or the getApplicationInstance() method of the application factory.

Warning: This method is an extension to the methods defined in the Global Platform Scripting specification. It is provided as development and test aid.

Arguments

TypeNameDescription
StringscriptNameName of script fragment to execute.

Return

VoidThe method does not return a value

Exceptions

NameValueDescription
GPErrorGPError.ARGUMENTS_MISSINGToo few arguments in call
GPErrorGPError.INVALID_ARGUMENTSToo many arguments in call
GPErrorGPError.INVALID_TYPEType of argument is invalid for method invocation

Example



select()

Prototype

ByteString select()

ByteString select(Boolean next, Boolean noData)

ByteString select(Boolean next, Number[] sw)

ByteString select(Boolean next, Boolean noData, Number[] sw)

Description

Select application on ICC.

Arguments

TypeNameDescription
BooleannextUsed to control parameter P1 in the select command. True will select next application with matching AID. Default is false.
BooleannoDataIgnore data returned from card. Default is false.
Number[]swArray of acceptable SW1/SW2 response codes.

Return

ByteStringData returned from card in response to select.

Exceptions

NameValueDescription
GPErrorGPError.ARGUMENTS_MISSINGToo few arguments in call
GPErrorGPError.INVALID_ARGUMENTSToo many arguments in call
GPErrorGPError.INVALID_TYPEType of argument is invalid for method invocation

Example


/*
var aid = new ByteString("D040000017010101", HEX);
var card = new Card(_scsh3.reader);
var crypto = new Crypto();

var application = new GPApplication("profiles/ap_test.xml", aid, card, crypto, new Object());

var resp = application.select();
assert(resp instanceof ByteString);
print(resp);

var resp = application.select(false, false);
assert(resp instanceof ByteString);
print(resp);

var resp = application.select(false, [ 0x9000 ]);
assert(resp instanceof ByteString);
print(resp);

var resp = application.select(true, false, [ 0x6A86 ]);
assert(resp instanceof ByteString);
print(resp);
*/

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 of the associated card object 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

TypeNameDescription
NumberclaThe CLA byte for the Command-APDU
NumberinsThe INS byte for the Command-APDU
Numberp1The P1 byte for the Command-APDU
Numberp2The P2 byte for the Command-APDU
ByteStringdataThe data bytes to be send in the Command-APDU for case 3 or case 4 commands
NumberleThe number of bytes expected in the response. 256 is encoded as '00' in short format. 65536 is encoded as '0000' in extended format.
Number[]swArray of acceptable SW1/SW2 return codes

Return

ByteStringResponse APDU received from ICC

Exceptions

NameValueDescription
GPErrorGPError.ARGUMENTS_MISSINGToo few arguments in call
GPErrorGPError.INVALID_ARGUMENTSToo many arguments in call
GPErrorGPError.INVALID_TYPEType of argument is invalid for call or SW array contain a type other than Number
GPErrorGPError.CARD_COMM_ERRORA communication error with the ICC occured
GPErrorGPError.CARD_INVALID_SWThe status word return by the ICC does not match one of the expected result
GPErrorGPError.DATA_TOO_LARGEThe data for the command APDU exceeds 65536
GPErrorGPError.INVALID_LENGTHThe value given for Le is out of range

Example

/*
// Case 1: 0022F3A4 - MANAGE SE

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

resp = card.sendApdu(0x00, 0x22, 0xF3, 0xA4, [0x9000]);
assert(resp instanceof ByteString);


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

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

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

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


// Case 3: 002A90A008 - HASH

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

assert(card.SW == 0x9000);

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


// Case 4: 00A40204022F0000 - SELECT EF_STATUS

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

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

resp = application.sendApdu(0x00, 0xA4, 0x02, 0x04, new ByteString("EF04", HEX), 0, [0x9000]);
assert(resp.length > 0);
*/