# Smart Card Shell

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

# 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 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 - 2024 CardContact Systems GmbH , Minden, Germany