SSE4E

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

• CardFile() constructor
• getFCPBytes()
• getFileID()
• isDirectory()
• isTransparent()
• isCyclic()
• getLength()
• getRecordSize()
• exists()
• readBinary()
• readRecord()
• updateBinary()
• updateRecord()
• appendRecord()
• performCHV()
• setCredential()
• createFile()
• deleteFile()
• activateFile()
• deactivateFile()
• sendApdu()
• sendSecMsgApdu()

Constants

Constructor

Prototype

CardFile(Card card, String path)

CardFile(CardFile parent, String path)

Description

Arguments

Exceptions

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

Exceptions

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

Exceptions

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

Exceptions

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

Exceptions

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

Exceptions

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

Exceptions

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

Exceptions

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

Exceptions

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

Arguments

Return

Exceptions

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

Arguments

Return

Exceptions

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

Return

Exceptions

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

Return

Exceptions

Example

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

appendRecord()

Prototype

appendRecord(ByteString data)

Description

Arguments

Return

Exceptions

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

Arguments

Return

Exceptions

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

Return

Exceptions

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

Return

Exceptions

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

Return

Exceptions

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

Exceptions

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

Exceptions

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

Return

Exceptions

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

Return

Exceptions

Example

// See Card.sendApdu() for an example

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