Lev Walkin | c6080fd | 2016-01-23 06:35:34 -0800 | [diff] [blame] | 1 | .\" Automatically generated by Pandoc 1.16.0.2 |
| 2 | .\" |
| 3 | .ad l |
| 4 | .TH "unber" "1" "2016\-01\-23" "ASN.1 BER Decoder" "Version 0.9.28" |
| 5 | .nh \" Turn off hyphenation by default. |
| 6 | .SH NAME |
| 7 | .PP |
| 8 | unber \-\- the ASN.1 BER Decoder |
| 9 | .SH SYNOPSIS |
| 10 | .PP |
| 11 | unber [\f[B]\-1\f[]] [\f[B]\-i\f[]\f[I]indent\f[]] [\f[B]\-m\f[]] |
| 12 | [\f[B]\-p\f[]] [\f[B]\-s\f[]\f[I]skip\f[]] |
| 13 | [\f[B]\-t\f[]\f[I]hex\-string\f[]] [\f[B]\-\f[]] |
| 14 | [\f[I]input\-filenames\f[]...] |
| 15 | .SH DESCRIPTION |
| 16 | .PP |
| 17 | unber presents the internal structure of BER\-encoded files as a human |
| 18 | readable text. |
| 19 | A single dash denotes the standard input. |
| 20 | .PP |
| 21 | (The DER and CER formats are subsets of the BER and are also supported.) |
| 22 | .SH OPTIONS |
| 23 | .TP |
| 24 | .B \-1 |
| 25 | Do \f[I]not\f[] attempt to read the next BER structure after the first |
| 26 | one. |
| 27 | This may be useful if the input contains garbage past the single BER |
| 28 | sequence. |
| 29 | By default, unber continues decoding until the end of file (input |
| 30 | stream). |
| 31 | .RS |
| 32 | .RE |
| 33 | .TP |
| 34 | .B \-i \f[I]indent\f[] |
| 35 | Use the specified number of spaces for output indentation. |
| 36 | Default is 4 spaces. |
| 37 | .RS |
| 38 | .RE |
| 39 | .TP |
| 40 | .B \-m |
| 41 | Generate shorter output while still preserving BER encoding information. |
| 42 | .RS |
| 43 | .RE |
| 44 | .TP |
| 45 | .B \-p |
| 46 | Do \f[I]not\f[] attempt to pretty\-print known ASN.1 types |
| 47 | (\f[C]BOOLEAN\f[], \f[C]INTEGER\f[], \f[C]OBJECT\ IDENTIFIER\f[], etc). |
| 48 | By default, some ASN.1 types are converted into the text representation. |
| 49 | .RS |
| 50 | .PP |
| 51 | This option is required if the \f[C]unber\f[](1) output is used as an |
| 52 | input to \f[C]enber\f[](1). |
| 53 | .RE |
| 54 | .TP |
| 55 | .B \-s \f[I]skip\f[] |
| 56 | Ignore the first \f[I]skip\f[] bytes in the input stream; useful for |
| 57 | stripping off lower level protocol framing data. |
| 58 | .RS |
| 59 | .RE |
| 60 | .TP |
| 61 | .B \-t \f[I]hex\-string\f[] |
| 62 | Interpret the hex\-string as a sequence of hexadecimal values |
| 63 | representing the start of BER TLV encoding. |
| 64 | Print the human readable explanation. |
| 65 | .RS |
| 66 | .RE |
| 67 | .SH XML FORMAT |
| 68 | .PP |
| 69 | unber dumps the output in the regular XML format which preserves most of |
| 70 | the information from the underlying binary encoding. |
| 71 | .PP |
| 72 | The XML opening tag format is as follows: |
| 73 | .PP |
| 74 | <\f[B]tform\f[] O="\f[B]off\f[]" T="\f[B]tag\f[]" TL="\f[B]t_len\f[]" |
| 75 | V="{Indefinite|\f[B]v_len\f[]}" [A="\f[B]type\f[]"] [\f[B]F\f[]]> |
| 76 | .PP |
| 77 | Where: |
| 78 | .TP |
| 79 | .B \f[B]tform\f[] |
| 80 | Encoding form the value is in: primitive ("P") or constructed ("C") or |
| 81 | constructed with indefinite length ("I") |
| 82 | .RS |
| 83 | .RE |
| 84 | .TP |
| 85 | .B \f[B]off\f[] |
| 86 | Offset of the encoded element in the unber input stream. |
| 87 | .RS |
| 88 | .RE |
| 89 | .TP |
| 90 | .B \f[B]tag\f[] |
| 91 | The tag class and value in human readable form. |
| 92 | .RS |
| 93 | .RE |
| 94 | .TP |
| 95 | .B \f[B]t_len\f[] |
| 96 | The length of the TL (BER Tag and Length) encoding. |
| 97 | .RS |
| 98 | .RE |
| 99 | .TP |
| 100 | .B \f[B]v_len\f[] |
| 101 | The length of the value (V, encoded by the L), may be "Indefinite". |
| 102 | .RS |
| 103 | .RE |
| 104 | .TP |
| 105 | .B \f[B]type\f[] |
| 106 | Likely name of the underlying ASN.1 type (for UNIVERSAL tags). |
| 107 | .RS |
| 108 | .RE |
| 109 | .TP |
| 110 | .B [\f[B]F\f[]] |
| 111 | Indicates that the value was reformatted (pretty\-printed). |
| 112 | This will never appear in the output produced using the \f[B]\-p\f[] |
| 113 | command line option. |
| 114 | .RS |
| 115 | .RE |
| 116 | .SS Example XML output: |
| 117 | .PP |
| 118 | <I O="0" T="[UNIVERSAL 16]" TL="2" V="Indefinite" A="SEQUENCE"> |
| 119 | .PD 0 |
| 120 | .P |
| 121 | .PD |
| 122 | \ <P O="2" T="[UNIVERSAL 19]" TL="2" V="2" A="PrintableString">US</P> |
| 123 | .PD 0 |
| 124 | .P |
| 125 | .PD |
| 126 | \ \ <C O="6" T="[UNIVERSAL 16]" TL="2" V="6" A="SEQUENCE"> |
| 127 | .PD 0 |
| 128 | .P |
| 129 | .PD |
| 130 | \ \ \ \ <P O="8" T="[UNIVERSAL 2]" TL="2" V="4" A="INTEGER" |
| 131 | F>832970823</P> |
| 132 | .PD 0 |
| 133 | .P |
| 134 | .PD |
| 135 | \ \ </C O="14" T="[UNIVERSAL 16]" A="SEQUENCE" L="8"> |
| 136 | .PD 0 |
| 137 | .P |
| 138 | .PD |
| 139 | </I O="14" T="[UNIVERSAL 0]" TL="2" L="16"> |
| 140 | .SH EXAMPLES |
| 141 | .PP |
| 142 | Decode the given Tag/Length sequence specified in hexadecimal form: |
| 143 | .RS |
| 144 | .PP |
| 145 | unber\ \f[B]\-t\f[] "\f[I]bf 20\f[]" |
| 146 | .RE |
| 147 | .PP |
| 148 | Decode the DER file using two\-spaces indentation: |
| 149 | .RS |
| 150 | .PP |
| 151 | unber\ \f[B]\-i\f[] \f[I]2\f[]\ \f[I]filename.der\f[] |
| 152 | .RE |
| 153 | .PP |
| 154 | Decode the binary stream taken from the standard input: |
| 155 | .RS |
| 156 | .PP |
| 157 | cat \f[I]filename.der\f[] | unber \f[B]\-\f[] |
| 158 | .RE |
| 159 | .PP |
| 160 | Decode the binary stream and encode it back into an identical stream |
| 161 | (see \f[C]enber\f[](1)): |
| 162 | .RS |
| 163 | .PP |
| 164 | cat \f[I]filename.der\f[] | unber \f[B]\-p\f[] \f[B]\-\f[] | enber |
| 165 | \f[B]\-\f[] > \f[I]filename.ber\f[] |
| 166 | .RE |
| 167 | .SH FOOTNOTES |
| 168 | .PP |
| 169 | The constructed XML output is not necessarily well\-formed. |
| 170 | .PP |
| 171 | When indefinite length encoding is being used, the BER sequence which is |
| 172 | not terminated with the end\-of\-content octets will cause the |
| 173 | terminating \f[B]</I>\f[] XML tag to disappear. |
| 174 | Thus, invalid BER framing directly causes invalid XML output. |
| 175 | .PP |
| 176 | The \f[C]enber\f[](1) utility understands such XML correctly. |
| 177 | .SH SEE ALSO |
| 178 | .PP |
| 179 | \f[C]enber\f[](1), \f[C]asn1c\f[](1). |
| 180 | .SH AUTHORS |
| 181 | Lev Walkin <vlm@lionet.info>. |