javacardx.framework.tlv

Class BERTLV

java.lang.Object

javacardx.framework.tlv.BERTLV

Direct Known Subclasses:

ConstructedBERTLV, PrimitiveBERTLV

public abstract class BERTLV
extends Object

The abstract BERTLV class encapsulates a BER TLV structure. The rules on the allowed encoding of the Tag, length and value fields are based on the ASN.1 BER encoding rules ISO/IEC 8825-1:2002.

The BERTLV class and the subclasses - ConstructedBERTLV and PrimitiveBERTLV only support encoding of the length(L) octets in definite form. These classes do not provide support for the encoding rules of the contents octets of the value(V) field as described in ISO/IEC 8825-1:2002.

The BERTLV class and the subclasses - ConstructedBERTLV and PrimitiveBERTLV also provide static methods to parse/edit a TLV structure representation in a byte array.

Since:

2.2.2

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	BERTLV() Constructor creates an empty BERTLV object capable of encapsulating a BER TLV structure.

Method Summary

Methods

Modifier and Type	Method and Description
static BERTLV	getInstance(byte[] bArray, short bOff, short bLen) Creates the BERTLV using the input binary data.
short	getLength() Returns the value of this TLV object's Length component
static short	getLength(byte[] berTLVArray, short bOff) Returns the value of the TLV Structure's Length component in the specified input byte array
BERTag	getTag() Returns this value of the TLV object's Tag component
static short	getTag(byte[] berTLVArray, short bTLVOff, byte[] berTagArray, short bTagOff) Copies the tag component in the TLV representation in the specified input byte array to the specified output byte array
abstract short	init(byte[] bArray, short bOff, short bLen) Abstract init method.
short	size() Returns the number of bytes required to represent this TLV structure
short	toBytes(byte[] outBuf, short bOff) Writes this TLV structure to the specified byte array.
static boolean	verifyFormat(byte[] berTlvArray, short bOff, short bLen) Checks if the input data is a well-formed BER TLV representation.

Methods inherited from class java.lang.Object

equals

Constructor Detail

BERTLV

protected BERTLV()

Constructor creates an empty BERTLV object capable of encapsulating a BER TLV structure.

Method Detail

init

public abstract short init(byte[] bArray,
         short bOff,
         short bLen)
                    throws TLVException

Abstract init method. (Re-)Initializes this BERTLV using the input byte data.

The capacity of this BERTLV is increased, if required and supported, based on the size of the input TLV data structure.

Note:

• If bOff+bLen is greater than bArray.length, the length of the bArray array, an ArrayIndexOutOfBoundsException exception is thrown.

Parameters:

bArray - input byte array

bOff - offset within byte array containing the TLV data

bLen - byte length of input data

Returns:

the resulting size of this TLV if represented in bytes

Throws:

ArrayIndexOutOfBoundsException - if accessing the input array would cause access of data outside array bounds, or if the array offset or array length parameter is negative

NullPointerException - if bArray is null

TLVException - with the following reason codes:

• TLVException.INSUFFICIENT_STORAGE if the required capacity is not available and the implementation does not support automatic expansion.
• TLVException.MALFORMED_TLV if the input data is not a well-formed BER TLV or the input data represents a primitive BER TLV structure and this is a ConstructedBERTLV object or the input data represents a constructed BER TLV structure and this is a PrimiitveBERTLV object.

getInstance

public static BERTLV getInstance(byte[] bArray,
                 short bOff,
                 short bLen)
                          throws TLVException

Creates the BERTLV using the input binary data. The resulting BER TLV object may be a primitive or a constructed TLV object. The object must be cast to the correct sub-class: ConstructedBERTLV or PrimitiveBERTLV to access the specialized API. The init( byte[] bArray, short bOff, short bLen ) methods of the appropriate BERTLV classes will be used to initialize the created TLV object.

Note:

• If bOff+bLen is greater than bArray.length, the length of the bArray array, an ArrayIndexOutOfBoundsException exception is thrown.

Parameters:

bArray - input byte array

bOff - offset within byte array containing the tlv data

bLen - byte length of input data

Throws:

ArrayIndexOutOfBoundsException - if accessing the input array would cause access of data outside array bounds, or if the array offset or array length parameter is negative

NullPointerException - if bArray is null

TLVException - with the following reason codes:

• TLVException.ILLEGAL_SIZE if the TLV structure requested is larger than the supported maximum size
• TLVException.MALFORMED_TLV if the input data is not a well-formed BER TLV.

toBytes

public short toBytes(byte[] outBuf,
            short bOff)

Writes this TLV structure to the specified byte array.

Parameters:

outBuf - output byte array

bOff - offset within byte array output data begins

Returns:

the byte length written to the output array

Throws:

ArrayIndexOutOfBoundsException - if accessing the output array would cause access of data outside array bounds, or if the array offset parameter is negative

NullPointerException - if outBuf is null

TLVException - with the following reason codes:

• TLVException.TLV_SIZE_GREATER_THAN_32767 if the size of the BER TLV is > 32767.
• TLVException.EMPTY_TLV if the BERTLV object is empty.

getTag

public BERTag getTag()
              throws TLVException

Returns this value of the TLV object's Tag component

Returns:

the Tag for this BERTLV object

Throws:

TLVException - with the following reason codes:

• TLVException.EMPTY_TLV if the BERTLV object is empty.

getLength

public short getLength()
                throws TLVException

Returns the value of this TLV object's Length component

Throws:

TLVException - with the following reason codes:

• TLVException.TLV_LENGTH_GREATER_THAN_32767 if the value of the Length component is > 32767.
• TLVException.EMPTY_TLV if the BERTLV object is empty.

size

public short size()

Returns the number of bytes required to represent this TLV structure

Returns:

the byte length of the TLV

Throws:

TLVException - with the following reason codes:

• TLVException.TLV_SIZE_GREATER_THAN_32767 if the size of TLV structure is > 32767.
• TLVException.EMPTY_TLV if the BERTLV object is empty.

verifyFormat

public static boolean verifyFormat(byte[] berTlvArray,
                   short bOff,
                   short bLen)

Checks if the input data is a well-formed BER TLV representation.

Note:

• If bOff+bLen is greater than berTlvArray.length, the length of the berTlvArray array, an ArrayIndexOutOfBoundsException exception is thrown.

Parameters:

berTlvArray - input byte array

bOff - offset within byte array containing first byte

bLen - byte length of input BER TLV data

Returns:

true if input data is a well formed BER TLV structure, false otherwise

Throws:

ArrayIndexOutOfBoundsException - if accessing the input array would cause access of data outside array bounds, or if the array offset or array length parameter is negative

NullPointerException - if berTlvArray is null

getTag

public static short getTag(byte[] berTLVArray,
           short bTLVOff,
           byte[] berTagArray,
           short bTagOff)
                    throws TLVException

Copies the tag component in the TLV representation in the specified input byte array to the specified output byte array

Parameters:

berTLVArray - input byte array

bTLVOff - offset within byte array containing the tlv data

berTagArray - output Tag byte array

bTagOff - offset within byte array where output begins

Returns:

the size of the output BER Tag

Throws:

ArrayIndexOutOfBoundsException - if accessing the input or output array would cause access of data outside array bounds, or if either array offset parameter is negative

NullPointerException - if either berTLVArray or berTagArray is null

TLVException - with the following reason codes:

• TLVException.ILLEGAL_SIZE if the size of the Tag component is > 32767.
• TLVException.MALFORMED_TLV if the input data is not a well-formed BER TLV.

getLength

public static short getLength(byte[] berTLVArray,
              short bOff)
                       throws TLVException

Returns the value of the TLV Structure's Length component in the specified input byte array

Parameters:

berTLVArray - input byte array

bOff - offset within byte array containing the tlv data

Returns:

the length value in the TLV representation in the specified byte array

Throws:

ArrayIndexOutOfBoundsException - if accessing the input array would cause access of data outside array bounds, or if the array offset parameter is negative

NullPointerException - if berTLVArray

TLVException - with the following reason codes:

• TLVException.TLV_LENGTH_GREATER_THAN_32767 if the length element(L) > 32767.
• TLVException.MALFORMED_TLV if the input data is not a well-formed BER TLV.