Scripting Server

GPSecurityDomain - Reference Documentation

An instance of the GPSecurityDomain class represents an application that is a security domain on a smart card.

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

Index of Methods

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

GPSecurityDomain(String profile)

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

Description

Create a GPSecurityDomain 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 card = new Card(_scsh3.reader);
var crypto = new Crypto();
var sdAid = new ByteString("A000000003000000", HEX);

var sd = new GPSecurityDomain("profiles/ap_sample.xml", sdAid, card, crypto);

assert(sd != null);
assert(sd.aid != null);
assert(sd.aid instanceof ByteString);
assert(sd.aid.equals(sdAid));
assert(sd.card != null);
assert(sd.crypto != null);

deleteAID()

Prototype

ByteString deleteAID(ByteString aid)

ByteString deleteAID(ByteString aid, Number[] sw)

Description

Delete application, module or load file stored under given aid using the Global Platform DELETE_FILE APDU.

Arguments

Type Name Description
ByteString aid Application identifier of application, module or load file.
Number[] sw Array of acceptable SW1/SW2 status codes.

Return

ByteString The method returns the data returned by the ICC in response to the DELETE_FILE command.

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
GPError GPError.CARD_COMM_ERROR Communication with the ICC failed
GPError GPError.CARD_INVALID_SW The ICC returned an unexpected status word SW1/SW2

Example


// var applAid = new ByteString("", HEX);
// sd.deleteAID(applAid, [0x9000, 0x6A88] );

installForInstall()

Prototype

ByteString installForInstall(ByteString loadFileAID, ByteString executableModuleAID, ByteString applicationAID, ByteString privileges, ByteString installParam, ByteString installToken)

ByteString installForInstall(ByteString loadFileAID, ByteString executableModuleAID, ByteString applicationAID, ByteString privileges, ByteString installParam, ByteString installToken, Number[] sw)

Description

Create an instance of an application under the given AID using the executable module from the load file as the template.

The optional argument sw allows to define a list of acceptable status word returned by the ICC. If the argument is missing, then 9000 is the only acceptable status word.

Arguments

Type Name Description
ByteString loadFileAID Application identifier of load file.
ByteString executableModuleAID Application identifier of module in load file.
ByteString applicationAID Application identifier for instance to be created.
ByteString privileges Application privileges.
ByteString installParam Installation parameter.
ByteString installToken Install token to authenticate install process or null if not defined.
Number[] sw Array of acceptable SW1/SW2 status codes.

Return

ByteString The method returns the data returned by the ICC in response to the INSTALL command.

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
GPError GPError.CARD_COMM_ERROR Communication with the ICC failed
GPError GPError.CARD_INVALID_SW The ICC returned an unexpected status word SW1/SW2

Example


/*
var loadFileAid = new ByteString("A000000001", HEX);
var moduleAid = new ByteString("A00000000101", HEX);
var applAid = new ByteString("A00000000102", HEX);
var applPrivileges = new ByteString("00", HEX);
var installParam = new ByteString("C900", HEX);

sd.installForInstall(loadFileAid, moduleAid, applAid, applPrivileges, installParam, null);
*/

installForInstallAndSelectable()

Prototype

ByteString installForInstallAndSelectable(ByteString loadFileAID, ByteString executableModuleAID, ByteString applicationAID, ByteString privileges, ByteString installParam, ByteString installToken)

ByteString installForInstallAndSelectable(ByteString loadFileAID, ByteString executableModuleAID, ByteString applicationAID, ByteString privileges, ByteString installParam, ByteString installToken, Number[] sw)

Description

Create an instance of an application under the given AID using the executable module from the load file as the template.

After instantiating the applet, it is selectable with the select command.

The optional argument sw allows to define a list of acceptable status word returned by the ICC. If the argument is missing, then 9000 is the only acceptable status word.

Arguments

Type Name Description
ByteString loadFileAID Application identifier of load file.
ByteString executableModuleAID Application identifier of module in load file.
ByteString applicationAID Application identifier for instance to be created.
ByteString privileges Application privileges.
ByteString installParam Installation parameter.
ByteString installToken Install token to authenticate install process or null if not defined.
Number[] sw Array of acceptable SW1/SW2 status codes.

Return

ByteString The method returns the data returned by the ICC in response to the INSTALL command.

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
GPError GPError.CARD_COMM_ERROR Communication with the ICC failed
GPError GPError.CARD_INVALID_SW The ICC returned an unexpected status word SW1/SW2

Example


/*
var loadFileAid = new ByteString("A000000001", HEX);
var moduleAid = new ByteString("A00000000101", HEX);
var applAid = new ByteString("A00000000102", HEX);
var applPrivileges = new ByteString("00", HEX);
var installParam = new ByteString("C900", HEX);

sd.installForInstallAndSelectable(loadFileAid, moduleAid, applAid, applPrivileges, 
                                  installParam, null);
*/

installForLoad()

Prototype

ByteString installForLoad(ByteString loadFileAID, ByteString securityDomainAID, ByteString loadFileDataBlockHash, ByteString loadParam, ByteString loadToken)

Description

Prepare the download of a load file into the ICC with a subsequent load(), loadByName() or loadWithProfile() method.

The optional argument sw allows to define a list of acceptable status word returned by the ICC. If the argument is missing, then 9000 is the only acceptable status word.

Arguments

Type Name Description
ByteString loadFileAID Application identifier of load file.
ByteString securityDomainAID Application identifier of security domain or null if not used.
ByteString loadFileDataBlockHash Hash of load file data blocks or null if not used.
ByteString loadParam Load parameter or null if not used.
ByteString loadToken Load token to authenticate load process or null if not used.
Number[] sw Array of acceptable SW1/SW2 status codes.

Return

ByteString The method returns the data returned by the ICC in response to the INSTALL command.

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
GPError GPError.CARD_COMM_ERROR Communication with the ICC failed
GPError GPError.CARD_INVALID_SW The ICC returned an unexpected status word SW1/SW2

Example


/*
var loadFileAid = new ByteString("A000000001", HEX);
var sdAid = new ByteString("A000000003000000", HEX);

sd.installForLoad(loadFileAid, sdAid, null, null, null);
*/

loadByName()

Prototype

ByteString loadByName(String capFileName)

ByteString loadByName(ByteString capFileName)

ByteString loadByName(ByteString capFileName, [[aid, dap]])

Description

Read cap file and transfer into GP card using the LOAD command APDU.

Arguments

Type Name Description
String capFileName Name of cap file. Will be mapped to a file name in the runtime environment.
ByteString capFileName Name of cap file as ByteString. Will be mapped to a file name in the runtime environment.
[[ByteString,ByteString]] [[aid,dap]] Pair of application identifier and data block signature - Not yet supported

Return

ByteString Data returned in last LOAD block

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
GPError GPError.OBJECT_NOT_FOUND Cap file not found or invalid cap file structure
GPError GPError.CARD_COMM_ERROR Communication with the ICC failed
GPError GPError.CARD_INVALID_SW The ICC returned an unexpected status word SW1/SW2

Example


// sd.loadByName("musclecard/CardEdge.cap");

openSecureChannel()

Prototype

Number openSecureChannel(Number level)

Number openSecureChannel(Number level, Number version)

Number openSecureChannel(Number level, Number version, Number index) (not supported yet)

Description

Read cap file and transfer into GP card using the LOAD command APDU.

Arguments

Type Name Description
Number level Level of security requested for the secure channel.
Number version Key set version.
Number index Key set version index.

Return

ByteString Level of security selected for the secure channel.

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
GPError GPError.CARD_COMM_ERROR Communication with the ICC failed
GPError GPError.CARD_INVALID_SW The ICC returned an unexpected status word SW1/SW2

Example


var level = sd.openSecureChannel(0x01);
assert(level == 0x01);
assert(sd.secureChannel != null);
assert(sd.secureChannel.state == SC_CLOSE);

var level = sd.openSecureChannel(0x03, 0x02);
assert(level == 0x03);
assert(sd.secureChannel != null);
assert(sd.secureChannel instanceof GPScp02);
assert(sd.secureChannel.state == SC_CLOSE);

var scp02 = sd.secureChannel;

assert(scp02.securityLevel == 0x03);
assert(scp02.hostChallenge == null);
assert(scp02.keyVersion == null);

scp02.initializeUpdate(0x00, 0x00);

assert(scp02.hostChallenge != null);
assert(scp02.hostChallenge instanceof ByteString);
print(scp02.hostChallenge);

assert(scp02.keyVersion != null);
assert(scp02.keyVersion == 0x00);

assert(scp02.cardChallenge != null);
print(scp02.cardChallenge);
assert(scp02.cardCryptogram != null);
print(scp02.cardCryptogram);
assert(scp02.diversificationData != null);
print(scp02.diversificationData);
assert(scp02.sequenceCounter != null);
print(scp02.sequenceCounter);

var masterSENC = new Key("profiles/kp_jcop_default_s-enc.xml");
var masterSMAC = new Key("profiles/kp_jcop_default_s-mac.xml");

/*
var kmc = new Key("profiles/kp_kmc.xml");
   
var derivationData = scp02.diversificationData.right(6);

var derivationParam = derivationData.concat(new ByteString("F001", HEX)).concat(derivationData).concat(new ByteString("0F01", HEX));

var masterSENC = new Key();
crypto.deriveKey(kmc, Crypto.DES_ECB, derivationParam, masterSENC);
print("SC-ENC: " + masterSENC.getComponent(Key.DES));

var derivationParam = derivationData.concat(new ByteString("F002", HEX)).concat(derivationData).concat(new ByteString("0F02", HEX));

var masterSMAC = new Key();
crypto.deriveKey(kmc, Crypto.DES_ECB, derivationParam, masterSMAC);
print("SC-MAC: " + masterSMAC.getComponent(Key.DES));
  
*/
     
var derivationPostfix = scp02.sequenceCounter.concat(new ByteString("000000000000000000000000", HEX));
        
// Derive S-ENC session key
var derivationPrefix = new ByteString("0182", HEX);
var derivationParam = derivationPrefix.concat(derivationPostfix);
        
print("Input to session S-ENC derivation: " + derivationParam);

var sessionSENC = new Key();            
crypto.deriveKey(masterSENC, Crypto.DES_CBC, derivationParam, sessionSENC);
        
        
// Derive S-MAC session key
var derivationPrefix = new ByteString("0101", HEX);
var derivationParam = derivationPrefix.concat(derivationPostfix);
        
print("Input to session S-MAC derivation: " + derivationParam);

var sessionSMAC = new Key();
crypto.deriveKey(masterSMAC, Crypto.DES_CBC, derivationParam, sessionSMAC);
        
scp02.setEncKey(sessionSENC);
scp02.setMacKey(sessionSMAC);
        
scp02.externalAuthenticate(0x03);

var rsp = sd.sendApdu(0x80, 0xCA, 0x00, 0x66, 0x00); // Send GET DATA command
print(rsp);

// AIDs for Smart Card HSM
var loadFileAid = new ByteString("E82B0601040181C31F020101", HEX);
var moduleAid =   new ByteString("E82B0601040181C31F0201", HEX);
var applAid =     new ByteString("E82B0601040181C31F0201", HEX);

// Clean the card
print("Delete old smart card HSM applet instance...");
sd.deleteAID(applAid, [0x9000, 0x6A88, 0x6A80] );
print("Delete old smart card HSM applet load file...");
sd.deleteAID(loadFileAid, [0x9000, 0x6A88, 0x6A80] );

print("InstallForLoad smart card HSM applet...");
sd.installForLoad(loadFileAid, sdAid, null, null, null);
print("Loading smart card HSM applet...");
sd.loadByName("javacard/smartcardhsm.cap");

print("Instantiating smart card HSM applet...");
var applPrivileges = new ByteString("00", HEX);
var installParam = new ByteString("C900", HEX);
sd.installForInstallAndSelectable(loadFileAid, moduleAid, applAid, applPrivileges, installParam, null);


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 security domain 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
GPError GPError.CARD_COMM_ERROR Communication with the ICC failed
GPError GPError.CARD_INVALID_SW The ICC returned an unexpected status word SW1/SW2

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

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