SSE4E

Home

GPError
GPSystem
ByteString
ByteBuffer
TLV
TLVList
Card
Atr
Key
Crypto
Application GPApplication GPSecDomain

ASN1
CardFile
IsoSecureChannel
ApplFactory
GPXML
JsScript
CardSim

X509
CRL
KeyStore
CMSSignedData
CMSGenerator
XMLSignature
OCSPQuery
LDAP
SOAP
URLConnection

PKCS11Provider
PKCS11Session
PKCS11Object

OutlineNode

OpenSCDP

TLVList - Reference Documentation

Implementation of a mutable TLV object list.

Index of Methods

Properties

TypeNameDescription
NumberencodingModeEncoding mode used for TLV object. One of TLV.EMV, TLV.DGI or TLV.L16
NumberlengthThe 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

TypeNameDescription
ByteStringtlvStreamByteString containing the encoded tlv objects
NumberencodingEncoding for tag and length field of the tlv objects in the ByteString. Must be one of TLV.EMV, TLV.DGI or TLV.L16.

Exceptions

NameValueDescription
GPErrorGPError.ARGUMENTS_MISSINGToo few arguments in call
GPErrorGPError.INVALID_ARGUMENTSToo many arguments in call
GPErrorGPError.INVALID_TYPEType of argument is invalid for call
GPErrorGPError.INVALID_ENCODINGThe argument encoding is invalid
GPErrorGPError.INVALID_TAGThe tag value is invalid for the selected encoding format
GPErrorGPError.DATA_TOO_LARGEThe 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

TypeNameDescription
NumberindexIndex of the TLV object

Return

TLVTLV object at the specified index

Exceptions

NameValueDescription
GPErrorGPError.INVALID_ARGUMENTSToo many arguments in call
GPErrorGPError.ARGUMENTS_MISSINGToo few arguments in call
GPErrorGPError.INVALID_TYPEType of argument is invalid for call
GPErrorGPError.INVALID_INDEXThe 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

TypeNameDescription
ByteStringtlvStreamTLV as a single stream of bytes in a ByteString.
NumbertagTag to be used to be added to the list.
ByteStringvalueValue to be used to be added to the List.
TLVtlvTLV as a TLV object.

Return

Exceptions

NameValueDescription
GPErrorGPError.INVALID_ARGUMENTSToo many arguments in call
GPErrorGPError.ARGUMENTS_MISSINGToo few arguments in call
GPErrorGPError.INVALID_TYPEType of argument is invalid for call
GPErrorGPError.INVALID_INDEXThe specified index is not valid
GPErrorGPError.INVALID_TAGThe tag value is invalid for the selected encoding format
GPErrorGPError.DATA_TOO_LARGEThe data supplied for the value fields exceeds the maximum length
GPErrorGPError.TAG_ALREADY_EXISTSThe 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

TypeNameDescription
NumbertagTag to be used to be added to the list.
ByteStringvalueValue to be used to be added to the List.

Return

Exceptions

NameValueDescription
GPErrorGPError.INVALID_ARGUMENTSToo many arguments in call
GPErrorGPError.ARGUMENTS_MISSINGToo few arguments in call
GPErrorGPError.INVALID_TYPEType of argument is invalid for call
GPErrorGPError.INVALID_TAGThe tag value is invalid for the selected encoding format
GPErrorGPError.DATA_TOO_LARGEThe 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

TypeNameDescription
NumberindexTag to be used to be added to the list.
ByteStringvalueValue to be used to be added to the List.

Return

Exceptions

NameValueDescription
GPErrorGPError.INVALID_ARGUMENTSToo many arguments in call
GPErrorGPError.ARGUMENTS_MISSINGToo few arguments in call
GPErrorGPError.INVALID_TYPEType of argument is invalid for call
GPErrorGPError.INVALID_TAGThe tag value is invalid for the selected encoding format
GPErrorGPError.INVALID_INDEXThe specified index is not valid
GPErrorGPError.DATA_TOO_LARGEThe 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

TypeNameDescription
NumberindexZero based index number that represents the Tag that will be deleted from the list.

Return

Exceptions

NameValueDescription
GPErrorGPError.INVALID_ARGUMENTSToo many arguments in call
GPErrorGPError.ARGUMENTS_MISSINGToo few arguments in call
GPErrorGPError.INVALID_TYPEType of argument is invalid for call
GPErrorGPError.INVALID_INDEXThe 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

TypeNameDescription
NumbertagNumber of Tag that will be deleted from the list.

Return

Exceptions

NameValueDescription
GPErrorGPError.INVALID_ARGUMENTSToo many arguments in call
GPErrorGPError.ARGUMENTS_MISSINGToo few arguments in call
GPErrorGPError.INVALID_TYPEType of argument is invalid for call
GPErrorGPError.INVALID_INDEXThe specified index is not valid
GPErrorGPError.TAG_NOT_FOUNDThe 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

TypeNameDescription
NumbertagThe Tag that will be searched for within the list.

Return

NumberIndex that indicates the location of the TLV within TLV list or -1 if not found.

Exceptions

NameValueDescription
GPErrorGPError.INVALID_ARGUMENTSToo many arguments in call
GPErrorGPError.ARGUMENTS_MISSINGToo few arguments in call
GPErrorGPError.INVALID_TYPEType of argument is invalid for call
GPErrorGPError.INVALID_TAGThe 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

TypeNameDescription
NumbertagThe Tag that will be searched for within the list.

Return

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

Exceptions

NameValueDescription
GPErrorGPError.INVALID_ARGUMENTSToo many arguments in call
GPErrorGPError.ARGUMENTS_MISSINGToo few arguments in call
GPErrorGPError.INVALID_TYPEType of argument is invalid for call
GPErrorGPError.INVALID_TAGThe 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

TypeNameDescription
NumbertagTag to be used to be added to the list.
ByteStringvalueData to replace existing value of TLV specified by tag with.

Return

Exceptions

NameValueDescription
GPErrorGPError.INVALID_ARGUMENTSToo many arguments in call
GPErrorGPError.ARGUMENTS_MISSINGToo few arguments in call
GPErrorGPError.INVALID_TYPEType of argument is invalid for call
GPErrorGPError.INVALID_TAGThe tag value is invalid for the selected encoding format
GPErrorGPError.DATA_TOO_LARGEThe 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

TypeNameDescription
NumberindexTag to be used to be added to the list.
ByteStringvalueValue to be used to be added to the List.

Return

Exceptions

NameValueDescription
GPErrorGPError.INVALID_ARGUMENTSToo many arguments in call
GPErrorGPError.ARGUMENTS_MISSINGToo few arguments in call
GPErrorGPError.INVALID_TYPEType of argument is invalid for call
GPErrorGPError.INVALID_TAGThe tag value is invalid for the selected encoding format
GPErrorGPError.INVALID_INDEXThe specified index is not valid
GPErrorGPError.DATA_TOO_LARGEThe 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

ByteStringThe concatenated T, L and V values in a TLV format.

Exceptions

NameValueDescription
GPErrorGPError.INVALID_ARGUMENTSToo many arguments in call
GPErrorGPError.ARGUMENTS_MISSINGToo 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());