ByteString - Reference Documentation

Implementation of an immutable binary string, similar to the String class.

Index of Methods

ByteString() constructor
and()
byteAt()
bytes()
concat()
crc()
equals()
find()
getL()
getLV()
left()
neg()
not()
or()
pad()
right()
startsWith()
toBase64()
toBcd()
toHex()
toSigned()
toString()
toUnsigned()
xor()
add()
clear()
valueOf()
fromJSON()
asSigned()
asUnsigned()
biAdd()
sub()
mod()
modInverse()
modPow()
multiply()
divide()

Constants

Type	Name	Description
Number	XOR	Constant used in crc() method

Properties

Type	Name	Description
Number	length	Number of bytes in the ByteString

Constructor

Prototype

ByteString(String stringValue, Number encoding)

Description

Create a ByteString object containing the data from stringValue decoded according to format defined in argument encoding

The following encoding formats can be used for the stringValue argument:

HEX - A string containing hexadecimal characters and arbitrary delimiters.

ASCII - A string containing ASCII characters and characters from Latin-1.

UTF8 - A string containing Unicode characters.

BASE64 - A string containing BASE-64 encoded data.

OID - A string containing an object identifier in dotted notation or separated by blanks (This is a proprietary extension to Global Platform Scripting).

Arguments

Type	Name	Description
`String`	stringValue	String containing the encoded binary data
`Number`	encoding	Encoding format. Must be one of HEX, ASCII, UTF8, BASE64 or OID

Exceptions

Name	Value	Description
GPError	GPError.ARGUMENTS_MISSING	Too few arguments given
GPError	GPError.INVALID_ARGUMENTS	Too many arguments given
GPError	GPError.INVALID_ENCODING	The argument encoding contains an unknown encoding format
GPError	GPError.INVALID_DATA	The argument stringValue contains characters not compatible with the encoding format
GPError	GPError.INVALID_TYPE	On or more arguments are not of the expected type

Example


x = new ByteString("1234", HEX);

assert(x.length == 2);
assert(x.toString() == "12 34");


x = new ByteString("", HEX);

assert(x.length == 0);
assert(x.toString() == "");


x = new ByteString("0x1234 56.78.90+AB#cd'EF", HEX);

assert(x.length == 8);
assert(x.toString() == "12 34 56 78 90 AB CD EF");


x = new ByteString("1234ABCDÄÖÜß", ASCII);

assert(x.length == 12);
assert(x.toString() == "31 32 33 34 41 42 43 44 C4 D6 DC DF");


x = new ByteString("1234ABCDÄÖÜß", UTF8);

assert(x.length == 16);
assert(x.toString() == "31 32 33 34 41 42 43 44 C3 84 C3 96 C3 9C C3 9F");


x = new ByteString("SGVsbG8gV29ybGQ=", BASE64);

assert(x.length == 11);
assert(x.toString(ASCII) == "Hello World");


x = new ByteString("1.2.840.113549.1.1.2", OID);

assert(x.length == 9);
assert(x.toString(OID) == "1.2.840.113549.1.1.2");
assert(x.toString(HEX) == "2A864886F70D010102");


x = new ByteString("1 2 840 113549 1 1 2", OID);

assert(x.toString(HEX) == "2A864886F70D010102");

and()

Prototype

ByteString and(ByteString value)

Description

The bitwise AND of the object for which this method is called and the argument. Both must be of equal size

Arguments

Type	Name	Description
`ByteString`	value	ByteString object of same size to use in bitwise and operation

Return

ByteString The result of the and operation as ByteString

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_LENGTH	Object and argument have different length
GPError	GPError.INVALID_TYPE	Type of argument is invalid for call

Example


x = new ByteString("AA A5 55", HEX);
y = new ByteString("55 A5 AA", HEX);
z = x.and(y);
assert(z.toString(HEX) == "00A500", HEX);

byteAt()

Prototype

Number byteAt(Number offset)

Description

Return the value of the byte at the zero based offset

Arguments

Type	Name	Description
`Number`	offset	Zero based offset

Return

Number The value of the byte at offset

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_INDEX	Offset is out of range

Example


x = new ByteString("123ABCÄÖÜ", ASCII);
assert(typeof(x.byteAt(0)) == "number");
assert(x.byteAt(0) == 0x31);
assert(x.byteAt(3) == 0x41);
assert(x.byteAt(6) == 0xC4);

bytes()

Prototype

ByteString bytes(Number offset)

ByteString bytes(Number offset, Number count)

Description

Extract count bytes from a ByteString starting at zero based offset. If count is missing then the all remaining bytes from offset are extracted.

Arguments

Type	Name	Description
`Number`	offset	Zero based offset from which bytes are extracted
`Number`	count	Number of bytes to extract

Return

ByteString New ByteString containing the extracted bytes

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_INDEX	The offset is out of range
GPError	GPError.INVALID_LENGTH	The offset plus the count exceeds the length of the buffer

Example


x = new ByteString("123ABC???", ASCII);
y = x.bytes(3, 3);
assert(y.toString(ASCII) == "ABC");

y = x.bytes(6);
assert(y.toString(ASCII) == "???");

y = x.bytes(9);
assert(y.toString(ASCII) == "");

concat()

Prototype

ByteString concat(ByteString value)

Description

Concatenate ByteString for which the method is called with argument value and return a new ByteString object. The ByteString for which the method is called is not changed.

Arguments

Type	Name	Description
`ByteString`	value	ByteString to append to object for which the method is called

Return

ByteString New ByteString object containing the concatenation of both objects

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

Example


x = new ByteString("123", ASCII);
y = new ByteString("414243", HEX);

z = x.concat(y);

assert(z.toString(ASCII) == "123ABC");

z = z.concat(new ByteString("", HEX));

assert(z.toString(ASCII) == "123ABC");

crc()

Prototype

ByteString crc(Number method)

Description

Calculate a checksum for the ByteString object using the method defined by argument method

Arguments

Type Name Description

Type	Name	Description
`Number`	method	The method to use for checksum calculation. Currently only XOR is available, calculating the XOR checksum across all bytes in the ByteString

Number

method

The method to use for checksum calculation.

Currently only XOR is available, calculating the XOR checksum across all bytes in the ByteString

Return

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_MECH	Argument method must be XOR

Example


x = new ByteString("A55A", HEX);
c = x.crc(ByteString.XOR);
assert(c.toString(HEX) == "FF");

x = new ByteString("", HEX);
c = x.crc(ByteString.XOR);
assert(c.toString(HEX) == "00");

equals()

Prototype

Boolean equals(ByteString value)

Description

Check if both ByteString have the same length and contain the same value.

Arguments

Type	Name	Description
`ByteString`	value	ByteString object to check against

Return

Boolean true if both ByteString are equal, otherwise false

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

Example


x = new ByteString("414243", HEX);
y = new ByteString("ABC", ASCII);

assert(x.equals(y));

y = new ByteString("CBA", ASCII);
assert(!x.equals(y));

y = new ByteString("ABCD", ASCII);
assert(!x.equals(y));

y = new ByteString("AB", ASCII);
assert(!x.equals(y));

find()

Prototype

Number find(ByteString value)

Number find(ByteString value, Number offset)

Description

Search the ByteString for the first occurance of the ByteString specified in argument value. Start at zero based offset or 0 if offset is not defined.

Arguments

Type	Name	Description
`ByteString`	value	ByteString to search for
`Number`	offset	Zero based index to start search at. 0 is assumed if parameter is not present

Return

Number Zero based offset at which the search string was found or -1 if the search string could not be found

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_INDEX	Offset given in argument is out of range
GPError	GPError.INVALID_TYPE	Type of argument is invalid for call

Example


x = new ByteString("ABCDABCD", ASCII);
y = new ByteString("BC", ASCII);

assert(typeof(x.find(y)) == "number");
assert(x.find(y) == 1);
assert(x.find(y, 2) == 5);
assert(x.find(y, -2) == 1);

y = new ByteString("CD", ASCII);
assert(x.find(y, 4) == 6);

y = new ByteString("CD", ASCII);
assert(x.find(y, 6) == 6);

y = new ByteString("CB", ASCII);
assert(x.find(y) == -1);

y = new ByteString("BCDE", ASCII);
assert(x.find(y) == -1);

y = new ByteString("", ASCII);
assert(x.find(y) == 0);

x = new ByteString("", ASCII);
y = new ByteString("", ASCII);
assert(x.find(y) == 0);
assert(x.find(y, 0) == 0);

getL()

Prototype

ByteString getL(Number method)

Description

Return a length field encoded as per specification in method.

TLV.EMV encodes the length field with a variable length as per ASN.1 DER encoding. Values in the range 0 to 127 are encoded in one byte. Values in the range 128 to 255 are encoded in two bytes with a leading '81'. Length fields in the range 256 to 65535 are encoded in three bytes with a leading '82' and two bytes in MSB/LSB order. Length fields in the range 65536 to 16777215 are encoded in four bytes with a leading '83' and three bytes in MSB/LSB format.

TLV.DGI encodes length values between 0 and 254 in one byte and length values between 255 and 65535 in three bytes with a leading 'FF' and two bytes in MSB/LSB format.

Arguments

Type	Name	Description
`Number`	method	Must be either TLV.EMV or TLV.DGI.

Return

ByteString Length field as ByteString

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_LENGTH	Length must not exceed 65535 for DGI encoding
GPError	GPError.INVALID_MECH	The encoding method is invalid

Example


x = new ByteString("", ASCII);
y = x.getL(TLV.EMV);
assert(y.toString(HEX) == "00");

y = x.getL(TLV.DGI);
assert(y.toString(HEX) == "00");


x = new ByteString("123ABC", ASCII);
y = x.getL(TLV.EMV);
assert(y.toString(HEX) == "06");

y = x.getL(TLV.DGI);
assert(y.toString(HEX) == "06");


x = new ByteString("01234567890123456789012345678901234567890123456789012345" +
                   "67890123456789012345678901234567890123456789012345678901" +
                   "2345678901234567", ASCII);
y = x.getL(TLV.EMV);
assert(y.toString(HEX) == "8180");

y = x.getL(TLV.DGI);
assert(y.toString(HEX) == "80");


x = new ByteString("01234567890123456789012345678901234567890123456789012345" +
                   "67890123456789012345678901234567890123456789012345678901" +
                   "23456789012345678901234567890123456789012345678901234567" +
                   "89012345678901234567890123456789012345678901234567890123" +
                   "4567890123456789012345678901234", ASCII);
y = x.getL(TLV.EMV);
assert(y.toString(HEX) == "81FF");

y = x.getL(TLV.DGI);
assert(y.toString(HEX) == "FF00FF");


x = new ByteString("01234567890123456789012345678901234567890123456789012345" +
                   "67890123456789012345678901234567890123456789012345678901" +
                   "23456789012345678901234567890123456789012345678901234567" +
                   "89012345678901234567890123456789012345678901234567890123" +
                   "45678901234567890123456789012345", ASCII);
y = x.getL(TLV.EMV);
assert(y.toString(HEX) == "820100");

y = x.getL(TLV.DGI);
assert(y.toString(HEX) == "FF0100");

getLV()

Prototype

ByteString getLV(Number method)

Description

Prefix the ByteString with a length field as specified by method.

Arguments

Type	Name	Description
`Number`	method	Must be either TLV.EMV or TLV.DGI

Return

ByteString Length field concatenated with content

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_LENGTH	Length must not exceed 65535 for DGI encoding
GPError	GPError.INVALID_MECH	The encoding method is invalid

Example


x = new ByteString("", ASCII);
y = x.getLV(TLV.EMV);
assert(y.toString(HEX) == "00");

y = x.getLV(TLV.DGI);
assert(y.toString(HEX) == "00");


x = new ByteString("123ABC", ASCII);
y = x.getLV(TLV.EMV);
assert(y.toString(HEX) == "06313233414243");

y = x.getLV(TLV.DGI);
assert(y.toString(HEX) == "06313233414243");


x = new ByteString("01234567890123456789012345678901234567890123456789012345" +
                   "67890123456789012345678901234567890123456789012345678901" +
                   "2345678901234567", ASCII);
y = x.getLV(TLV.EMV);
assert(y.equals(x.getL(TLV.EMV).concat(x)));

y = x.getLV(TLV.DGI);
assert(y.equals(x.getL(TLV.DGI).concat(x)));


x = new ByteString("01234567890123456789012345678901234567890123456789012345" +
                   "67890123456789012345678901234567890123456789012345678901" +
                   "23456789012345678901234567890123456789012345678901234567" +
                   "89012345678901234567890123456789012345678901234567890123" +
                   "45678901234567890123456789012345", ASCII);
y = x.getLV(TLV.EMV);
assert(y.equals(x.getL(TLV.EMV).concat(x)));

y = x.getLV(TLV.DGI);
assert(y.equals(x.getL(TLV.DGI).concat(x)));

left()

Prototype

ByteString left(Number value)

Description

Extract the leftmost number of bytes as specified in the argument.

Arguments

Type	Name	Description
`Number`	value	Number of leftmost bytes

Return

ByteString New ByteString object with leftmost bytes

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_LENGTH	The length specified exceeds the length of the ByteString

Example


x = new ByteString("123ABC", ASCII);
y = x.left(3);
assert(y.toString(ASCII) == "123");

y = x.left(9);
assert(y.toString(ASCII) == "123ABC");

neg()

Prototype

ByteString neg()

ByteString neg(Number size)

Description

Return a ByteString object with the negative binary value of the ByteString object the method is applied to.

The method calculates the ones-complement by inverting all bits and adding 1.

The method can be applied to ByteString objects of arbitrary length.

If no size argument is given, then the resulting ByteString has the same length as the ByteString object the method is called for

Arguments

Type	Name	Description
`Number`	size	The number of bytes in the resulting ByteString

Return

ByteString New ByteString object with negative 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_LENGTH	The size argument must be equals or larger than the length of the ByteString

Example


x = new ByteString("0101", HEX);
y = x.neg();
assert(y.toString(HEX) == "FEFF");

x = new ByteString("0101", HEX);
y = x.neg(3);
assert(y.toString(HEX) == "FFFEFF");

x = new ByteString("0000", HEX);
y = x.neg(3);
assert(y.toString(HEX) == "000000");

x = new ByteString("FFFF", HEX);
y = x.neg();
assert(y.toString(HEX) == "0001");

x = new ByteString("", HEX);
y = x.neg();
assert(y.toString(HEX) == "");

x = new ByteString("", HEX);
y = x.neg(2);
assert(y.toString(HEX) == "0000");

not()

Prototype

ByteString not()

Description

Return an new ByteString object with all bits inverted.

Return

ByteString New ByteString object of same size with all bits inverted.

Exceptions

Name	Value	Description
GPError	GPError.INVALID_ARGUMENTS	Too many arguments in call

Example


x = new ByteString("0101", HEX);

y = x.not();
assert(y.toString(HEX) == "FEFE");

y = y.not();
assert(y.toString(HEX) == "0101");

x = new ByteString("", HEX);

y = x.not();
assert(y.toString(HEX) == "");

or()

Prototype

ByteString or(ByteString value)

Description

Return a new ByteString object containing the bitwise OR of the ByteString object for which the method is called and the argument. Both ByteString objects must have the same length.

Arguments

Type	Name	Description
`ByteString`	value	ByteString argument.

Return

ByteString New ByteString object containing the result of the OR operation.

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_LENGTH	The length of the ByteString argument must be equal to the length of the ByteString object.
GPError	GPError.INVALID_TYPE	Type of argument is invalid for call

Example


x = new ByteString("AA A5 55", HEX);
y = new ByteString("55 A5 AA", HEX);
z = x.or(y);
assert(z.toString(HEX) == "FFA5FF", HEX);

pad()

Prototype

ByteString pad(Number method)

ByteString pad(Number method, Boolean optional)

Description

Return ByteString padded to the right according to the method specified.

Arguments

Type	Name	Description
`Number`	method	The padding method to use. Must be either Crypto.ISO9797_METHOD_1 or Crypto.ISO9797_METHOD_2. Method 1 will append the appropriate number of '00' bytes to complete the 8 byte block, whereas method 2 will append an '80' followed by the appropriate number of '00' bytes. Crypto.ISO9797_METHOD_1_16 or Crypto.ISO9797_METHOD_2_16 use a 16 byte block size.
`Boolean`	optional	If optional is true, then padding will only occur if the length is not a multiple of the block size. Default is false.

Return

ByteString New ByteString object containing the extracted bytes.

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_MECH	Invalid padding method

Example


x = new ByteString("123ABC", HEX);

y = x.pad(Crypto.ISO9797_METHOD_1);
assert(y.toString(HEX) == "123ABC0000000000");

y = x.pad(Crypto.ISO9797_METHOD_1_16);
assert(y.toString(HEX) == "123ABC00000000000000000000000000");

y = x.pad(Crypto.ISO9797_METHOD_2);
assert(y.toString(HEX) == "123ABC8000000000");

y = x.pad(Crypto.ISO9797_METHOD_2_16);
assert(y.toString(HEX) == "123ABC80000000000000000000000000");

x = new ByteString("123ABC11223333", HEX);

y = x.pad(Crypto.ISO9797_METHOD_1);
assert(y.toString(HEX) == "123ABC1122333300");

y = x.pad(Crypto.ISO9797_METHOD_2);
assert(y.toString(HEX) == "123ABC1122333380");

x = new ByteString("123ABC112233338877665544332211", HEX);

y = x.pad(Crypto.ISO9797_METHOD_1_16);
assert(y.toString(HEX) == "123ABC11223333887766554433221100");

y = x.pad(Crypto.ISO9797_METHOD_2_16);
assert(y.toString(HEX) == "123ABC11223333887766554433221180");

x = new ByteString("123ABC1122333399", HEX);

y = x.pad(Crypto.ISO9797_METHOD_1, true);
assert(y.toString(HEX) == "123ABC1122333399");

y = x.pad(Crypto.ISO9797_METHOD_2, true);
assert(y.toString(HEX) == "123ABC1122333399");

x = new ByteString("123ABC11223333998877665544332211", HEX);

y = x.pad(Crypto.ISO9797_METHOD_1_16, true);
assert(y.toString(HEX) == "123ABC11223333998877665544332211");

y = x.pad(Crypto.ISO9797_METHOD_2_16, true);
assert(y.toString(HEX) == "123ABC11223333998877665544332211");

right()

Prototype

ByteString right(Number count)

Description

Return the rightmost bytes of the ByteString as specified by the argument.

Arguments

Type	Name	Description
`Number`	count	The number of bytes to extract.

Return

ByteString New ByteString object containing the extracted bytes.

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_LENGTH	The count argument must not exceed the length of the ByteString.

Example


x = new ByteString("123ABC", ASCII);
y = x.right(3);
assert(y.toString(ASCII) == "ABC");

y = x.right(9);
assert(y.toString(ASCII) == "123ABC");

startsWith()

Prototype

Number startsWith(ByteString value)

Description

Return the number of bytes by which the ByteString and the argument start with the same bytes.

Arguments

Type	Name	Description
`ByteString`	value	ByteString to test against.

Return

Number Number of equal bytes in object and argument.

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

Example


x = new ByteString("123ABC", ASCII);
y = new ByteString("123", ASCII);

assert(typeof(x.startsWith(y)) == "number");
assert(x.startsWith(y) == 3);
assert(y.startsWith(x) == 3);

y = new ByteString("1234", ASCII);
assert(x.startsWith(y) == 3);

y = new ByteString("01234", ASCII);
assert(x.startsWith(y) == 0);

toBase64()

Prototype

ByteString toBase64()

ByteString toBase64(Boolean linebreak)

Description

Return a new ByteString object containing the BASE64 encoding of the ByteString object for which the method is called.

The resulting ByteString will only contain ASCII characters.

If the linebreak argument is true, then a newline is inserted after each 62. character (48 Bytes).

Arguments

Type	Name	Description
`Boolean`	linebreak	If true, a newline is inserted after each 62. character. Default is false.

Return

ByteString New ByteString object containing BASE64 encoded ASCII string.

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

Example


x = new ByteString("Hello World", ASCII);
y = x.toBase64();
assert(y.toString(ASCII) == "SGVsbG8gV29ybGQ=");

x = new ByteString("The quick brown fox jumped over the lazy dog12345", ASCII);
y = x.toBase64(false);
assert(y.toString(ASCII) ==
  "VGhlIHF1aWNrIGJyb3duIGZveCBqdW1wZWQgb3ZlciB0aGUgbGF6eSBkb2cxMjM0NQ==");

x = new ByteString("The quick brown fox jumped over the lazy dog12345", ASCII);
y = x.toBase64(true);
assert(y.toString(ASCII) ==
  "VGhlIHF1aWNrIGJyb3duIGZveCBqdW1wZWQgb3ZlciB0aGUgbGF6eSBkb2cxMjM0\nNQ==");

x = new ByteString("", ASCII);
y = x.toBase64(true);
assert(y.length == 0);

toBcd()

Prototype

ByteString toBcd()

ByteString toBcd(Number countBytes)

Description

Return a new ByteString object containing the BCD encoded binary value of the ByteString for which the method is called.

The ByteString can be up to 63 bits long.

If the optional countBytes argument is given, then the resulting ByteString has countBytes length. If the resulting ByteString is longer than the BCD encoded value, then zeros are padded to the left. If the resulting ByteString is smaller than the BCD encoded value, then only the rightmost digits are preserved.

Arguments

Type	Name	Description
`Number`	countBytes	Length of resulting ByteString.

Return

New ByteString object containing BCD encoded 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_LENGTH	The countBytes argument is invalid.

Example


x = new ByteString("0101", HEX);
y = x.toBcd();
assert(y.toString(HEX) == "0257");

y = x.toBcd(3);
assert(y.toString(HEX) == "000257");

y = x.toBcd(1);
assert(y.toString(HEX) == "57");

x = new ByteString("7FFFFFFFFFFFFFFF", HEX);

y = x.toBcd();
assert(y.toString(HEX) == "09223372036854775807");

y = x.toBcd(0);
assert(y.toString(HEX) == "");

toHex()

Prototype

ByteString toHex()

ByteString toHex(Number countBytes)

Description

Return a new ByteString object containing in ASCII the HEX encoded binary value of the ByteString for which the method is called.

The ByteString can be of arbitrary length.

If the optional countBytes argument is given, then the resulting ByteString has countBytes length. If the resulting ByteString is longer than the HEX encoded value, then ASCII zeros ('0') are padded to the left. If the resulting ByteString is smaller than the HEX encoded value, then only the rightmost digits are preserved.

Arguments

Type	Name	Description
`Number`	countBytes	Optional argument specifying the bytes the length of the resulting ByteString.

Return

ByteString New ByteString object containing ASCII encoded HEX string.

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_LENGTH	Type countBytes argument is negativ.

Example


x = new ByteString("65666768", HEX);
y = x.toHex();
assert(y.toString(ASCII) == "65666768");

x = new ByteString("65666768", HEX);
y = x.toHex(10);
assert(y.toString(ASCII) == "0065666768");

x = new ByteString("65666768", HEX);
y = x.toHex(4);
assert(y.toString(ASCII) == "6768");

x = new ByteString("", HEX);
y = x.toHex();
assert(y.toString(ASCII) == "");

toSigned()

Prototype

Number toSigned()

Number toSigned(Boolean littleEndian)

Description

Return the signed binary value of the ByteString.

The ByteString can be of arbitrary length, however the number of significant bits must not exceed 32. Leading zeros for positive values or ones for negative values are skipped. The first bit in the ByteString is used as sign bit.

Arguments

Type	Name	Description
`Boolean`	littleEndian	Assume little endian encoding format. Optional argument, default is false.

Return

Number ByteString as 32 bit signed integer 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.DATA_TOO_LARGE	The number of significant bits exceeds 32.

Example


x = new ByteString("", HEX);
assert(typeof(x.toSigned()) == "number");
assert(x.toSigned() == 0);

x = new ByteString("0123", HEX);
assert(x.toSigned() == 0x0123);

x = new ByteString("FF", HEX);
assert(x.toSigned() == -1);

x = new ByteString("7FFFFFFF", HEX);
assert(x.toSigned() == 0x7FFFFFFF);

x = new ByteString("007FFFFFFF", HEX);
assert(x.toSigned() == 0x7FFFFFFF);

x = new ByteString("007FEDCBA0", HEX);
assert(x.toSigned() == 0x7FEDCBA0);

x = new ByteString("FFFFFFFF", HEX);
assert(x.toSigned() == -1);

x = new ByteString("FFFFFFFFFF", HEX);
assert(x.toSigned() == -1);

x = new ByteString("FF80000000", HEX);
assert(x.toSigned() == -0x80000000);

x = new ByteString("", HEX);
assert(x.toSigned(true) == 0);

x = new ByteString("0123", HEX);
assert(x.toSigned(true) == 0x2301);

x = new ByteString("FF", HEX);
assert(x.toSigned(true) == -1);

x = new ByteString("FFFFFF7F", HEX);
assert(x.toSigned(true) == 0x7FFFFFFF);

x = new ByteString("FFFFFF7F00", HEX);
assert(x.toSigned(true) == 0x7FFFFFFF);

x = new ByteString("A0CBED7F00", HEX);
assert(x.toSigned(true) == 0x7FEDCBA0);

x = new ByteString("FFFFFFFF", HEX);
assert(x.toSigned(true) == -1);

x = new ByteString("FFFFFFFFFF", HEX);
assert(x.toSigned(true) == -1);

x = new ByteString("00000080FF", HEX);
assert(x.toSigned(true) == -0x80000000);

toString()

Prototype

String toString()

String toString(Number encoding)

Description

Return a String containing the ByteString value in the encoding specified by the argument or as hexadecimal string.

Arguments

Type	Name	Description
`Number`	encoding	Encoding format, one of ASCII, UTF8, BASE64 or CN.

Return

String String containing ByteString value in specified encoding format.

Exceptions

Name	Value	Description
GPError	GPError.INVALID_DATA	ByteString can not be expressed in specified encoding.
GPError	GPError.INVALID_ENCODING	Unknown encoding format specified.

Example


x = new ByteString("41 42 43", HEX);
assert(x.toString(HEX) == "414243");

x = new ByteString("41 42 43 C4 D6 DC DF", HEX);
assert(x.toString(ASCII) == "ABCÄÖÜß");

x = new ByteString("C3 84 C3 96 C3 9C C3 9F", HEX);
assert(x.toString(UTF8) == "ÄÖÜß");

x = new ByteString("Hello World", ASCII);
assert(x.toString(BASE64) == "SGVsbG8gV29ybGQ=");

toUnsigned()

Prototype

Number toUnsigned()

Number toUnsigned(Boolean littleEndian)

Description

Return the unsigned binary value of the ByteString.

The ByteString can be of arbitrary length, however the number of significant bits must not exceed 64. Leading zeros are skipped.

Arguments

Type	Name	Description
`Boolean`	littleEndian	Assume little endian encoding format. Optional argument, default is false.

Return

Number ByteString as 64 bit unsigned integer 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.DATA_TOO_LARGE	The number of significant bits exceeds 64.

Example


x = new ByteString("", HEX);
assert(typeof(x.toUnsigned()) == "number");
assert(x.toUnsigned() == 0);

x = new ByteString("0123", HEX);
assert(x.toUnsigned() == 0x0123);

x = new ByteString("FF", HEX);
assert(x.toUnsigned() == 255);

x = new ByteString("FFFFFFFF", HEX);
assert(x.toUnsigned() == 0xFFFFFFFF);

x = new ByteString("00FFFFFFFF", HEX);
assert(x.toUnsigned() == 0xFFFFFFFF);

x = new ByteString("00DFEDCBA0", HEX);
assert(x.toUnsigned() == 0xDFEDCBA0);

x = new ByteString("007FFFFFFFFFFFFFFF", HEX);
assert(x.toUnsigned() == 0x7FFFFFFFFFFFFFFF);

x = new ByteString("7FEDCBA0DFEDCBA0", HEX);
assert(x.toUnsigned() == 0x7FEDCBA0DFEDCBA0);


x = new ByteString("", HEX);
assert(x.toUnsigned(true) == 0);

x = new ByteString("0123", HEX);
assert(x.toUnsigned(true) == 0x2301);

x = new ByteString("FF", HEX);
assert(x.toUnsigned(true) == 0xFF);

x = new ByteString("FFFFFF8F", HEX);
assert(x.toUnsigned(true) == 0x8FFFFFFF);

x = new ByteString("FFFFFFFFFFFFFF7F00", HEX);
assert(x.toUnsigned(true) == 0x7FFFFFFFFFFFFFFF);

x = new ByteString("70CBED7FA0CBED7F00", HEX);
assert(x.toUnsigned(true) == 0x7FEDCBA07FEDCB70);

xor()

Prototype

ByteString xor(ByteString value)

Description

Return a new ByteString object containing the bitwise exclusive or of the ByteString object for which the method is called and the argument. Both ByteString objects must have the same length.

Arguments

Type	Name	Description
`ByteString`	value	ByteString argument.

Return

ByteString New ByteString object containing the result of the XOR operation.

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_LENGTH	The length of the ByteString argument must be equal to the length of the ByteString object.
GPError	GPError.INVALID_TYPE	Type of argument is invalid for call

Example


x = new ByteString("AA A5 55", HEX);
y = new ByteString("55 A5 AA", HEX);
z = x.xor(y);

assert(z.toString(HEX) == "FF00FF", HEX);

add()

Prototype

ByteString add(Number value)

Description

Returns a ByteString with the same length, which is the total of the objects value, interpreted as big unsigned integer value, plus the signed value.

This method is suitable for implementing sequence counters, in particular for secure messaging.

Arguments

Type	Name	Description
`Number`	value	The signed value to add.

Return

ByteString New ByteString object that is the total of base plus 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

Example


var base = new ByteString("00", HEX);
var r = base.add(1)
assert(r.toString(HEX) == "01", HEX);

var r = r.add(-1)
assert(r.toString(HEX) == "00", HEX);

var r = r.add(-1)
assert(r.toString(HEX) == "FF", HEX);

var base = new ByteString("FFFFFFFFFFFFFFFF", HEX);
var r = base.add(2)
assert(r.toString(HEX) == "0000000000000001", HEX);
var r = r.add(-1)
assert(r.toString(HEX) == "0000000000000000", HEX);
var r = r.add(-1)
var base = new ByteString("FFFFFFFFFFFFFFFF", HEX);

clear()

Prototype

clear()

Description

Overwrite buffer with zeros to clear sensitive informations.

Return

Exceptions

Name	Value	Description
GPError	GPError.INVALID_ARGUMENTS	Too many arguments in call
GPError	GPError.INVALID_TYPE	Type of argument is invalid for call

Example


var b = new ByteString("A5", HEX);
b.clear();

assert(b.toString(HEX) == "00", HEX);

valueOf()

Prototype

ByteString ByteString.valueOf(Number value)

ByteString ByteString.valueOf(Number value, Number octets)

Description

Returns a ByteString encoding the value in big endian format.

If the argument octets is not provided, the value is encoded on the minimum number of bytes.

If the argument octets is provided, the value is encoded on the given number of bytes, possibly truncating the value.

The number range is -(2^63) to 2^63 - 1.

Arguments

Type	Name	Description
`Number`	value	The value to convert.

Return

ByteString New ByteString object encoding the integer 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

Example


var r = ByteString.valueOf(0);
assert(r.toString(HEX) == "00");

var r = ByteString.valueOf(0, 2);
assert(r.toString(HEX) == "0000");

var r = ByteString.valueOf(1);
assert(r.toString(HEX) == "01");

var r = ByteString.valueOf(1, 2);
assert(r.toString(HEX) == "0001");

var r = ByteString.valueOf(256);
assert(r.toString(HEX) == "0100");

var r = ByteString.valueOf(256, 1);
assert(r.toString(HEX) == "00");

var r = ByteString.valueOf(0x80000000);
assert(r.toString(HEX) == "80000000");

var r = ByteString.valueOf(-1);
assert(r.toString(HEX) == "FFFFFFFFFFFFFFFF");

var r = ByteString.valueOf(-1, 2);
assert(r.toString(HEX) == "FFFF");

fromJSON()

Prototype

ByteString ByteString.fromJSON(Object json)

Description

Returns a ByteString created from the JSON encoded class format.

The JSON object must contain a property "clazz" with value "ByteString" and a property "value" with a hexadecimal encoded string.

Arguments

Type	Name	Description
`Object`	json	The JavaScript object

Return

ByteString New ByteString object encoding the value property

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 JSON object does not contain the required properties

Example


var b1 = new ByteString("1234", HEX);
var j = JSON.stringify(b1);
assert(j == '{"clazz":"ByteString","value":"1234"}');
var o = JSON.parse(j);
var b2 = ByteString.fromJSON(o);
assert(b2.equals(b1));

asSigned()

Prototype

ByteString asSigned()

Description

Return the signed binary value of the ByteString.

Return

ByteString ByteString as signed integer value.

Exceptions

Name	Value	Description
GPError	GPError.INVALID_ARGUMENTS	Too many arguments in call

Example


var unsigned = new ByteString("80", HEX);
var signed = unsigned.asSigned();
assert(unsigned.toString(HEX) == "80");
assert(signed.toString(HEX) == "0080");

var unsigned = new ByteString("7F", HEX);
var signed = unsigned.asSigned();
assert(unsigned.toString(HEX) == "7F")
assert(signed.toString(HEX) == "7F");

var b = new ByteString("00 01", HEX);
var signed = b.asSigned();
assert(b.toString(HEX) == "0001");
assert(signed.toString(HEX) == "0001");

asUnsigned()

Prototype

ByteString asUnsigned()

ByteString asUnsigned(Number length)

Description

Return the unsigned binary value of the ByteString.

Arguments

Type	Name	Description
`Number`	length	The minimum size of the ByteString.

Return

ByteString ByteString as unsigned integer value.

Exceptions

Name	Value	Description
GPError	GPError.INVALID_ARGUMENTS	Too many arguments in call
GPError	GPError.INVALID_TYPE	Type of argument is invalid for call

Example


var b = new ByteString("00 01", HEX);
var unsigned = b.asUnsigned();
assert(unsigned.toString(HEX) == "01");

var b = new ByteString("00 00 01", HEX);
var unsigned = b.asUnsigned(2);
assert(unsigned.toString(HEX) == "0001");

var b = new ByteString("00 01", HEX);
var unsigned = b.asUnsigned(2);
assert(unsigned.toString(HEX) == "0001");

var b = new ByteString("01 01", HEX);
var unsigned = b.asUnsigned();
assert(unsigned.toString(HEX) == "0101");

var b = new ByteString("CA FE", HEX);
var unsigned = b.asUnsigned(4);
assert(unsigned.toString(HEX) == "0000CAFE");

var b = new ByteString("00", HEX);
var unsigned = b.asUnsigned();
assert(unsigned.toString(HEX) == "00");

biAdd()

Prototype

ByteString biAdd(ByteString value)

Description

Returns a ByteString which is the total of the objects value, interpreted as big signed integer value, plus the signed value.

Arguments

Type	Name	Description
`ByteString`	value	The signed big integer to add.

Return

ByteString New ByteString object that is the total of base plus 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

Example


var b = new ByteString("00 FF", HEX);
var total = b.biAdd(new ByteString("00 FF 01", HEX));
assert(total.toString(HEX) == "010000");

var b = new ByteString("7F", HEX);
var total = b.biAdd(new ByteString("01", HEX));
assert(total.toString(HEX) == "0080");

var b = new ByteString("FF FF", HEX);
var total = b.biAdd(new ByteString("01", HEX));
assert(total.toString(HEX) == "00");

sub()

Prototype

ByteString sub(ByteString value)

Description

Returns a ByteString which is the difference of the objects value, interpreted as big signed integer value, minus the signed value.

Arguments

Type	Name	Description
`ByteString`	value	The signed big integer to subtract.

Return

ByteString New ByteString object that is the difference of base minus 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

Example


var b = new ByteString("00 80", HEX);
var difference = b.sub(new ByteString("01", HEX));
assert(difference.toString(HEX) == "7F");

var b = new ByteString("00", HEX);
var difference = b.sub(new ByteString("01", HEX));
assert(difference.toString(HEX) == "FF");

var b = new ByteString("7F", HEX);
var difference = b.sub(new ByteString("FF", HEX));
assert(difference.toString(HEX) == "0080");

mod()

Prototype

ByteString mod(ByteString m)

Description

Returns a non-negative ByteString which is the objects value, interpreted as big signed integer value, modulo the unsigned m.

Arguments

Type	Name	Description
`ByteString`	m	The modulo as unsigned big integer.

Return

ByteString New non-negative ByteString object that is base value mod m.

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

Example


var b = new ByteString("0B", HEX);
var value = b.mod(new ByteString("07", HEX));
assert(value.toString(HEX) == "04");

modInverse()

Prototype

ByteString modInverse(ByteString m)

Description

Returns ByteString which is the multiplicative inverse of the objects value, interpreted as big signed integer value, modulo the unsigned m.

Arguments

Type	Name	Description
`ByteString`	m	The modulo as unsigned big integer.

Return

ByteString New ByteString object that is base^-1 mod m.

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

Example


var b = new ByteString("17", HEX);
var value = b.modInverse(new ByteString("78", HEX));
assert(value.toString(HEX) == "2F");

modPow()

Prototype

ByteString modPow(ByteString exponent, ByteString m)

Description

Returns ByteString which is the objects value, interpreted as big signed integer value, raised to the power of exp modulo the unsigned m.

Arguments

Type	Name	Description
`ByteString`	exponent	The exponent as signed big integer.
`ByteString`	m	The modulo as unsigned big integer.

Return

ByteString New ByteString object that is base^exponent mod m.

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

Example


var b = new ByteString("03 DF", HEX);
var exp = new ByteString("03 E5", HEX);
var m = new ByteString("04 00", HEX);
var value = b.modPow(exp, m);
assert(value.toString(HEX) == "035F");

multiply()

Prototype

ByteString multiply(ByteString factor)

Description

Returns ByteString which is the objects value, interpreted as big signed integer value, multiplied by the unsigned factor.

Arguments

Type	Name	Description
`ByteString`	factor	The factor as signed big integer.

Return

ByteString New ByteString object that is base * factor.

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

Example


var b = new ByteString("10", HEX);
var factor = new ByteString("02", HEX);
var value = b.multiply(factor);
assert(value.toString(HEX) == "20");

divide()

Prototype

ByteString divide(ByteString divisor)

Description

Returns ByteString which is the objects value, interpreted as big signed integer value, divided by the unsigned divisor.

Arguments

Type	Name	Description
`ByteString`	divisor	The divisor as signed big integer.

Return

ByteString New ByteString object that is base / divisor.

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

Example


var b = new ByteString("20", HEX);
var divisor = new ByteString("02", HEX);
var value = b.divide(divisor);
assert(value.toString(HEX) == "10");

Smart Card Shell

ByteString - Reference Documentation

Index of Methods

Constants

Properties

Constructor

Prototype

Description

Arguments

Exceptions

Example

and()

Prototype

Description

Arguments

Return

Exceptions

Example

byteAt()

Prototype

Description

Arguments

Return

Exceptions

Example

bytes()

Prototype

Description

Arguments

Return

Exceptions

Example

concat()

Prototype

Description

Arguments

Return

Exceptions

Example

crc()

Prototype

Description

Arguments

Return

Exceptions

Example

equals()

Prototype

Description

Arguments

Return

Exceptions

Example

find()

Prototype

Description

Arguments

Return

Exceptions

Example

getL()

Prototype

Description

Arguments

Return

Exceptions

Example

getLV()

Prototype

Description

Arguments

Return

Exceptions

Example

left()

Prototype

Description

Arguments

Return

Exceptions