Class ASN1Buffer

  • All Implemented Interfaces:
    java.io.Serializable

    @Mutable
    @ThreadSafety(level=NOT_THREADSAFE)
    public final class ASN1Buffer
    extends java.lang.Object
    implements java.io.Serializable
    This class provides a mechanism for writing one or more ASN.1 elements into a byte string buffer. It may be cleared and re-used any number of times, and the contents may be written to an OutputStream or ByteBuffer, or copied to a byte array. ASN1Buffer instances are not threadsafe and should not be accessed concurrently by multiple threads.
    See Also:
    Serialized Form
    • Constructor Summary

      Constructors 
      Constructor Description
      ASN1Buffer()
      Creates a new instance of this ASN.1 buffer.
      ASN1Buffer​(int maxBufferSize)
      Creates a new instance of this ASN.1 buffer with an optional maximum retained size.
    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      void addBoolean​(boolean booleanValue)
      Adds a Boolean element to this ASN.1 buffer using the default BER type.
      void addBoolean​(byte type, boolean booleanValue)
      Adds a Boolean element to this ASN.1 buffer using the provided BER type.
      void addElement​(ASN1Element element)
      Adds the provided ASN.1 element to this ASN.1 buffer.
      void addEnumerated​(byte type, int intValue)
      Adds an enumerated element to this ASN.1 buffer using the provided BER type.
      void addEnumerated​(int intValue)
      Adds an enumerated element to this ASN.1 buffer using the default BER type.
      void addGeneralizedTime​(byte type, long time)
      Adds a generalized time element to this ASN.1 buffer using the provided BER type.
      void addGeneralizedTime​(byte type, java.util.Date date)
      Adds a generalized time element to this ASN.1 buffer using the provided BER type.
      void addGeneralizedTime​(long time)
      Adds a generalized time element to this ASN.1 buffer using the default BER type.
      void addGeneralizedTime​(java.util.Date date)
      Adds a generalized time element to this ASN.1 buffer using the default BER type.
      void addInteger​(byte type, int intValue)
      Adds an integer element to this ASN.1 buffer using the provided BER type.
      void addInteger​(byte type, long longValue)
      Adds an integer element to this ASN.1 buffer using the provided BER type.
      void addInteger​(byte type, java.math.BigInteger value)
      Adds an integer element to this ASN.1 buffer using the provided BER type.
      void addInteger​(int intValue)
      Adds an integer element to this ASN.1 buffer using the default BER type.
      void addInteger​(long longValue)
      Adds an integer element to this ASN.1 buffer using the default BER type.
      void addInteger​(java.math.BigInteger value)
      Adds an integer element to this ASN.1 buffer using the default BER type.
      void addNull()
      Adds a null element to this ASN.1 buffer using the default BER type.
      void addNull​(byte type)
      Adds a null element to this ASN.1 buffer using the provided BER type.
      void addOctetString()
      Adds an octet string element to this ASN.1 buffer using the default BER type and no value.
      void addOctetString​(byte type)
      Adds an octet string element to this ASN.1 buffer using the provided BER type and no value.
      void addOctetString​(byte[] value)
      Adds an octet string element to this ASN.1 buffer using the default BER type.
      void addOctetString​(byte type, byte[] value)
      Adds an octet string element to this ASN.1 buffer using the provided BER type.
      void addOctetString​(byte type, java.lang.CharSequence value)
      Adds an octet string element to this ASN.1 buffer using the provided BER type.
      void addOctetString​(byte type, java.lang.String value)
      Adds an octet string element to this ASN.1 buffer using the provided BER type.
      void addOctetString​(java.lang.CharSequence value)
      Adds an octet string element to this ASN.1 buffer using the default BER type.
      void addOctetString​(java.lang.String value)
      Adds an octet string element to this ASN.1 buffer using the default BER type.
      void addUTCTime​(byte type, long time)
      Adds a UTC time element to this ASN.1 buffer using the provided BER type.
      void addUTCTime​(byte type, java.util.Date date)
      Adds a UTC time element to this ASN.1 buffer using the provided BER type.
      void addUTCTime​(long time)
      Adds a UTC time element to this ASN.1 buffer using the default BER type.
      void addUTCTime​(java.util.Date date)
      Adds a UTC time element to this ASN.1 buffer using the default BER type.
      java.nio.ByteBuffer asByteBuffer()
      Retrieves a byte buffer that wraps the data associated with this ASN.1 buffer.
      ASN1BufferSequence beginSequence()
      Begins adding elements to an ASN.1 sequence using the default BER type.
      ASN1BufferSequence beginSequence​(byte type)
      Begins adding elements to an ASN.1 sequence using the provided BER type.
      ASN1BufferSet beginSet()
      Begins adding elements to an ASN.1 set using the default BER type.
      ASN1BufferSet beginSet​(byte type)
      Begins adding elements to an ASN.1 set using the provided BER type.
      void clear()
      Clears the contents of this buffer.
      int length()
      Retrieves the current length of this buffer in bytes.
      void setZeroBufferOnClear()
      Specifies that the content of the buffer should be zeroed out the next time it is cleared in order to wipe any sensitive information it may contain.
      byte[] toByteArray()
      Retrieves a byte array containing the contents of this ASN.1 buffer.
      void writeTo​(java.io.OutputStream outputStream)
      Writes the contents of this buffer to the provided output stream.
      boolean zeroBufferOnClear()
      Indicates whether the content of the buffer should be zeroed out the next time it is cleared in order to wipe any sensitive information it may contain.
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • Constructor Detail

      • ASN1Buffer

        public ASN1Buffer()
        Creates a new instance of this ASN.1 buffer.
      • ASN1Buffer

        public ASN1Buffer​(int maxBufferSize)
        Creates a new instance of this ASN.1 buffer with an optional maximum retained size. If a maximum size is defined, then this buffer may be used to hold elements larger than that, but when the buffer is cleared it will be shrunk to the maximum size.
        Parameters:
        maxBufferSize - The maximum buffer size that will be retained by this ASN.1 buffer. A value less than or equal to zero indicates that no maximum size should be enforced.
    • Method Detail

      • zeroBufferOnClear

        public boolean zeroBufferOnClear()
        Indicates whether the content of the buffer should be zeroed out the next time it is cleared in order to wipe any sensitive information it may contain.
        Returns:
        true if the content of the buffer should be zeroed out the next time it is cleared, or false if not.
      • setZeroBufferOnClear

        public void setZeroBufferOnClear()
        Specifies that the content of the buffer should be zeroed out the next time it is cleared in order to wipe any sensitive information it may contain.
      • clear

        public void clear()
        Clears the contents of this buffer. If there are any outstanding sequences or sets that have been created but not closed, then they must no longer be used and any attempt to do so may yield unpredictable results.
      • length

        public int length()
        Retrieves the current length of this buffer in bytes.
        Returns:
        The current length of this buffer in bytes.
      • addElement

        public void addElement​(ASN1Element element)
        Adds the provided ASN.1 element to this ASN.1 buffer.
        Parameters:
        element - The element to be added. It must not be null.
      • addBoolean

        public void addBoolean​(boolean booleanValue)
        Adds a Boolean element to this ASN.1 buffer using the default BER type.
        Parameters:
        booleanValue - The value to use for the Boolean element.
      • addBoolean

        public void addBoolean​(byte type,
                               boolean booleanValue)
        Adds a Boolean element to this ASN.1 buffer using the provided BER type.
        Parameters:
        type - The BER type to use for the Boolean element.
        booleanValue - The value to use for the Boolean element.
      • addEnumerated

        public void addEnumerated​(int intValue)
        Adds an enumerated element to this ASN.1 buffer using the default BER type.
        Parameters:
        intValue - The value to use for the enumerated element.
      • addEnumerated

        public void addEnumerated​(byte type,
                                  int intValue)
        Adds an enumerated element to this ASN.1 buffer using the provided BER type.
        Parameters:
        type - The BER type to use for the enumerated element.
        intValue - The value to use for the enumerated element.
      • addGeneralizedTime

        public void addGeneralizedTime​(java.util.Date date)
        Adds a generalized time element to this ASN.1 buffer using the default BER type.
        Parameters:
        date - The date value that specifies the time to represent. This must not be null.
      • addGeneralizedTime

        public void addGeneralizedTime​(byte type,
                                       java.util.Date date)
        Adds a generalized time element to this ASN.1 buffer using the provided BER type.
        Parameters:
        type - The BER type to use for the generalized time element.
        date - The date value that specifies the time to represent. This must not be null.
      • addGeneralizedTime

        public void addGeneralizedTime​(long time)
        Adds a generalized time element to this ASN.1 buffer using the default BER type.
        Parameters:
        time - The time to represent. This must be expressed in milliseconds since the epoch (the same format used by System.currentTimeMillis() and Date.getTime()).
      • addGeneralizedTime

        public void addGeneralizedTime​(byte type,
                                       long time)
        Adds a generalized time element to this ASN.1 buffer using the provided BER type.
        Parameters:
        type - The BER type to use for the generalized time element.
        time - The time to represent. This must be expressed in milliseconds since the epoch (the same format used by System.currentTimeMillis() and Date.getTime()).
      • addInteger

        public void addInteger​(int intValue)
        Adds an integer element to this ASN.1 buffer using the default BER type.
        Parameters:
        intValue - The value to use for the integer element.
      • addInteger

        public void addInteger​(byte type,
                               int intValue)
        Adds an integer element to this ASN.1 buffer using the provided BER type.
        Parameters:
        type - The BER type to use for the integer element.
        intValue - The value to use for the integer element.
      • addInteger

        public void addInteger​(long longValue)
        Adds an integer element to this ASN.1 buffer using the default BER type.
        Parameters:
        longValue - The value to use for the integer element.
      • addInteger

        public void addInteger​(byte type,
                               long longValue)
        Adds an integer element to this ASN.1 buffer using the provided BER type.
        Parameters:
        type - The BER type to use for the integer element.
        longValue - The value to use for the integer element.
      • addInteger

        public void addInteger​(java.math.BigInteger value)
        Adds an integer element to this ASN.1 buffer using the default BER type.
        Parameters:
        value - The value to use for the integer element. It must not be null.
      • addInteger

        public void addInteger​(byte type,
                               java.math.BigInteger value)
        Adds an integer element to this ASN.1 buffer using the provided BER type.
        Parameters:
        type - The BER type to use for the integer element.
        value - The value to use for the integer element. It must not be null.
      • addNull

        public void addNull()
        Adds a null element to this ASN.1 buffer using the default BER type.
      • addNull

        public void addNull​(byte type)
        Adds a null element to this ASN.1 buffer using the provided BER type.
        Parameters:
        type - The BER type to use for the null element.
      • addOctetString

        public void addOctetString()
        Adds an octet string element to this ASN.1 buffer using the default BER type and no value.
      • addOctetString

        public void addOctetString​(byte type)
        Adds an octet string element to this ASN.1 buffer using the provided BER type and no value.
        Parameters:
        type - The BER type to use for the octet string element.
      • addOctetString

        public void addOctetString​(byte[] value)
        Adds an octet string element to this ASN.1 buffer using the default BER type.
        Parameters:
        value - The value to use for the octet string element.
      • addOctetString

        public void addOctetString​(java.lang.CharSequence value)
        Adds an octet string element to this ASN.1 buffer using the default BER type.
        Parameters:
        value - The value to use for the octet string element.
      • addOctetString

        public void addOctetString​(java.lang.String value)
        Adds an octet string element to this ASN.1 buffer using the default BER type.
        Parameters:
        value - The value to use for the octet string element.
      • addOctetString

        public void addOctetString​(byte type,
                                   byte[] value)
        Adds an octet string element to this ASN.1 buffer using the provided BER type.
        Parameters:
        type - The BER type to use for the octet string element.
        value - The value to use for the octet string element.
      • addOctetString

        public void addOctetString​(byte type,
                                   java.lang.CharSequence value)
        Adds an octet string element to this ASN.1 buffer using the provided BER type.
        Parameters:
        type - The BER type to use for the octet string element.
        value - The value to use for the octet string element.
      • addOctetString

        public void addOctetString​(byte type,
                                   java.lang.String value)
        Adds an octet string element to this ASN.1 buffer using the provided BER type.
        Parameters:
        type - The BER type to use for the octet string element.
        value - The value to use for the octet string element.
      • addUTCTime

        public void addUTCTime​(java.util.Date date)
        Adds a UTC time element to this ASN.1 buffer using the default BER type.
        Parameters:
        date - The date value that specifies the time to represent. This must not be null.
      • addUTCTime

        public void addUTCTime​(byte type,
                               java.util.Date date)
        Adds a UTC time element to this ASN.1 buffer using the provided BER type.
        Parameters:
        type - The BER type to use for the UTC time element.
        date - The date value that specifies the time to represent. This must not be null.
      • addUTCTime

        public void addUTCTime​(long time)
        Adds a UTC time element to this ASN.1 buffer using the default BER type.
        Parameters:
        time - The time to represent. This must be expressed in milliseconds since the epoch (the same format used by System.currentTimeMillis() and Date.getTime()).
      • addUTCTime

        public void addUTCTime​(byte type,
                               long time)
        Adds a UTC time element to this ASN.1 buffer using the provided BER type.
        Parameters:
        type - The BER type to use for the UTC time element.
        time - The time to represent. This must be expressed in milliseconds since the epoch (the same format used by System.currentTimeMillis() and Date.getTime()).
      • beginSequence

        public ASN1BufferSequence beginSequence()
        Begins adding elements to an ASN.1 sequence using the default BER type.
        Returns:
        An object that may be used to indicate when the end of the sequence has been reached. Once all embedded sequence elements have been added, then the ASN1BufferSequence.end() method MUST be called to ensure that the sequence is properly encoded.
      • beginSequence

        public ASN1BufferSequence beginSequence​(byte type)
        Begins adding elements to an ASN.1 sequence using the provided BER type.
        Parameters:
        type - The BER type to use for the sequence.
        Returns:
        An object that may be used to indicate when the end of the sequence has been reached. Once all embedded sequence elements have been added, then the ASN1BufferSequence.end() method MUST be called to ensure that the sequence is properly encoded.
      • beginSet

        public ASN1BufferSet beginSet()
        Begins adding elements to an ASN.1 set using the default BER type.
        Returns:
        An object that may be used to indicate when the end of the set has been reached. Once all embedded set elements have been added, then the ASN1BufferSet.end() method MUST be called to ensure that the set is properly encoded.
      • beginSet

        public ASN1BufferSet beginSet​(byte type)
        Begins adding elements to an ASN.1 set using the provided BER type.
        Parameters:
        type - The BER type to use for the set.
        Returns:
        An object that may be used to indicate when the end of the set has been reached. Once all embedded set elements have been added, then the ASN1BufferSet.end() method MUST be called to ensure that the set is properly encoded.
      • writeTo

        public void writeTo​(java.io.OutputStream outputStream)
                     throws java.io.IOException
        Writes the contents of this buffer to the provided output stream.
        Parameters:
        outputStream - The output stream to which the data should be written.
        Throws:
        java.io.IOException - If a problem occurs while writing to the provided output stream.
      • toByteArray

        public byte[] toByteArray()
        Retrieves a byte array containing the contents of this ASN.1 buffer.
        Returns:
        A byte array containing the contents of this ASN.1 buffer.
      • asByteBuffer

        public java.nio.ByteBuffer asByteBuffer()
        Retrieves a byte buffer that wraps the data associated with this ASN.1 buffer. The position will be set to the beginning of the data, and the limit will be set to one byte after the end of the data. The contents of the returned byte buffer must not be altered in any way, and the contents of this ASN.1 buffer must not be altered until the ByteBuffer is no longer needed.
        Returns:
        A byte buffer that wraps the data associated with this ASN.1 buffer.