asn1parse.pod revision 325337 
1=pod
2
3=head1 NAME
4
5openssl-asn1parse,
6asn1parse - ASN.1 parsing tool
7
8=head1 SYNOPSIS
9
10B<openssl> B<asn1parse>
11[B<-inform PEM|DER>]
12[B<-in filename>]
13[B<-out filename>]
14[B<-noout>]
15[B<-offset number>]
16[B<-length number>]
17[B<-i>]
18[B<-oid filename>]
19[B<-dump>]
20[B<-dlimit num>]
21[B<-strparse offset>]
22[B<-genstr string>]
23[B<-genconf file>]
24
25=head1 DESCRIPTION
26
27The B<asn1parse> command is a diagnostic utility that can parse ASN.1
28structures. It can also be used to extract data from ASN.1 formatted data.
29
30=head1 OPTIONS
31
32=over 4
33
34=item B<-inform> B<DER|PEM>
35
36the input format. B<DER> is binary format and B<PEM> (the default) is base64
37encoded.
38
39=item B<-in filename>
40
41the input file, default is standard input
42
43=item B<-out filename>
44
45output file to place the DER encoded data into. If this
46option is not present then no data will be output. This is most useful when
47combined with the B<-strparse> option.
48
49=item B<-noout>
50
51don't output the parsed version of the input file.
52
53=item B<-offset number>
54
55starting offset to begin parsing, default is start of file.
56
57=item B<-length number>
58
59number of bytes to parse, default is until end of file.
60
61=item B<-i>
62
63indents the output according to the "depth" of the structures.
64
65=item B<-oid filename>
66
67a file containing additional OBJECT IDENTIFIERs (OIDs). The format of this
68file is described in the NOTES section below.
69
70=item B<-dump>
71
72dump unknown data in hex format.
73
74=item B<-dlimit num>
75
76like B<-dump>, but only the first B<num> bytes are output.
77
78=item B<-strparse offset>
79
80parse the contents octets of the ASN.1 object starting at B<offset>. This
81option can be used multiple times to "drill down" into a nested structure.
82
83=item B<-genstr string>, B<-genconf file>
84
85generate encoded data based on B<string>, B<file> or both using
86L<ASN1_generate_nconf(3)|ASN1_generate_nconf(3)> format. If B<file> only is
87present then the string is obtained from the default section using the name
88B<asn1>. The encoded data is passed through the ASN1 parser and printed out as
89though it came from a file, the contents can thus be examined and written to a
90file using the B<out> option. 
91
92=back
93
94=head2 OUTPUT
95
96The output will typically contain lines like this:
97
98  0:d=0  hl=4 l= 681 cons: SEQUENCE          
99
100.....
101
102  229:d=3  hl=3 l= 141 prim: BIT STRING        
103  373:d=2  hl=3 l= 162 cons: cont [ 3 ]        
104  376:d=3  hl=3 l= 159 cons: SEQUENCE          
105  379:d=4  hl=2 l=  29 cons: SEQUENCE          
106  381:d=5  hl=2 l=   3 prim: OBJECT            :X509v3 Subject Key Identifier
107  386:d=5  hl=2 l=  22 prim: OCTET STRING      
108  410:d=4  hl=2 l= 112 cons: SEQUENCE          
109  412:d=5  hl=2 l=   3 prim: OBJECT            :X509v3 Authority Key Identifier
110  417:d=5  hl=2 l= 105 prim: OCTET STRING      
111  524:d=4  hl=2 l=  12 cons: SEQUENCE          
112
113.....
114
115This example is part of a self signed certificate. Each line starts with the
116offset in decimal. B<d=XX> specifies the current depth. The depth is increased
117within the scope of any SET or SEQUENCE. B<hl=XX> gives the header length
118(tag and length octets) of the current type. B<l=XX> gives the length of
119the contents octets.
120
121The B<-i> option can be used to make the output more readable.
122
123Some knowledge of the ASN.1 structure is needed to interpret the output. 
124
125In this example the BIT STRING at offset 229 is the certificate public key.
126The contents octets of this will contain the public key information. This can
127be examined using the option B<-strparse 229> to yield:
128
129    0:d=0  hl=3 l= 137 cons: SEQUENCE          
130    3:d=1  hl=3 l= 129 prim: INTEGER           :E5D21E1F5C8D208EA7A2166C7FAF9F6BDF2059669C60876DDB70840F1A5AAFA59699FE471F379F1DD6A487E7D5409AB6A88D4A9746E24B91D8CF55DB3521015460C8EDE44EE8A4189F7A7BE77D6CD3A9AF2696F486855CF58BF0EDF2B4068058C7A947F52548DDF7E15E96B385F86422BEA9064A3EE9E1158A56E4A6F47E5897
131  135:d=1  hl=2 l=   3 prim: INTEGER           :010001
132
133=head1 NOTES
134
135If an OID is not part of OpenSSL's internal table it will be represented in
136numerical form (for example 1.2.3.4). The file passed to the B<-oid> option 
137allows additional OIDs to be included. Each line consists of three columns,
138the first column is the OID in numerical format and should be followed by white
139space. The second column is the "short name" which is a single word followed
140by white space. The final column is the rest of the line and is the
141"long name". B<asn1parse> displays the long name. Example:
142
143C<1.2.3.4	shortName	A long name>
144
145=head1 EXAMPLES
146
147Parse a file:
148
149 openssl asn1parse -in file.pem
150
151Parse a DER file:
152
153 openssl asn1parse -inform DER -in file.der
154
155Generate a simple UTF8String:
156
157 openssl asn1parse -genstr 'UTF8:Hello World'
158
159Generate and write out a UTF8String, don't print parsed output:
160
161 openssl asn1parse -genstr 'UTF8:Hello World' -noout -out utf8.der
162
163Generate using a config file:
164
165 openssl asn1parse -genconf asn1.cnf -noout -out asn1.der
166
167Example config file:
168
169 asn1=SEQUENCE:seq_sect
170
171 [seq_sect]
172
173 field1=BOOL:TRUE
174 field2=EXP:0, UTF8:some random string
175
176
177=head1 BUGS
178
179There should be options to change the format of output lines. The output of some
180ASN.1 types is not well handled (if at all).
181
182=head1 SEE ALSO
183
184L<ASN1_generate_nconf(3)|ASN1_generate_nconf(3)>
185
186=cut
187