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
    Description
    protected
    BERTLV()
    Constructor creates an empty BERTLV object capable of encapsulating a BER TLV structure.

  • Method Summary

    Modifier and Type
    Method
    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 Object

    equals
    Modifier and Type
    Method
    Description
    boolean
    equals(Object obj)
    Compares two Objects for equality.

  • Constructor Details

    • BERTLV

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

  • Method Details

    • 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
      Returns:
      the BERTLV object instance
      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
      Returns:
      the value length of the TLV
      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.