Package com.oss.util

Class BERTool

java.lang.Object

com.oss.util.BERTool

public class BERTool
extends Object

BERTool is an OSS Type-Length-Value(TLV) Print Utility and a nested utility class suite.

DESCRIPTION

The OSS TLV Print Utility is run by invoking the BERTool class as a Java application. It reads a BER, DER, or CER encoding in ASCII or binary format from an input file and writes it to an output file in one of the four different type-length-value (TLV) formats. All BER references below apply to DER and CER as well.

BER encodings can be printed in any of the following formats: hexadecimal-TLV, decomposed-TLV, syntax-TLV, or extendeddump-TLV. These formats are described under the "Description of TLV Formats" section.

OPTIONS

Keyword options, except -help, can be abbreviated to the fewest number of letters needed to uniquely identify them (e.g., -binary can be abbreviated -b).

 
     -binary infile    Input file, infile, contains a BER/DER encoding in
                       binary format. When infile is a dash (e.g., -b -),
                       the input is read from stdin. -binary is the default
                       input format when the input file name is specified without
                       being preceded by either the -binary or -text option.

     -text infile      Input file, infile, contains a BER/DER encoding in
                       hexadecimal format. When infile is a dash (e.g., -t -),
                       the input is read from stdin.

     +offset,num       Print a number of bytes, num, of a BER/DER encoding from
                       an input file starting from the offset position.

     -hexadecimal      Print a BER/DER encoding in hexadecimal-TLV format.
                       This is the default output format.

     -decomposed       Print a BER/DER encoding in decomposed-TLV format.
     
     -syntax           Print a BER/DER encoding in syntax-TLV format.
     
     -extendeddump            Print a BER/DER encoding in extendeddump-TLV format.

     -output outfile   The output will be written to the "outfile" file. The output
                       is written to stdout when the -output option is omitted.
                       When outfile is a dash (e.g., -o -), the output file
                       name is read from stdin.

     -noshort          Don't truncate output lines that would otherwise be
                       longer than a line. By default, such lines are
                       truncated to fit one line without wrapping.

     -notitles         Don't print the "Type", "Length", and "Contents" titles
                       when printing a BER encoding in syntax-TLV format.
                       By default, titles are printed.

     -help             Print help information.

     -pad <byte>       Skip padding areas between concatenated records
                       filled with <byte>s. <byte> represents a hex
                       number (e.g., 0x00 for hex 00, 0xFF for hex FF)
                       or a non-negative decimal number from 0 to 255
                       (e.g. 10 or 128).                       
                       
     Examples:

     NOTE: The osstlv.jar executable class library file is configured to run the
     BERTool Java application. In the examples below, the BERTool application
     is run using the "java -jar osstlv.jar <parameters>" command.

     1. Print the BER binary file, foo.dat, in hexadecimal-TLV format to
        out.txt without truncating output lines:

        java -jar osstlv.jar -b foo.dat -nos -o out.txt

     2. Print the BER text file, foo.txt, in syntax-TLV format to stdout
        without printing titles:

        java -jar osstlv.jar -t foo.txt -s -not
        
     3. Print the contents of the BER binary file, foo.dat, containing
        two concatenated records with padding zero bytes in hexadecimal
        format skipping padding bytes:

        java -jar osstlv.jar foo.dat -pad 0x00

           30 80
              A1 80
              00 00
           00 00

           Padding byte '0x00' detected, skipping 6 bytes ...

           

           Concatenated record #2 detected, printing ...

           30 80
              A1 80
              00 00
           00 00 

           Padding byte '0x00' detected, skipping 6 bytes ...
           

 
 

Description of TLV Formats

BER encodings can be printed in any of the following formats:

 
     - Hexadecimal-TLV
     - Decomposed-TLV
     - Syntax-TLV
     - Extendeddump-TLV

     1. The hexadecimal-TLV format allows a BER/DER encoding to be viewed in
        hexadecimal format with type, length, and value information separated
        from each other by a space or newline. All nested encodings are printed
        in an indented manner. Lengths of value 80 (hex) are not the true
        length of the value, but indicate that the encoding is indefinite
        in length, and that the occurrence of matching end-of-contents octets
        (00 00) indicates the end of the value.

        Example:

        Definite length encoding:

           30 2A
               30 06
                   02 01 0A
                   01 01 FF
               30 00
               30 1E
                   09 09 803509540A2BE520DF
                   17 11 3932303432333137343333342D30373030

        Indefinite length encoding:

           30 80
               30 80
                   02 01 0A
                   01 01 FF
                   00 00
               30 80
                   00 00
               30 80
                   09 09 803509540A2BE520DF
                   17 11 3932303432333137343333342D30373030
                   00 00
               00 00


     2. The decomposed-TLV format allows a BER/DER encoding to be viewed
        in a format that lends itself to post-processing. The structure
        of each output line is:

        <offset>:d=<lvl> hl=<head> l=<len> {prim | cons}: <type> :<contents>

        with the following meanings:

            offset   is the offset from the beginning of the file.

            lvl      is the level of nesting, 1 - for the outermost level.

            head     is the number of octets occupied by the header information
                     (type and length fields) of an encoding.  
                     
            len      is the decimal length of an encoding, -128 - for encodings
                     with an indefinite length.  

            type     is the built-in name of an ASN.1 type when the type
                     information contains a UNIVERSAL class, otherwise, it is the
                     tag class and number in brackets. The tag class is
                     printed only for the APPLICATION and PRIVATE classes;
                     it is not printed for context-specific classes. For
                     encodings with an indefinite length, "END-OF-CONTENTS" is
                     printed when the end of the current encoding is reached.
                     The type information is prefixed with either "prim:",
                     indicating that the type is a primitive one, or "cons:",
                     indicating that it is a constructed one (i.e., one that
                     contains zero or more types, lengths, and values nested
                     within).

            contents is the value component of the encoding. Its contents
                     are printed as a hexadecimal string.

        Example:

        Definite length encoding:

            0:d= 1 hl=2 l=  42 cons: SET
            2:d= 2 hl=2 l=   6 cons: SET
            4:d= 3 hl=2 l=   1 prim: INTEGER      :0A
            7:d= 3 hl=2 l=   1 prim: BOOLEAN      :FF
           10:d= 2 hl=2 l=   0 cons: SET
           12:d= 2 hl=2 l=  30 cons: SET
           14:d= 3 hl=2 l=   9 prim: REAL         :803509540A2BE520DF
           25:d= 3 hl=2 l=  17 prim: UTCTime      :3932303432333137343333342D30373030

        Indefinite length encoding:

            0:d= 1 hl=2 l=-128 cons: SET
            2:d= 2 hl=2 l=-128 cons: SET
            4:d= 3 hl=2 l=   1 prim: INTEGER      :0A
            7:d= 3 hl=2 l=   1 prim: BOOLEAN      :FF
           10:d= 3 hl=2 l=   0 prim: END-OF-CONTENTS
           12:d= 2 hl=2 l=-128 cons: SET
           14:d= 3 hl=2 l=   0 prim: END-OF-CONTENTS
           16:d= 2 hl=2 l=-128 cons: SET
           18:d= 3 hl=2 l=   9 prim: REAL         :803509540A2BE520DF
           29:d= 3 hl=2 l=  17 prim: UTCTime      :3932303432333137343333342D30373030
           48:d= 3 hl=2 l=   0 prim: END-OF-CONTENTS
           50:d= 2 hl=2 l=   0 prim: END-OF-CONTENTS


     3. The syntax-TLV format includes three fields: "Type", "Length",
        "Contents", similar to the format used in X.690 to show examples
        of encodings, where:

            Type     is the name of the ASN.1 type, if this information can be
                     determined, else the tag class and number of the encoding.

            Length   is the length of the encoding or "indef" for indefinite
                     length encodings.  

            Contents is the contents if the encoding is primitive, or empty
                     for constructed encodings.

        Example:

        Definite length encoding:

            Type         Length  Contents
            SET          42
                Type         Length  Contents
                SET          6
                     Type         Length  Contents
                     INTEGER      1       0A
                     BOOLEAN      1       FF
                SET          0
                SET          30
                    Type         Length  Contents
                    REAL         9       803509540A2BE520DF
                    UTCTime      17      3932303432333137343333342D30373030

        Indefinite length encoding:

            Type         Length  Contents
            SET          indef
                Type         Length  Contents
                SET          indef
                    Type         Length  Contents
                    INTEGER      1       0A
                    BOOLEAN      1       FF
                    END-OF-CONTENTS
                SET          indef
                             END-OF-CONTENTS
                SET          indef
                    Type         Length  Contents
                    REAL         9       803509540A2BE520DF
                    UTCTime      17      3932303432333137343333342D30373030
                    END-OF-CONTENTS
                END-OF-CONTENTS
                
     4. The Extendeddump-TLV format is similar to the hexadecimal memory dump. It includes 
        three fields separated by colons: file offset, encoding in hexadecimal,
        and encoding in ASCII. The Tag-Length and Contents parts are printed on
        separate lines. The ASCII representation for the Tag-Length part contains the
        character 'C' for constructed encodings and 'P' for primitive and 
        formatted tag and length.

     Example:

        Definite length encoding:

        0000 : 30 2A                               : C [UNIVERSAL 16] 42
        0002 : 30 06                               : C [UNIVERSAL 16] 6
        0004 : 02 01                               : P [UNIVERSAL 2] 1
        0006 : 0A                                  : .
        0007 : 01 01                               : P [UNIVERSAL 1] 1
        0009 : FF                                  : .
        0010 : 30 00                               : C [UNIVERSAL 16] 0
        0012 : 30 1E                               : C [UNIVERSAL 16] 30
        0014 : 09 09                               : P [UNIVERSAL 9] 9
        0016 : 80 35 09 54 0A 2B E5 20 DF          : .5.T.+. .
        0025 : 17 11                               : P [UNIVERSAL 23] 17
        0027 : 39 32 30 34 32 33 31 37 34 33 33 34 : 920423174334
        0039 : 2D 30 37 30 30                      : -0700
 
        Indefinite length encoding:

        0000 : 30 80                               : C [UNIVERSAL 16] indef
        0002 : 30 80                               : C [UNIVERSAL 16] indef
        0004 : 02 01                               : P [UNIVERSAL 2] 1
        0006 : 0A                                  : .
        0007 : 01 01                               : P [UNIVERSAL 1] 1
        0009 : FF                                  : .
        0010 : 00 00                               : END-OF-CONTENTS
        0012 : 30 80                               : C [UNIVERSAL 16] indef
        0014 : 00 00                               : END-OF-CONTENTS
        0016 : 30 80                               : C [UNIVERSAL 16] indef
        0018 : 09 09                               : P [UNIVERSAL 9] 9
        0020 : 80 35 09 54 0A 2B E5 20 DF          : .5.T.+. .
        0029 : 17 11                               : P [UNIVERSAL 23] 17
        0031 : 39 32 30 34 32 33 31 37 34 33 33 34 : 920423174334
        0043 : 2D 30 37 30 30                      : -0700
        0048 : 00 00                               : END-OF-CONTENTS
        0050 : 00 00                               : END-OF-CONTENTS
 
 
 
 

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	BERTool.BERException	Thrown when an error is detected in the BER encoded data.
static class	BERTool.BERReader	Provides the readTLV() method to read a complete BER encoding from an input stream and return it as an array of bytes.
static class	BERTool.DecomposedBuilder	Implements a BER encoding dump in decomposed-TLV format.
static interface	BERTool.DumpBuilder	Defines methods that are invoked by the dumpTLV(ByteBuffer, DumpBuilder) BER parser.
static class	BERTool.ExtendedDumpBuilder	Implements a BER encoding dump in extended dump format.
static class	BERTool.HexBuilder	Implements a BER encoding dump in hexadecimal-TLV format.
static class	BERTool.SyntaxBuilder	Implements a BER encoding dump in syntax-TLV format.
static class	BERTool.Tag	Represents BER tags.
static enum	BERTool.TagClass	Represents BER tag class values as Java enumeration objects.
static class	BERTool.TLV	Represents a BER encoding as a TAG, LENGTH, and VALUE triple.
static class	BERTool.TLVDumpException	Thrown by the TLVDump.dumpTLV() method in case of unexpected end of data.
static enum	BERTool.ValueType	Represents BER universal tag numbers as Java enumeration objects.

Constructor Summary

Constructors

Constructor	Description
BERTool()

Method Summary

Modifier and Type	Method	Description
static void	dumpTLV(ByteBuffer source, BERTool.DumpBuilder sink)	Parses a BER encoding in a byte buffer and invokes dump builder object methods.
static int	getDefaultIndentWidth()	Gets the width of an indentation level.
static int	getDefaultTruncationLimit()	Gets the truncation limit for long contents strings.
static void	main(String[] args)	Runs the OSS Type-Length-Value(TLV) Print Utility.
static void	resetDefaults()	Resets class wide defaults to built-in values.
static void	setDefaultIndentWidth(int width)	Specifies the value for the indent width.
static void	setDefaultTruncationLimit(int limit)	Specifies the value for the truncation limit that will be used to truncate long contents strings.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Details

BERTool

public BERTool()

Method Details

getDefaultIndentWidth

public static int getDefaultIndentWidth()

Gets the width of an indentation level.

Returns:

the setting for the indent width.

setDefaultIndentWidth

public static void setDefaultIndentWidth(int width)

Specifies the value for the indent width.

Parameters:

width - the indent width to be used by the BER printing utility.

getDefaultTruncationLimit

public static int getDefaultTruncationLimit()

Gets the truncation limit for long contents strings.

Returns:

the setting for the truncation limit.

setDefaultTruncationLimit

public static void setDefaultTruncationLimit(int limit)

Specifies the value for the truncation limit that will be used to truncate long contents strings.

Parameters:

limit - the truncation limit to be used by the BER printing utility.

resetDefaults

public static void resetDefaults()

Resets class wide defaults to built-in values. The current built-in defaults are:

1. indent width - 4,
2. truncation limit - 35.

dumpTLV

public static void dumpTLV(ByteBuffer source,
 BERTool.DumpBuilder sink)

Parses a BER encoding in a byte buffer and invokes dump builder object methods.

Parameters:

source - the byte buffer that contains a BER encoding.

sink - the dump builder object that is used by the parser to report the elements of an encoding.

main

public static void main(String[] args)
                 throws IOException

Runs the OSS Type-Length-Value(TLV) Print Utility.

Parameters:

args - the command-line parameters.

Throws:

IOException - when an input/output error occurs.