Smart Card Shell

CardFile - Reference Documentation

Class implementing support for ISO7816-4 elementary and dedicated files on an ICC

Objects created using this class represent a file on the ICC. Each file has an associated absolute path, that uniquely identifies the file in the hierarchical file system of the ICC. The path is constructed from file identifiers and/or file names. File identifier are 16 bit hexadecimal value prefixed by a ':'. File names are hexadecimal strings prefixed with '#'. They usually contain the Application Identifier (AID) assigned to an application dedicated file or an applet.

The class provided for two variant of the constructor. The first variant requires a card object to bind the file to a specific card activated in a reader. This is quite typically the MF (":3F00"), an application DF or an applet. Subsequent instantiations of CardFile objects shall use the second variant of the CardFile constructor, which takes a parent object as first argument. This second variant accepts relative paths, which are then evalutated relative to the parent CardFile object.

When an application is selected using an AID, then the CardFile object may have the MF as parent. This will however not construct an invalid path ":3F00#A00000270101", but allocate a new CardFile objects that inherits the credentials from the MF. This construct is suitable, if credentials from the MF level are valid in subordinate DF as well.

Short file identifier are supported as 1 byte file identifier. Specify a 8 bit hexadecimal value rather than the 16 bit hexadecimal file id. ":3F00:12" for example refers to a file in the MF with short file identifier 18.

Index of Methods

Constants

Type Name Description
Number READ READ access mode in setCredential().
Number UPDATE UPDATE access mode in setCredential().
Number APPEND APPEND access mode in setCredential().
Number SELECT SELECT access mode in setCredential().
Number CREATE CREATE access mode in setCredential().
Number DELETE DELETE access mode in setCredential().
Number ACTIVATE ACTIVATE access mode in setCredential().
Number DEACTIVATE DEACTIVATE access mode in setCredential().
Number ALL All access modes or all usage qualifier in setCredential()

Constructor

Prototype

CardFile(Card card, String path)

CardFile(CardFile parent, String path)

Description

Obtain access to an existing file on an ICC.

Arguments

Type Name Description
Card card Card object to operate on
String path Path to object
CardFile parent Parent CardFile object used to share session

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.OBJECT_NOT_FOUND File not found

Example


card = new Card(_scsh3.reader);

root = new CardFile(card, ":3F00");
print(root);
print(root.getFCPBytes());

// Select EF_DIR with file identifier 2F00
efdir = new CardFile(root, ":2F00");
print(efdir);
print(efdir.getFCPBytes());

// Select EF_DIR with short file identifier 1E (dec. 30)
efdir = new CardFile(root, ":1E");
print(efdir);
print(efdir.getFCPBytes());

df = new CardFile(card, "#D040000017010101");
print(df);
print(df.getFCPBytes());

efsvpd = new CardFile(df, ":EF01");
print(efsvpd);
print(efsvpd.getFCPBytes());

df = new CardFile(card, ":3F00:3F01");
print(df);
print(df.getFCPBytes());

efsvpd = new CardFile(df, ":EF01");
print(efsvpd);
print(efsvpd.getFCPBytes());

getFCPBytes()

Prototype

ByteString getFCPBytes()

Description

Get the bytes returned as File Control Parameter (FCP) in response to the select file command APDU.

This method can be used to ensure, that the object on the ICC is selected.

This method is not available for files refered to by a short file identifier. It will return the FCP of the directory instead.

Return

ByteString Header returned by the ICC

Exceptions

Name Value Description
GPError GPError.INVALID_ARGUMENTS Too many arguments in call
GPError GPError.CARD_COMM_ERROR An error occured while talking to the ICC

Example


efsvpd = new CardFile(card, "#D040000017010101:EF01");

fcp = efsvpd.getFCPBytes();
print(fcp.toString(HEX));
assert(fcp);

getFileID()

Prototype

Number getFileID()

Description

Return the file identifier as indicated in the file control parameter (FCP)

This method is not available for files refered to by a short file identifier

Return

Number File identifier

Exceptions

Name Value Description
GPError GPError.INVALID_ARGUMENTS Too many arguments in call
GPError GPError.CARD_COMM_ERROR An error occured while talking to the ICC

Example


ef = new CardFile(card, ":3F00:2F00");

fid = ef.getFileID();
assert(typeof(fid) == "number");
assert(fid == 0x2F00);

isDirectory()

Prototype

Boolean isDirectory()

Description

Use file control parameter to determine if the file is a dedicated file

This method is not available for files refered to by a short file identifier

Return

Boolean True, if file is dedicated file

Exceptions

Name Value Description
GPError GPError.INVALID_ARGUMENTS Too many arguments in call
GPError GPError.CARD_COMM_ERROR An error occured while talking to the ICC

Example


df = new CardFile(card, ":3F00");
assert(df.isDirectory());
ef = new CardFile(df, ":2F00");
assert(!ef.isDirectory());

isTransparent()

Prototype

Boolean isTransparent()

Description

Use file control parameter to determine if the file is a transparent elementary file

This method is not available for files refered to by a short file identifier

Return

Boolean True, if file is a transparent elementary file

Exceptions

Name Value Description
GPError GPError.INVALID_ARGUMENTS Too many arguments in call
GPError GPError.CARD_COMM_ERROR An error occured while talking to the ICC

Example


ef = new CardFile(card, "#D040000017010101:EF01");
assert(ef.isTransparent());

ef = new CardFile(card, ":3F00:2F00");
assert(!ef.isTransparent());

isCyclic()

Prototype

Boolean isCyclic()

Description

Use file control parameter to determine if the file is a cyclic elementary file

This method is not available for files refered to by a short file identifier

Return

Boolean True, if file is a cyclic linear elementary file

Exceptions

Name Value Description
GPError GPError.INVALID_ARGUMENTS Too many arguments in call
GPError GPError.CARD_COMM_ERROR An error occured while talking to the ICC

Example


ef = new CardFile(card, ":3F00:2F00");
assert(!ef.isCyclic());

getLength()

Prototype

Number getLength()

Description

Use file control parameter to determine length of the file

This method is not available for files refered to by a short file identifier

Return

Number Length in byte

Exceptions

Name Value Description
GPError GPError.INVALID_ARGUMENTS Too many arguments in call
GPError GPError.CARD_COMM_ERROR An error occured while talking to the ICC

Example


ef = new CardFile(card, "#D040000017010101:EF01");
len = ef.getLength();
assert(typeof(len) == "number");
assert((len == 550) || (len == 12));

ef = new CardFile(card, ":3F00:2F00");
len = ef.getLength();
assert((len == 200) || (len == 800));

getRecordSize()

Prototype

Number getRecordSize()

Description

Use file control parameter to determine maximum size of a record

This method is not available for files refered to by a short file identifier

Return

Number Maximum size of record

Exceptions

Name Value Description
GPError GPError.INVALID_ARGUMENTS Too many arguments in call
GPError GPError.CARD_COMM_ERROR An error occured while talking to the ICC

Example


ef = new CardFile(card, ":3F00:2F00");
assert(typeof(ef.getRecordSize()) == "number");
assert(ef.getRecordSize() > 0);

exists()

Prototype

Boolean exists(String file)

Description

Check if file exists in dedicated file

This method is not available for files refered to by a short file identifier

Return

Boolean True, if the file exists

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


root = new CardFile(card, ":3F00");
assert(root.exists(":2F00"));
assert(!root.exists(":2F77"));

readBinary()

Prototype

ByteString readBinary()

ByteString readBinary(Number offset)

ByteString readBinary(Number offset, Number length)

Description

Read content of transparent EF

Arguments

Type Name Description
Number offset Zero based offset at which data should be read. Default is 0
Number length Number of bytes to be read. Default is all

Return

ByteString Data read from EF

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
GPError GPError.INVALID_USAGE The card service layer reported an error
GPError GPError.CARD_COMM_ERROR The card terminal layer reported an error

Example


// Using a file identifier
efsvpd = new CardFile(card, "#D040000017010101:EF01");

svpd = efsvpd.readBinary();

print(svpd);

// Using a short file identifier
efsvpd = new CardFile(card, "#D040000017010101:01");

svpd = efsvpd.readBinary();

print(svpd);

readRecord()

Prototype

ByteString readRecord(Number record)

Description

Read record from linear file

Arguments

Type Name Description
Number record Record number

Return

ByteString Record read from linear EF

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
GPError GPError.INVALID_USAGE The card service layer reported an error
GPError GPError.CARD_COMM_ERROR The card terminal layer reported an error

Example


// Using a file identifier
efdir = new CardFile(card, ":3F00:2F00");

dir = efdir.readRecord(1);

print(dir);

// Using a short file identifier
efdir = new CardFile(card, ":3F00:1E");

dir = efdir.readRecord(1);

print(dir);

updateBinary()

Prototype

updateBinary(Number offset, ByteString data)

Description

Write data to transparent file at offset.

A method writeBinary() is provided for backward compatibility with scripts written before version 3.4. Please refrain from use.

Arguments

Type Name Description
Number offset Zero based offset in transparent elementary file
ByteString data Date to be written

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
GPError GPError.INVALID_USAGE The card service layer reported an error
GPError GPError.CARD_COMM_ERROR The card terminal layer reported an error

Example


// Using a file identifier
efsvpb = new CardFile(card, "#D040000017010101:EF03");

efsvpb.updateBinary(0, new ByteString("Hello World", ASCII));

efsvpb = new CardFile(card, "#D040000017010101:03");

efsvpb.updateBinary(0, new ByteString("Hello World", ASCII));

updateRecord()

Prototype

updateRecord(Number record, ByteString data)

Description

Write record to linear file.

A method writeRecord() is provided for backward compatibility with scripts written before version 3.4. Please refrain from use.

Arguments

Type Name Description
Number record Record number starting at 1
ByteString data Date to be written

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
GPError GPError.INVALID_USAGE The card service layer reported an error
GPError GPError.CARD_COMM_ERROR The card terminal layer reported an error

Example


// Using a file identifier
efdir = new CardFile(card, ":3F00:2F00");
efdir.updateRecord(2, 
  new ByteString("611C4F08D040000017001001500A53565369676E61747572530454312E30", HEX));

appendRecord()

Prototype

appendRecord(ByteString data)

Description

Append a record with data to linear file.

Arguments

Type Name Description
ByteString data Date to be written to appended record

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
GPError GPError.INVALID_USAGE The card service layer reported an error
GPError GPError.CARD_COMM_ERROR The card terminal layer reported an error

Example


// Using a file identifier
efdir = new CardFile(card, ":3F00:2F00");
efdir.appendRecord(
  new ByteString("611C4F08D040000017001001500A53565369676E61747572530454312E30", HEX));

performCHV()

Prototype

performCHV(Boolean global, Number reference)

performCHV(Boolean global, Number reference, ByteString value)

Description

Perform cardholder verification.

Arguments

Type Name Description
Boolean global True, if global reference data is to be used. False, if reference data resides in the directory of the CardFile object.
Number reference Reference to data to be used for CHV.
ByteString value Cardholder verification value (e.g. PIN or PASSWORD)

Return

Boolean True, if cardholder verification is successful.

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
GPError GPError.DEVICE_ERROR An card terminal error occured or the CHV was aborted

Example


// Allocate a cardfile object
var root = new CardFile(card, ":3F00");

// Perform cardholder verification (e.g. PIN entry) for global reference data 1
root.performCHV(true, 1);

// Perform cardholder verification procedure using given data for global reference data 1
root.performCHV(true, 1, new ByteString("241122FFFFFFFFFF", HEX));

// Perform cardholder verification (e.g. PIN entry) for local reference data 1 (Signature-PIN)
var dfssig = new CardFile(card, "#D040000017001201");
dfssig.performCHV(false, 1);

setCredential()

Prototype

setCredential(Number accessMode, Number usageQualifier, Object credential)

Description

Provide an object that contains the credential required to access the file in the specified mode.

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 transformation is applied, if the file access operation (e.g. readBinary()) matches the access mode.

The access mode can be defined by or'ing the constants CardFile.READ, CardFile.UPDATE or CardFile.APPEND. Use CardFile.ALL as a combination of the above.

The usage qualifier 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.

Usage qualifier are stored per access mode. Use multiple calls to setCredential(), if different access modes require different usage qualifier.

Subsequent calls to this method will overwrite the previous credential for an access mode.

If the CardFile object was created as the child of a parent DF (the second constructor option), then all credentials are stored with the top-most parent CardFile in the hierarchy. Credentials are stored based on the file's path on the card, so subsequent CardFile objects with the same file identifier will inherit a once defined credential. If this is not desired, then the CardFile object must be created without a parent dependency.

Arguments

Type Name Description
Number accessMode Bitwise or'ing of CardFile.READ, CardFile.UPDATE or CardFile.APPEND to specify the access mode for which this credential is applicable.
Number usageQualifier Bitwise or'ing of Card.CPRO, Card.CENC, Card.RPRO or Card.RENC. Card.ALL is a combination of all.
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);
}


// Allocate a secure channel credential
var sc = new SecureChannelCredential();

// Allocate a cardfile object
var efsvpd = new CardFile(card, "#D040000017010101:EF01");
efsvpd.setCredential(CardFile.READ, Card.ALL, sc);
svpd = efsvpd.readBinary();

createFile()

Prototype

Void createFile(ByteString fcp)

Void createFile(ByteString fcp, Number fileDescriptorByte)

Description

Create a new file object on the card subordinate to the dedicated file for which this method is called.

The data passed in the method invocation must match the data supplied to the card operating system in the CREATE FILE APDU.

The optional parameter fileDescriptorByte can be used to set P1 of the command APDU to a specific value as defined in ISO 7816-9.

The command APDU will be send using secure messaging, if a credential is set for the object that has the access mode CardFile.CREATE defined.

Arguments

Type Name Description
ByteString fcp File control parameter defining the properties of the new card object. Format and encoding depends on the card operation system.
Number fileDescriptorByte File descriptor byte passed as P1 in the command APDU. 0 if missing.

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 call
GPError GPError.CARD_COMM_ERROR An error occured while talking to the ICC
GPError GPError.INVALID_USAGE A card service error occured
GPError GPError.DEVICE_ERROR A card terminal error occured

Example


// Create an EF_DIR on a Starcos 3.1 card
var fcp = new ByteString("621A8205044100500F83022F00850203208801F08A0105A1038B0102", HEX);

var mf = new CardFile(card, ":3F00");
mf.createFile(fcp);

deleteFile()

Prototype

Void deleteFile()

Void deleteFile(String fileIdentifier)

Void deleteFile(String fileIdentifier, boolean isDF)

Description

Delete a file object from the card.

If this method is called without parameters, then the card object represented by the CardFile object is deleted (DELETE SELF).

If this method is called with a fileIdentifier argument, then a file objects within the dedicated file represented by the CardFile object is deleted.

By default, the method assumes that the subordinate file is a EF. This can be overwritten by setting the isDF argument to true.

The command APDU will be send using secure messaging, if a credential is set for the object that has the access mode CardFile.DELETE defined.

Arguments

Type Name Description
String fileIdentifier File identifier (FID or AID).
Boolean isDF Indicator, that the file to be deleted is a DF. Default is false.

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 call
GPError GPError.INVALID_DATA The fileIdentifier argument must be a single id, not a path.
GPError GPError.CARD_COMM_ERROR An error occured while talking to the ICC
GPError GPError.INVALID_USAGE A card service error occured
GPError GPError.DEVICE_ERROR An card terminal error occured or the CHV was aborted

Example


// Delete EF_DIR in MF
var mf = new CardFile(card, ":3F00");
mf.deleteFile(":2F00");

// Delete DF using DELETE SELF method
var df = new CardFile(card, "#A0000000041234");
df.deleteFile();

// Delete DF from MF
mf.deleteFile(":DF01", true);

activateFile()

Prototype

Void activateFile()

Description

Activate the file object on the card represented by this CardFile object using the ACTIVATE FILE command APDU defined by ISO 7816-9.

The command APDU will be send using secure messaging, if a credential is set for the object that has the access mode CardFile.ACTIVATE defined.

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 call
GPError GPError.CARD_COMM_ERROR An error occured while talking to the ICC
GPError GPError.INVALID_USAGE A card service error occured
GPError GPError.DEVICE_ERROR An card terminal error occured or the CHV was aborted

Example


// Activate DF
var df = new CardFile(card, "#A0000000041234");
df.activate();

deactivateFile()

Prototype

Void deactivateFile()

Description

De-activate the file object on the card represented by this CardFile object using the DEACTIVATE FILE command APDU defined by ISO 7816-9.

The command APDU will be send using secure messaging, if a credential is set for the object that has the access mode CardFile.DEACTIVATE defined.

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 call
GPError GPError.CARD_COMM_ERROR An error occured while talking to the ICC
GPError GPError.INVALID_USAGE A card service error occured
GPError GPError.DEVICE_ERROR An card terminal error occured or the CHV was aborted

Example


// De-activate DF
var df = new CardFile(card, "#A0000000041234");
df.deactivate();

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.

This methods works similar to Card.sendApdu(), but also ensures, that the object for which the method is called is selected before the APDU is transmitted.

The method updates the fields SW, SW1, SW2 and SWMSG 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. 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


// See Card.sendApdu() for an 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.

This methods works similar to Card.sendSecMsgApdu() but uses credentials set for the object for which this method is called.

This method also ensures, that the object for which the method is called is selected before the APDU is transmitted.

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. APDUs send with this method will be transformed using the credential set for the CardFile.SELECT access mode.

The method updates the fields SW, SW1, SW2 and SWMSG 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 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. 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


// See Card.sendApdu() for an example

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