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
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 EFArguments
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 fileArguments
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