iaik.tc.tss.api.structs.common
Class TcBlobData

Object
  TcBlobData

public class TcBlobData
extends Object

This class represents a data blob (binary data object) that is received from/passed to the TSS. Passing parameters as simple unsigned byte arrays is a common practice in the TSS APIs. This class provides an abstraction of this byte data objects.

Method Summary

void	append(TcBlobData dataToAppend) This method is used to append binary data to the current binary data block.
byte[]	asByteArray() This method returns the entire binary data as a byte array.
short[]	asShortArray() This method returns the entire binary data as a short array.
Object	clone() This method returns a clone of the object.
boolean	equals(Object obj) This method checks if two objects are equal.
void	flush() Flushes the internal buffer by filling it with 0.
byte	getByteOrder() This method returns the byte order used when converting UINT16 and UINT32 types to byte blobs.
byte	getElement(int index) This method returns the byte value at the given position.
int	getLength() This method returns the length of the binary data.
long	getLengthAsLong() This method returns the length of the binary data.
byte[]	getRange(int index, int numElements) This method returns a specified range of elements.
short[]	getRangeAsShortArray(int index, int numElements) This method returns a specified range of elements.
int	hashCode()
TcBlobData	hmacSha1(TcBlobData key) This method returns the HmacSha1 digest of the object's data using the given HMAC key.
TcBlobData	initStringASCII(String input) Initializes the object using the provided String value.
void	invalidateContent() This method overwrites the data held internally by the object with all zeros.
static TcBlobData	newBlobData(TcBlobData other) This method takes another TcBlobData object and copies its contents to this object (i.e.
static TcBlobData	newBOOL(boolean input) Initializes the object using the provided boolean value.
static TcBlobData	newBYTE(short input) Initializes the object using the provided short value.
static TcBlobData	newByteArray(byte[] input) This factory method creates a new blob and initializes it with the given byte array.
static TcBlobData	newByteArray(byte[] input, int offset, int numBytes) This factory method creates a new blob and initializes it with the given byte array.
static TcBlobData	newString(String input) Initializes the object using the provided String value.Note that this method uses the default string encoding and the default null termination behavior.
static TcBlobData	newString(String input, boolean addNullTermination) Initializes the object using the provided String value.
static TcBlobData	newString(String input, boolean addNullTermination, String stringEncoding) Initializes the object using the provided String value.
static TcBlobData	newStringASCII(String input) Initializes the object using the provided String value.
static TcBlobData	newUINT16(int input) Initializes the object using the provided int value.
static TcBlobData	newUINT16(int input, byte byteOrder) Initializes the object using the provided int value.
static TcBlobData	newUINT32(long input) Initializes the object using the provided long value.
static TcBlobData	newUINT32(long input, byte byteOrder) Initializes the object using the provided long value.
static TcBlobData	newUINT64(BigInteger input)
void	overrideByteOrder(byte byteOrder) This method allows to override the default byte order used when parsing mutli-byte types into a byte array.
void	overrideStringEncoding(String encoding) This method allows to override the string encoding scheme that is used when interpreting the data held by the object.
void	overrideStringIsNullTerminated(boolean isNullTerminated) This method allows to override the internal flag indicating if the contained string data is null terminated or not.
void	prepend(TcBlobData dataToPrepend) This method is used to prepend binary data to the current binary data block.
TcBlobData	sha1() This method returns the SHA-1 digest of the contained binary data.
boolean	stringIsNullTerminated() This method returns true if the contained string data is null terminated, false otherwise.
void	substBytes(int offset, byte[] data) This method allows to substitute a contiguous range of bytes in the byte blob.
void	toggleNullTermination() This method appends or removes the null termination character of the contained data based on the current state of the stringIsNullTerminated_ flag.
String	toHexString() Returns a hex string representation of the object's binary data.
String	toHexStringNoWrap()
String	toString() Returns a string representation of the object's binary data.
String	toStringASCII() Returns a string representation of the object's binary data.
TcBlobData	xor(TcBlobData key) This method returns the object's data in XOR encrypted form using the provided key.

Methods inherited from class Object

getClass, notify, notifyAll, wait, wait, wait

Method Detail

newBYTE

public static TcBlobData newBYTE(short input)
                          throws IllegalArgumentException

Initializes the object using the provided short value. This is equivalent to the TSS BYTE (8 bit) data type.

Parameters:

input - Single byte the object is initialized with.

Returns:

this Pointer of the object

Throws:

IllegalArgumentException - If negative arguments are supplied, this exception is thrown.

newBOOL

public static TcBlobData newBOOL(boolean input)
                          throws IllegalArgumentException

Initializes the object using the provided boolean value. This is equivalent to the TSS BOOL (8 bit) data type.

Parameters:

input - Single byte the object is initialized with.

Returns:

this Pointer of the object

Throws:

IllegalArgumentException - If negative arguments are supplied, this exception is thrown.

newUINT16

public static TcBlobData newUINT16(int input)
                            throws IllegalArgumentException

Initializes the object using the provided int value. Note that only positive int arguments are accepted. Otherwise an IllegalArgumentException is thrown. This is the way, the UINT16 (unsigned 16 bit integer) specified in the TCG specs, is handled.

Parameters:

input - Single short the object is initialized with.

Returns:

this Pointer of the object

Throws:

IllegalArgumentException - If negative arguments are supplied, this exception is thrown.

newUINT16

public static TcBlobData newUINT16(int input,
                                   byte byteOrder)
                            throws IllegalArgumentException

Initializes the object using the provided int value. Note that only positive int arguments are accepted. Otherwise an IllegalArgumentException is thrown. This is the way, the UINT16 (unsigned 16 bit integer) specified in the TCG specs, is handled. This method additionally allows to specify the byte order used when converting the UINT32 into a byte array.

Parameters:

input - Single short the object is initialized with.

byteOrder - byte order to be used

Returns:

this Pointer of the object

Throws:

IllegalArgumentException - If negative arguments are supplied, this exception is thrown.

newUINT32

public static TcBlobData newUINT32(long input)
                            throws IllegalArgumentException

Initializes the object using the provided long value. Note that only positive long arguments are accepted. Otherwise an IllegalArgumentException is thrown. This is the way, the UINT32 (unsigned 32 bit integer) specified in the TCG specs, is handled.

Parameters:

input - Single int the object is initialized with.

Returns:

this Pointer of the object

Throws:

IllegalArgumentException - If negative arguments are supplied, this exception is thrown.

newUINT64

public static TcBlobData newUINT64(BigInteger input)
                            throws IllegalArgumentException

Parameters:

input - Single BigInteger the object is initialized with.

Returns:

this Pointer of the object

Throws:

IllegalArgumentException - If negative arguments are supplied, this exception is thrown.

newUINT32

public static TcBlobData newUINT32(long input,
                                   byte byteOrder)
                            throws IllegalArgumentException

Initializes the object using the provided long value. Note that only positive long arguments are accepted. Otherwise an IllegalArgumentException is thrown. This is the way, the UINT32 (unsigned 32 bit integer) specified in the TCG specs, is handled. This method additionally allows to specify the byte order used when converting the UINT32 into a byte array.

Parameters:

input - Single short the object is initialized with.

byteOrder - byte order to be used

Returns:

this Pointer of the object

Throws:

IllegalArgumentException - If negative arguments are supplied, this exception is thrown.

newByteArray

public static TcBlobData newByteArray(byte[] input)

This factory method creates a new blob and initializes it with the given byte array.

newByteArray

public static TcBlobData newByteArray(byte[] input,
                                      int offset,
                                      int numBytes)

This factory method creates a new blob and initializes it with the given byte array. This method copies numBytes from the input array starting at offset.

Parameters:

input - Byte array the object is initialized with.

offset - the Offset the data copying starts from

numBytes - the number of bytes copied

Returns:

this Pointer of the new object

newString

public static TcBlobData newString(String input,
                                   boolean addNullTermination,
                                   String stringEncoding)

Initializes the object using the provided String value. The String is parsed into an array of bytes in accordance with the provided String encoding scheme.

Parameters:

input - String the object is initialized with.

addNullTermination - If true, a null termination character is appended.

stringEncoding - The encoding scheme used when parsing the given String into a byte array.

Returns:

this Pointer of the object

newString

public static TcBlobData newString(String input,
                                   boolean addNullTermination)

Initializes the object using the provided String value. This method uses the uses the default encoding scheme. Note that the TSS spec 1.2 (Errata A.19 onwards) says that the terminating null character SHOULD NOT be included by default in TSS_UNICODE strings coming from TSS_SECRET_MODE_POPUP. Based on this statement, probably all passwords should be created without null termination.

Parameters:

input - String the object is initialized with.

addNullTermination - If true, a null termination character is appended.

Returns:

this Pointer of the object

newString

public static TcBlobData newString(String input)

Initializes the object using the provided String value.Note that this method uses the default string encoding and the default null termination behavior.

Parameters:

input - String the object is initialized with.

Returns:

this Pointer of the object

TSS Spec. 1.2 Errata A, page number:

230

newStringASCII

public static TcBlobData newStringASCII(String input)

Initializes the object using the provided String value. As encoding scheme, ASCII is used. No null termination character is added. This method is a convenience method and is intended to be used if e.g. the Ownership password has been set using C command line tools which do not use UNICODE strings. Note that this method uses the default null termination behavior.

Parameters:

input - String the object is initialized with.

Returns:

this Pointer of the object

newBlobData

public static TcBlobData newBlobData(TcBlobData other)

This method takes another TcBlobData object and copies its contents to this object (i.e. Copy Constructor).

Parameters:

other - Other BlobData object this object is initialized with.

Returns:

this Pointer of the object

overrideByteOrder

public void overrideByteOrder(byte byteOrder)

This method allows to override the default byte order used when parsing mutli-byte types into a byte array.

Parameters:

byteOrder - The byte order to the used.

overrideStringEncoding

public void overrideStringEncoding(String encoding)

This method allows to override the string encoding scheme that is used when interpreting the data held by the object.

Parameters:

encoding - The string encoding scheme used for interpreting the objects data.

overrideStringIsNullTerminated

public void overrideStringIsNullTerminated(boolean isNullTerminated)

This method allows to override the internal flag indicating if the contained string data is null terminated or not. This method is expected to be rarely used by developers. The only case where this function might be required is if the objects as initialized with string data using other methods than the initString methods (e.g. initByteArray). In such a case, this method allows to define if the binary data (if treated as a string) is null terminated or not.

Parameters:

isNullTerminated - The null termination state for the data.

getByteOrder

public byte getByteOrder()

This method returns the byte order used when converting UINT16 and UINT32 types to byte blobs.

Returns:

byte order used for UINT16 and UINT32

initStringASCII

public TcBlobData initStringASCII(String input)

Initializes the object using the provided String value. As encoding scheme, ASCII is used. No null termination character is added. This method is a convenience method and is intended to be used if e.g. the Ownership password has been set using C command line tools which do not use UNICODE strings. Note that this method uses the default null termination behavior.

Parameters:

input - String the object is initialized with.

Returns:

this Pointer of the object

append

public void append(TcBlobData dataToAppend)

This method is used to append binary data to the current binary data block.

Parameters:

dataToAppend - data to be appended to the current block

prepend

public void prepend(TcBlobData dataToPrepend)

This method is used to prepend binary data to the current binary data block.

Parameters:

dataToPrepend - data to be prepended to the current block

getElement

public byte getElement(int index)

This method returns the byte value at the given position.

Parameters:

index - the index of the element to be returned.

Returns:

the value at index

getLength

public int getLength()

This method returns the length of the binary data.

Returns:

the length of the binary data

getLengthAsLong

public long getLengthAsLong()

This method returns the length of the binary data.

Returns:

the length of the binary data

getRange

public byte[] getRange(int index,
                       int numElements)

This method returns a specified range of elements.

Parameters:

index - first element to be returned

numElements - number of elements to be returned

Returns:

byte array containing the specified range of elements (note: array elements are signed)

getRangeAsShortArray

public short[] getRangeAsShortArray(int index,
                                    int numElements)

This method returns a specified range of elements. In contrast to the getRange method, this method returns a short array where each (short) element holds an unsigned byte (in contrast to signed byte in case of the getRange method). I.e. only the range from 0 to 255 of every short element is actually used. This method is provided for convenience.

Parameters:

index - first element to be returned

numElements - number of elements to be returned

Returns:

short array containing the specified range of elements (note: array elements are unsigned)

asByteArray

public byte[] asByteArray()

This method returns the entire binary data as a byte array. Note that in contrast to the original C data where the individual array elements are unsigned bytes, the Java byte type is always signed.

Returns:

byte array containing the binary data.

asShortArray

public short[] asShortArray()

This method returns the entire binary data as a short array. This method returns the same content as the asByteArray method but encoded the individual bytes as shorts. The shorts only contain non negative values. This representation does not require the user to take care of the signedness of the byte data type in Java. The returned array contains the same data (regarding signedness) as the actual unsigned char array in C. This method is provided for convenience.

Returns:

short array containing the binary data.

substBytes

public void substBytes(int offset,
                       byte[] data)

This method allows to substitute a contiguous range of bytes in the byte blob.

Parameters:

offset - The offset where the substitution starts.

data - The data to be substituted into the blob.

sha1

public TcBlobData sha1()

This method returns the SHA-1 digest of the contained binary data.

Returns:

SHA-1 digest of the contained binary data

Throws:

NoSuchAlgorithmException

hmacSha1

public TcBlobData hmacSha1(TcBlobData key)

This method returns the HmacSha1 digest of the object's data using the given HMAC key.

Parameters:

key - The key used for the HMAC calculation.

Returns:

The HmacSha1 digest of the data.

Throws:

TcTssException - This exception is thrown if the provided key is invalid.

xor

public TcBlobData xor(TcBlobData key)

This method returns the object's data in XOR encrypted form using the provided key.

flush

public void flush()

Flushes the internal buffer by filling it with 0. Use this for TcBlobData instances that represent passwords to clear the password from memory.

equals

public boolean equals(Object obj)

This method checks if two objects are equal. It compares the entire internal state of the objects and not only the binary data.

Overrides:

equals in class Object

Returns:

true if the two objects have the same internal state

hashCode

public int hashCode()

Overrides:

hashCode in class Object

clone

public Object clone()

This method returns a clone of the object.

Overrides:

clone in class Object

toHexString

public String toHexString()

Returns a hex string representation of the object's binary data.

toHexStringNoWrap

public String toHexStringNoWrap()

stringIsNullTerminated

public boolean stringIsNullTerminated()

This method returns true if the contained string data is null terminated, false otherwise. Note that this method is only guaranteed to return correct values if the string was initialized using one of the initString methods. If the string was set any other way (e.g. as a byte array) incorrect values might be reported by this method.

toggleNullTermination

public void toggleNullTermination()

This method appends or removes the null termination character of the contained data based on the current state of the stringIsNullTerminated_ flag.

invalidateContent

public void invalidateContent()

This method overwrites the data held internally by the object with all zeros. This can be useful if the blob held sensitive information that is no longer used.

toString

public String toString()

Returns a string representation of the object's binary data. The string is encoded according to the internal stringEncoding.

Overrides:

toString in class Object

toStringASCII

public String toStringASCII()

Returns a string representation of the object's binary data. The string is assumed to be ASCII encoded.