Smart Card Shell

• • Home
• • GPError
  • GPSystem
  • ByteString
  • ByteBuffer
  • TLV
  • TLVList
  • Card
  • Atr
  • Key
  • Crypto
  • Application
  • GPApplication
  • GPSecDomain
• • ASN1
  • CardFile
  • IsoSecureChannel
  • ApplFactory
  • GPXML
  • JsScript
  • CardSim
• • X509
  • CRL
  • KeyStore
  • Signed CMS
  • Enveloped CMS
  • CMS Generator
  • XMLSignature
  • OCSPQuery
  • LDAP
  • SOAP
  • URLConnection
• • PKCS11Provider
  • PKCS11Session
  • PKCS11Object
• • OutlineNode
  • Dialog
  • Task
• • Tools
  • Modules
• • OpenSCDP

Application - Reference Documentation

An instance of the Application class represents an application on a smart card.

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

Index of Methods

• Application() constructor
• run()
• select()
• sendApdu()

Properties

Type	Name	Description
ByteString	aid	Application identifier for this application.
Card	card	Card object associated with application.
Card	crypto	Crypto object associated with application.
Array	data[]	Associative array of data elements.
Array	key[]	Associative array of keys.
Object	profile	Deserialized application profile.

Constructor

Prototype

Application(String profile)

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

Description

Create an Application 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

Type	Name	Description
String	profile	Name of file containing Global Platform Application profile. The file name will be mapped to the file system of the runtime environment.
ByteString	aid	Application identifier for application.
Card	card	Card object to associate Application with or null if none defined.
Crypto	crypto	Crypto object to associate Application with.
Object	dataMapper	Data mapper object to be used for external data elements or null if none defined.

Exceptions

Name	Value	Description
GPError	GPError.INVALID_ARGUMENTS	Too many arguments given
GPError	GPError.INVALID_TYPE	On or more arguments are not of the expected type

Example

var application = new Application("profiles/ap_sample.xml");

assert(application != 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

Type	Name	Description
String	scriptName	Name of script fragment to execute.

Return

Void	The 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 method invocation

Example

// application.run("Get Status");
application.run("UnitA1 GPError");
application.run("UnitA2 GPSystem getVersion");
application.run("UnitA3 ByteString constructor fuction");
application.run("UnitA4 ByteString byteAt() method");
application.run("UnitA5 ByteString pad() method");
application.run("UnitA6 ByteString toString() method");
// application.run("IntegrationB4 GPApplication Properties");
// application.run("IntegrationB5 DES Key get Method");
// application.run("IntegrationB6 RSA Key get Methods");
// application.run("IntegrationB7 GPApplication Key Profile Creation");
// application.run("IntegrationB9 Crypto Method Changes");
// application.run("IntegrationB22 GPApplication putKey");
// application.run("IntegrationB24 GPApplication select");
// application.run("IntegrationB30 DES Key set Methods");
// application.run("IntegrationB31 RSA Key set Methods");
application.run("IntegrationB32 DataElement TLV L16");
application.run("IntegrationB33 TLV L16 constructor");
// application.run("IntegrationB34 TLVList L16 constructor");
// application.run("IntegrationB35 GPApplication APDU Wrap");
// application.run("Select only");

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

Type	Name	Description
Boolean	next	Used to control parameter P1 in the select command. True will select next application with matching AID. Default is false.
Boolean	noData	Ignore data returned from card. Default is false.
Number[]	sw	Array of acceptable SW1/SW2 response codes.

Return

ByteString

Data returned from card in response to select.

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 method invocation

Example

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

var application = new Application(
            "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

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

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

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