# 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

# TLVList - Reference Documentation

Implementation of a mutable TLV object list.

## Index of Methods

- TLVList() constructor
- index()
- append()
- appendValue()
- appendValueIndex()
- deleteByIndex()
- deleteByTag()
- findIndex()
- find()
- updateValue()
- updateValueIndex()
- toByteString()

## Properties

Type | Name | Description
--- | --- | ---
Number | encodingMode | Encoding mode used for TLV object. One of TLV.EMV, TLV.DGI or TLV.L16
Number | length | The number of TLV objects in the list

## Constructor

### Prototype

TLVList(ByteString tlvStream, Number encoding)

### Description

Create a TLV list object initialized with the tlv objects encoded within the given ByteString object.

For EMV encoding the tag field has a variable length of up to 4 bytes. The length field has a variable length of up to 4 byte. Both fields are encoded as specified as per ASN.1 Basic Encoding Rule (ISO 8825).

For DGI encoding the tag field has a fixed length of two bytes. The length field contains one byte for values between 0 and 254. The length is encoded in three bytes for values between 255 and 65535, with the first byte set to 'FF'.

For L16 encoding the tag field has a fixed length of two bytes. The length field is always two byte long and is encoded in big endian / little endian format.

### Arguments

Type | Name | Description
--- | --- | ---
`ByteString` | tlvStream | ByteString containing the encoded tlv objects
`Number` | encoding | Encoding for tag and length field of the tlv objects in the ByteString. Must be one of TLV.EMV, TLV.DGI or TLV.L16.

### 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_ENCODING | The argument encoding is invalid
GPError | GPError.INVALID_TAG | The tag value is invalid for the selected encoding format
GPError | GPError.DATA_TOO_LARGE | The data supplied for the value fields exceeds the maximum length

### Example

    // EMV
    data = new ByteString("61050102030405620100630A00010203040506070809", HEX);

    // Create a TLV list
    list = new TLVList(data, TLV.EMV);
    assert(list.length == 3);

    // Create a TLV list with "illegal" ASN.1 DER encoding
    list = new TLVList(new ByteString("9f030100", HEX), TLV.EMV);
    assert(list.length == 1);

    // DGI
    data = new ByteString("7F1F05010203040500630A00010203040506070809", HEX);

    list = new TLVList(data, TLV.DGI);
    assert(list.length == 2);

    // L16
    data = new ByteString("7F1F000501020304050063000A00010203040506070809", HEX);

    list = new TLVList(data, TLV.L16);
    assert(list.length == 2);

## index()

### Prototype

TLV index(Number index)

### Description

Returns a TLV object which represents the TLV stored within the TLVList at the given index. The index is zero based.

### Arguments

Type | Name | Description
--- | --- | ---
`Number` | index | Index of the TLV object

### Return

`TLV` | TLV object at the specified index

### Exceptions

Name | Value | Description
--- | --- | ---
GPError | GPError.INVALID_ARGUMENTS | Too many arguments in call
GPError | GPError.ARGUMENTS_MISSING | Too few arguments in call
GPError | GPError.INVALID_TYPE | Type of argument is invalid for call
GPError | GPError.INVALID_INDEX | The specified index is not valid

### Example

    // EMV
    data = new ByteString("610501020304056201008E0A00010203040506070809", HEX);

    // Create a TLV list
    list = new TLVList(data, TLV.EMV);
    assert(list.length == 3);

    tag_61 = list.index(0);
    assert(tag_61 != null);
    assert(tag_61.getTag() == 0x61);

    tag_62 = list.index(1);
    assert(tag_62 != null);
    assert(tag_62.getTag() == 0x62);

    tag_8e = list.index(2);
    assert(tag_8e != null);
    assert(tag_8e.getTag() == 0x8E);

    // Invalid index
    try {
    	tag = list.index(10);
    } catch (e) {
    	assert(e instanceof GPError);
    }

    // Check various EMV length encodings

    data = new ByteString("6181050102030405", HEX);
    list = new TLVList(data, TLV.EMV);
    tlv = list.index(0);
    assert(tlv.getTag() == 0x61);
    assert(tlv.getValue().length == 5);
    assert(tlv.getValue().toString(HEX) == "0102030405");

    data = new ByteString("618200050102030405", HEX);
    list = new TLVList(data, TLV.EMV);
    tlv = list.index(0);
    assert(tlv.getTag() == 0x61);
    assert(tlv.getValue().length == 5);
    assert(tlv.getValue().toString(HEX) == "0102030405");

## append()

### Prototype

append(ByteString tlvStream)

append(Number tag, ByteString value)

append(TLV tlv)

### Description

Appends the specified TLV data to the end of the existing list of TLV objects.

### Arguments

Type | Name | Description
--- | --- | ---
`ByteString` | tlvStream | TLV as a single stream of bytes in a ByteString.
`Number` | tag | Tag to be used to be added to the list.
`ByteString` | value | Value to be used to be added to the List.
`TLV` | tlv | TLV as a TLV object.

### Return

`` |

### Exceptions

Name | Value | Description
--- | --- | ---
GPError | GPError.INVALID_ARGUMENTS | Too many arguments in call
GPError | GPError.ARGUMENTS_MISSING | Too few arguments in call
GPError | GPError.INVALID_TYPE | Type of argument is invalid for call
GPError | GPError.INVALID_INDEX | The specified index is not valid
GPError | GPError.INVALID_TAG | The tag value is invalid for the selected encoding format
GPError | GPError.DATA_TOO_LARGE | The data supplied for the value fields exceeds the maximum length
GPError | GPError.TAG_ALREADY_EXISTS | The tag of the specified TLV object already exists within the TLV list

### Example

    // L16 encoded data
    data = new ByteString("7F1F00050102030405", HEX);

    list = new TLVList(data, TLV.L16);
    assert(list.length == 1);

    // append(Number, Value)
    list.append(0x63, new ByteString("00010203040506070809", HEX));
    assert(list.length == 2);

    // append(ByteString)
    list.append(new ByteString("0061000A00010203040506070809", HEX));
    assert(list.length == 3);

    // append(TLV)
    t = new TLV(0x3221, new ByteString("123456", HEX), TLV.L16);
    list.append(t);
    assert(list.length == 4);

    // try to append an invalid type
    try {
     	list.append("HALLO");
    } catch (e) {
    	assert(e instanceof GPError);
    }

    // try to append a tag with an already existing tag number
    try {
    	t = new TLV(0x3221, new ByteString("123456", HEX), TLV.L16);
    	list.append(t);
    } catch (e) {
    	assert(e instanceof GPError);
    }

## appendValue()

### Prototype

appendValue(Number tag, ByteString value)

### Description

Appends the data to the existing data for the specified tag.

### Arguments

Type | Name | Description
--- | --- | ---
`Number` | tag | Tag to be used to be added to the list.
`ByteString` | value | Value to be used to be added to the List.

### Return

`` |

### Exceptions

Name | Value | Description
--- | --- | ---
GPError | GPError.INVALID_ARGUMENTS | Too many arguments in call
GPError | GPError.ARGUMENTS_MISSING | Too few arguments in call
GPError | GPError.INVALID_TYPE | Type of argument is invalid for call
GPError | GPError.INVALID_TAG | The tag value is invalid for the selected encoding format
GPError | GPError.DATA_TOO_LARGE | The data supplied for the value fields exceeds the maximum length

### Example

    // L16 encoded data
    data = new ByteString("7F1F00050102030405", HEX);

    list = new TLVList(data, TLV.L16);
    assert(list.length == 1);

    // appendValue(Number, Value)
    list.appendValue(0x7F1F, new ByteString("06070809", HEX));

    tlv = list.index(0);
    assert(tlv.getValue().toString(HEX) == "010203040506070809");

## appendValueIndex()

### Prototype

appendValueIndex(Number index, ByteString value)

### Description

Appends the data to the existing data for the specified zero-based index into the TLVStream.

### Arguments

Type | Name | Description
--- | --- | ---
`Number` | index | Tag to be used to be added to the list.
`ByteString` | value | Value to be used to be added to the List.

### Return

`` |

### Exceptions

Name | Value | Description
--- | --- | ---
GPError | GPError.INVALID_ARGUMENTS | Too many arguments in call
GPError | GPError.ARGUMENTS_MISSING | Too few arguments in call
GPError | GPError.INVALID_TYPE | Type of argument is invalid for call
GPError | GPError.INVALID_TAG | The tag value is invalid for the selected encoding format
GPError | GPError.INVALID_INDEX | The specified index is not valid
GPError | GPError.DATA_TOO_LARGE | The data supplied for the value fields exceeds the maximum length

### Example

    // L16 encoded data
    data = new ByteString("7F1F00050102030405", HEX);

    list = new TLVList(data, TLV.L16);
    assert(list.length == 1);

    // appendValueIndex(Number, Value)
    list.appendValueIndex(0, new ByteString("06070809", HEX));

    tlv = list.index(0);
    assert(tlv.getValue().toString(HEX) == "010203040506070809");

## deleteByIndex()

### Prototype

deleteByIndex(Number index)

### Description

Delete the specified TLV from the list using a zero based index.

### Arguments

Type | Name | Description
--- | --- | ---
`Number` | index | Zero based index number that represents the Tag that will be deleted from the list.

### Return

`` |

### Exceptions

Name | Value | Description
--- | --- | ---
GPError | GPError.INVALID_ARGUMENTS | Too many arguments in call
GPError | GPError.ARGUMENTS_MISSING | Too few arguments in call
GPError | GPError.INVALID_TYPE | Type of argument is invalid for call
GPError | GPError.INVALID_INDEX | The specified index is not valid

### Example

    // L16 encoded data
    data = new ByteString("7F1F000501020304050061000A00010203040506070809", HEX);

    list = new TLVList(data, TLV.L16);
    assert(list.length == 2);

    // deleteByIndex(Number)
    list.deleteByIndex(0);
    assert(list.length == 1);

    tlv = list.index(0);
    assert(tlv.getTLV().toString(HEX) == "0061000A00010203040506070809");

## deleteByTag()

### Prototype

deleteByTag(Number tag)

### Description

Delete the specified TLV from the list by tag value.

### Arguments

Type | Name | Description
--- | --- | ---
`Number` | tag | Number of Tag that will be deleted from the list.

### Return

`` |

### Exceptions

Name | Value | Description
--- | --- | ---
GPError | GPError.INVALID_ARGUMENTS | Too many arguments in call
GPError | GPError.ARGUMENTS_MISSING | Too few arguments in call
GPError | GPError.INVALID_TYPE | Type of argument is invalid for call
GPError | GPError.INVALID_INDEX | The specified index is not valid
GPError | GPError.TAG_NOT_FOUND | The specified tag could not be found

### Example

    // L16 encoded data
    data = new ByteString("7F1F000501020304050061000A00010203040506070809", HEX);

    list = new TLVList(data, TLV.L16);
    assert(list.length == 2);

    // deleteByTag(Number)
    list.deleteByTag(0x7F1F);
    assert(list.length == 1);

    tlv = list.index(0);
    assert(tlv.getTLV().toString(HEX) == "0061000A00010203040506070809");

## findIndex()

### Prototype

Number findIndex(Number tag)

### Description

Searches the list for a specified tag, and returns a zero based index for that TLV.

### Arguments

Type | Name | Description
--- | --- | ---
`Number` | tag | The Tag that will be searched for within the list.

### Return

`Number` | Index that indicates the location of the TLV within TLV list or -1 if not found.

### Exceptions

Name | Value | Description
--- | --- | ---
GPError | GPError.INVALID_ARGUMENTS | Too many arguments in call
GPError | GPError.ARGUMENTS_MISSING | Too few arguments in call
GPError | GPError.INVALID_TYPE | Type of argument is invalid for call
GPError | GPError.INVALID_TAG | The tag value is invalid for the selected encoding format

### Example

    // L16 encoded data
    data = new ByteString("7F1F000501020304050061000A00010203040506070809", HEX);

    list = new TLVList(data, TLV.L16);
    assert(list.length == 2);

    index_tag_61 = list.findIndex(0x61);
    assert(typeof(index_tag_61) == "number");
    assert(index_tag_61 == 1);

    index_tag_63 = list.findIndex(0x63);
    assert(index_tag_63 == -1);

## find()

### Prototype

TLV find(Number tag)

### Description

Searches the list for a specified tag, and returns a TLV object.

### Arguments

Type | Name | Description
--- | --- | ---
`Number` | tag | The Tag that will be searched for within the list.

### Return

`TLV` | A TLV object which contains the data stored for that Tag or null if the Tag was not found.

### Exceptions

Name | Value | Description
--- | --- | ---
GPError | GPError.INVALID_ARGUMENTS | Too many arguments in call
GPError | GPError.ARGUMENTS_MISSING | Too few arguments in call
GPError | GPError.INVALID_TYPE | Type of argument is invalid for call
GPError | GPError.INVALID_TAG | The tag value is invalid for the selected encoding format

### Example

    // L16 encoded data
    data = new ByteString("7F1F000501020304050061000A00010203040506070809", HEX);

    list = new TLVList(data, TLV.L16);
    assert(list.length == 2);

    tag_61 = list.find(0x61);
    assert(tag_61 != null);

    tag_63 = list.find(0x63);
    assert(tag_63 == null);

## updateValue()

### Prototype

updateValue(Number tag, ByteString value)

### Description

Updates the data for the specified tag.

### Arguments

Type | Name | Description
--- | --- | ---
`Number` | tag | Tag to be used to be added to the list.
`ByteString` | value | Data to replace existing value of TLV specified by tag with.

### Return

`` |

### Exceptions

Name | Value | Description
--- | --- | ---
GPError | GPError.INVALID_ARGUMENTS | Too many arguments in call
GPError | GPError.ARGUMENTS_MISSING | Too few arguments in call
GPError | GPError.INVALID_TYPE | Type of argument is invalid for call
GPError | GPError.INVALID_TAG | The tag value is invalid for the selected encoding format
GPError | GPError.DATA_TOO_LARGE | The data supplied for the value fields exceeds the maximum length

### Example

    // L16 encoded data
    data = new ByteString("7F1F00050102030405", HEX);

    list = new TLVList(data, TLV.L16);
    assert(list.length == 1);

    // appendValue(Number, Value)
    list.updateValue(0x7F1F, new ByteString("06070809", HEX));

    tlv = list.index(0);
    assert(tlv.getValue().toString(HEX) == "06070809");

## updateValueIndex()

### Prototype

updateValueIndex(Number index, ByteString value)

### Description

Updates the data for the specified zero-based index into the TLVStream.

### Arguments

Type | Name | Description
--- | --- | ---
`Number` | index | Tag to be used to be added to the list.
`ByteString` | value | Value to be used to be added to the List.

### Return

`` |

### Exceptions

Name | Value | Description
--- | --- | ---
GPError | GPError.INVALID_ARGUMENTS | Too many arguments in call
GPError | GPError.ARGUMENTS_MISSING | Too few arguments in call
GPError | GPError.INVALID_TYPE | Type of argument is invalid for call
GPError | GPError.INVALID_TAG | The tag value is invalid for the selected encoding format
GPError | GPError.INVALID_INDEX | The specified index is not valid
GPError | GPError.DATA_TOO_LARGE | The data supplied for the value fields exceeds the maximum length

### Example

    // L16 encoded data
    data = new ByteString("7F1F00050102030405", HEX);

    list = new TLVList(data, TLV.L16);
    assert(list.length == 1);

    // appendValueIndex(Number, Value)
    list.updateValueIndex(0, new ByteString("06070809", HEX));

    tlv = list.index(0);
    assert(tlv.getValue().toString(HEX) == "06070809");

## toByteString()

### Prototype

ByteString toByteString()

### Description

Returns the contents of the entire list, including T, L and V values in a TLV format as a ByteString object.

### Return

`ByteString` | The concatenated T, L and V values in a TLV format.

### Exceptions

Name | Value | Description
--- | --- | ---
GPError | GPError.INVALID_ARGUMENTS | Too many arguments in call
GPError | GPError.ARGUMENTS_MISSING | Too few arguments in call

### Example

    // L16 encoded data
    data = new ByteString("7F1F000501020304050061000A00010203040506070809", HEX);

    list = new TLVList(data, TLV.L16);
    assert(list.length == 2);

    t = list.toByteString();
    assert(t != null);

    assert(t.toString() == data.toString());

© Copyright 2003 - 2024 CardContact Systems GmbH , Minden, Germany