Gitiles
Code Review Sign In
gerrit.osmocom.org / asn1c / ed90e9ea2049050e608ecad00e6f2ce26b8918cd / . / doc / asn1c-usage.html
blob: 589e4273a13cfb4f1e6d38eeb61be0da9a3d990f [file] [log] [blame]
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]1
2<!--Converted with LaTeX2HTML 2002-2-1 (1.70)
3original version by: Nikos Drakos, CBLU, University of Leeds
4* revised and updated by: Marcus Hennecke, Ross Moore, Herb Swan
5* with significant contributions from:
6 Jens Lippmann, Marek Rouchal, Martin Wilck and others -->
7<HTML>
8<HEAD>
Lev Walkin71a8aaf2004-09-08 03:10:54 +0000[diff] [blame]9<TITLE>Using the Open ASN.1 Compiler</TITLE>
10<META NAME="description" CONTENT="Using the Open ASN.1 Compiler">
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]11<META NAME="asn1c, ASN.1, free, compiler, BER, DER, PER, XER\">
12
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]13
14
15</HEAD>
16
17<BODY >
18
19<P>
20
21<P>
22
23<P>
Lev Walkin71a8aaf2004-09-08 03:10:54 +0000[diff] [blame]24<H1 ALIGN="CENTER">Using the Open ASN.1 Compiler</H1><DIV>
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]25
26<P ALIGN="CENTER"><STRONG>Lev Walkin &lt;vlm@lionet.info&gt;</STRONG></P>
27</DIV>
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]28
29<P>
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]30<BR>
31
32<H2><A NAME="SECTION01000000000000000000">
33Contents</A>
34</H2>
35<!--Table of Contents-->
36
37<UL>
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]38<LI><A NAME="tex2html45"
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]39 HREF="asn1c-usage.html#SECTION02000000000000000000">ASN.1 Basics</A>
40<UL>
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]41<LI><A NAME="tex2html46"
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]42 HREF="asn1c-usage.html#SECTION02100000000000000000">Abstract Syntax Notation: ASN.1</A>
43<UL>
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]44<LI><A NAME="tex2html47"
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]45 HREF="asn1c-usage.html#SECTION02110000000000000000">Some of the ASN.1 Basic Types</A>
46<UL>
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]47<LI><A NAME="tex2html48"
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]48 HREF="asn1c-usage.html#SECTION02111000000000000000">The BOOLEAN type</A>
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]49<LI><A NAME="tex2html49"
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]50 HREF="asn1c-usage.html#SECTION02112000000000000000">The INTEGER type</A>
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]51<LI><A NAME="tex2html50"
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]52 HREF="asn1c-usage.html#SECTION02113000000000000000">The ENUMERATED type</A>
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]53<LI><A NAME="tex2html51"
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]54 HREF="asn1c-usage.html#SECTION02114000000000000000">The OCTET STRING type</A>
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]55<LI><A NAME="tex2html52"
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]56 HREF="asn1c-usage.html#SECTION02115000000000000000">The OBJECT IDENTIFIER type</A>
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]57<LI><A NAME="tex2html53"
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]58 HREF="asn1c-usage.html#SECTION02116000000000000000">The RELATIVE-OID type</A>
59</UL>
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]60<LI><A NAME="tex2html54"
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]61 HREF="asn1c-usage.html#SECTION02120000000000000000">Some of the ASN.1 String Types</A>
62<UL>
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]63<LI><A NAME="tex2html55"
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]64 HREF="asn1c-usage.html#SECTION02121000000000000000">The IA5String type</A>
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]65<LI><A NAME="tex2html56"
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]66 HREF="asn1c-usage.html#SECTION02122000000000000000">The UTF8String type</A>
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]67<LI><A NAME="tex2html57"
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]68 HREF="asn1c-usage.html#SECTION02123000000000000000">The NumericString type</A>
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]69<LI><A NAME="tex2html58"
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]70 HREF="asn1c-usage.html#SECTION02124000000000000000">The PrintableString type</A>
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]71<LI><A NAME="tex2html59"
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]72 HREF="asn1c-usage.html#SECTION02125000000000000000">The VisibleString type</A>
73</UL>
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]74<LI><A NAME="tex2html60"
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]75 HREF="asn1c-usage.html#SECTION02130000000000000000">ASN.1 Constructed Types</A>
76<UL>
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]77<LI><A NAME="tex2html61"
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]78 HREF="asn1c-usage.html#SECTION02131000000000000000">The SEQUENCE type</A>
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]79<LI><A NAME="tex2html62"
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]80 HREF="asn1c-usage.html#SECTION02132000000000000000">The SET type</A>
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]81<LI><A NAME="tex2html63"
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]82 HREF="asn1c-usage.html#SECTION02133000000000000000">The CHOICE type</A>
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]83<LI><A NAME="tex2html64"
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]84 HREF="asn1c-usage.html#SECTION02134000000000000000">The SEQUENCE OF type</A>
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]85<LI><A NAME="tex2html65"
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]86 HREF="asn1c-usage.html#SECTION02135000000000000000">The SET OF type</A>
87</UL>
88</UL>
89</UL><BR>
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]90<LI><A NAME="tex2html66"
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]91 HREF="asn1c-usage.html#SECTION03000000000000000000">Using the ASN.1 Compiler</A>
92<UL>
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]93<LI><A NAME="tex2html67"
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]94 HREF="asn1c-usage.html#SECTION03100000000000000000">Introduction to the ASN.1 Compiler</A>
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]95<LI><A NAME="tex2html68"
96 HREF="asn1c-usage.html#SECTION03200000000000000000">Quick start</A>
97<LI><A NAME="tex2html69"
98 HREF="asn1c-usage.html#SECTION03300000000000000000">Using the ASN.1 Compiler</A>
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]99<UL>
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]100<LI><A NAME="tex2html70"
101 HREF="asn1c-usage.html#SECTION03310000000000000000">Command-line options</A>
102<LI><A NAME="tex2html71"
103 HREF="asn1c-usage.html#SECTION03320000000000000000">Recognizing compiler output</A>
104<LI><A NAME="tex2html72"
105 HREF="asn1c-usage.html#SECTION03330000000000000000">Invoking the ASN.1 helper code from the application</A>
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]106<UL>
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]107<LI><A NAME="tex2html73"
108 HREF="asn1c-usage.html#SECTION03331000000000000000">Decoding BER</A>
109<LI><A NAME="tex2html74"
110 HREF="asn1c-usage.html#SECTION03332000000000000000">Encoding DER</A>
111<LI><A NAME="tex2html75"
112 HREF="asn1c-usage.html#SECTION03333000000000000000">Validating the target structure</A>
113<LI><A NAME="tex2html76"
114 HREF="asn1c-usage.html#SECTION03334000000000000000">Printing the target structure</A>
115<LI><A NAME="tex2html77"
116 HREF="asn1c-usage.html#SECTION03335000000000000000">Freeing the target structure</A>
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]117</UL>
118</UL>
119</UL><BR>
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]120<LI><A NAME="tex2html78"
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]121 HREF="asn1c-usage.html#SECTION04000000000000000000">Bibliography</A>
122</UL>
123<!--End of Table of Contents-->
124
125<P>
126
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]127<P>
128
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]129<H1><A NAME="SECTION02000000000000000000">
130ASN.1 Basics</A>
131</H1>
132
133<P>
134
135<H1><A NAME="SECTION02100000000000000000">
136Abstract Syntax Notation: ASN.1</A>
137</H1>
138
139<P>
140<I>This chapter defines some basic ASN.1 concepts and describes
141several most widely used types. It is by no means an authoritative
142or complete reference. For more complete ASN.1 description, please
143refer to Olivier Dubuisson's book [<A
144 HREF="asn1c-usage.html#Dub00">Dub00</A>] or the ASN.1 body
145of standards itself [<A
146 HREF="asn1c-usage.html#ITU-T_ASN.1">ITU-T/ASN.1</A>].</I>
147
148<P>
149The Abstract Syntax Notation One is used to formally describe the
150semantics of data transmitted across the network. Two communicating
151parties may have different formats of their native data types (i.e.
152number of bits in the integer type), thus it is important to have
153a way to describe the data in a manner which is independent from the
154particular machine's representation. The ASN.1 specifications is used
155to achieve one or more of the following:
156
157<P>
158
159<UL>
160<LI>The specification expressed in the ASN.1 notation is a formal and
161precise way to communicate the data semantics to human readers;
162</LI>
163<LI>The ASN.1 specifications may be used as input for automatic compilers
164which produce the code for some target language (C, C++, Java, etc)
165to encode and decode the data according to some encoding rules (which
166are also defined by the ASN.1 standard).
167</LI>
168</UL>
169Consider the following example:
170
171<P>
172
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]173<BLOCKQUOTE><PRE>
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]174Rectangle&nbsp;::=&nbsp;SEQUENCE&nbsp;{
175&nbsp;&nbsp;&nbsp;&nbsp;height&nbsp;&nbsp;INTEGER,
176&nbsp;&nbsp;&nbsp;&nbsp;width&nbsp;&nbsp;&nbsp;INTEGER
177}
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]178</PRE>
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]179</BLOCKQUOTE>
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]180This ASN.1 specification describes a constructed type, <I>Rectangle</I>,
181containing two integer fields. This specification may tell the reader
182that there is this kind of data structure and that some entity may
183be prepared to send or receive it. The question on <I>how</I> that
184entity is going to send or receive the <I>encoded data</I> is outside
185the scope of ASN.1. For example, this data structure may be encoded
186according to some encoding rules and sent to the destination using
187the TCP protocol. The ASN.1 specifies several ways of encoding (or
188''serializing'', or ''marshaling'') the data: BER, CER, DER and
189XER, some of them which will be described later.
190
191<P>
192The complete specification must be wrapped in a module, which looks
193like this:
194
195<P>
196
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]197<BLOCKQUOTE><PRE>
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]198UsageExampleModule1
199&nbsp;&nbsp;&nbsp;&nbsp;{&nbsp;iso&nbsp;org(3)&nbsp;dod(6)&nbsp;internet(1)&nbsp;private(4)
200&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;enterprise(1)&nbsp;spelio(9363)&nbsp;software(1)
201&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;asn1c(5)&nbsp;docs(2)&nbsp;usage(1)&nbsp;1&nbsp;}&nbsp;
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]202&nbsp;&nbsp;&nbsp;&nbsp;DEFINITIONS&nbsp;AUTOMATIC&nbsp;TAGS&nbsp;::=
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]203BEGIN
204&nbsp;
205--&nbsp;This&nbsp;is&nbsp;a&nbsp;comment&nbsp;which&nbsp;describes&nbsp;nothing.
206Rectangle&nbsp;::=&nbsp;SEQUENCE&nbsp;{
207&nbsp;&nbsp;&nbsp;&nbsp;height&nbsp;&nbsp;INTEGER,&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;--&nbsp;Height&nbsp;of&nbsp;the&nbsp;rectangle
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]208&nbsp;&nbsp;&nbsp;&nbsp;width&nbsp;&nbsp;&nbsp;INTEGER&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;--&nbsp;Width&nbsp;of&nbsp;the&nbsp;rectangle
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]209}
210&nbsp;
211END
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]212</PRE>
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]213</BLOCKQUOTE>
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]214The module header consists of module name (UsageExampleModule1), the
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]215module object identifier ({...}), a keyword ''DEFINITIONS'', a
216set of module flags (AUTOMATIC TAGS) and ''::= BEGIN''. The module
217ends with an ''END'' statement.
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]218
219<P>
220
221<H1><A NAME="SECTION02110000000000000000">
222Some of the ASN.1 Basic Types</A>
223</H1>
224
225<P>
226
227<H2><A NAME="SECTION02111000000000000000">
228The BOOLEAN type</A>
229</H2>
230
231<P>
232The BOOLEAN type models the simple binary TRUE/FALSE, YES/NO, ON/OFF
233or a similar kind of two-way choice.
234
235<P>
236
237<H2><A NAME="SECTION02112000000000000000">
238The INTEGER type</A>
239</H2>
240
241<P>
242The INTEGER type is a signed natural number type without any restrictions
243on its size. If the automatic checking on INTEGER value bounds are
244necessary, the subtype constraints must be used.
245
246<P>
247
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]248<BLOCKQUOTE><PRE>
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]249SimpleInteger&nbsp;::=&nbsp;INTEGER
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]250&nbsp;
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]251--&nbsp;An&nbsp;integer&nbsp;with&nbsp;a&nbsp;very&nbsp;limited&nbsp;range
252SmallInt&nbsp;::=&nbsp;INTEGER&nbsp;(0..127)
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]253&nbsp;
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]254--&nbsp;Integer,&nbsp;negative
255NegativeInt&nbsp;::=&nbsp;INTEGER&nbsp;(MIN..0)
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]256</PRE>
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]257</BLOCKQUOTE>
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]258
259<P>
260
261<H2><A NAME="SECTION02113000000000000000">
262The ENUMERATED type</A>
263</H2>
264
265<P>
266The ENUMERATED type is semantically equivalent to the INTEGER type
267with some integer values explicitly named.
268
269<P>
270
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]271<BLOCKQUOTE><PRE>
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]272FruitId&nbsp;::=&nbsp;ENUMERATED&nbsp;{&nbsp;apple(1),&nbsp;orange(2)&nbsp;}
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]273&nbsp;
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]274--&nbsp;The&nbsp;numbers&nbsp;in&nbsp;braces&nbsp;are&nbsp;optional,
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]275--&nbsp;the&nbsp;enumeration&nbsp;can&nbsp;be&nbsp;performed
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]276--&nbsp;automatically&nbsp;by&nbsp;the&nbsp;compiler
277ComputerOSType&nbsp;::=&nbsp;ENUMERATED&nbsp;{
278&nbsp;&nbsp;&nbsp;&nbsp;FreeBSD,&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;--&nbsp;will&nbsp;be&nbsp;0
279&nbsp;&nbsp;&nbsp;&nbsp;Windows,&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;--&nbsp;will&nbsp;be&nbsp;1
280&nbsp;&nbsp;&nbsp;&nbsp;Solaris(5),&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;--&nbsp;will&nbsp;remain&nbsp;5
281&nbsp;&nbsp;&nbsp;&nbsp;Linux,&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;--&nbsp;will&nbsp;be&nbsp;6
282&nbsp;&nbsp;&nbsp;&nbsp;MacOS&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;--&nbsp;will&nbsp;be&nbsp;7
283}
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]284</PRE>
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]285</BLOCKQUOTE>
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]286
287<P>
288
289<H2><A NAME="SECTION02114000000000000000">
290The OCTET STRING type</A>
291</H2>
292
293<P>
294This type models the sequence of 8-bit bytes. This may be used to
295transmit some opaque data or data serialized by other types of encoders
296(i.e. video file, photo picture, etc).
297
298<P>
299
300<H2><A NAME="SECTION02115000000000000000">
301The OBJECT IDENTIFIER type</A>
302</H2>
303
304<P>
305The OBJECT IDENTIFIER is used to represent the unique identifier of
306any object, starting from the very root of the registration tree.
307If your organization needs to uniquely identify something (a router,
308a room, a person, a standard, or whatever), you are encouraged to
309get your own identification subtree at http://www.iana.org/protocols/forms.htm.
310
311<P>
312For example, the very first ASN.1 module in this document has the
313following OBJECT IDENTIFIER: 1 3 6 1 4 1 9363 1 5 2 1 1.
314
315<P>
316
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]317<BLOCKQUOTE><PRE>
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]318ExampleOID&nbsp;::=&nbsp;OBJECT&nbsp;IDENTIFIER
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]319&nbsp;
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]320usageExampleModule1-oid&nbsp;ExampleOID
321&nbsp;&nbsp;::=&nbsp;{&nbsp;1&nbsp;3&nbsp;6&nbsp;1&nbsp;4&nbsp;1&nbsp;9363&nbsp;1&nbsp;5&nbsp;2&nbsp;1&nbsp;1&nbsp;}
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]322&nbsp;
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]323--&nbsp;An&nbsp;identifier&nbsp;of&nbsp;the&nbsp;Internet.
324internet-id&nbsp;OBJECT&nbsp;IDENTIFIER
325&nbsp;&nbsp;::=&nbsp;{&nbsp;iso(1)&nbsp;identified-organization(3)
326&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;dod(6)&nbsp;internet(1)&nbsp;}
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]327</PRE>
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]328</BLOCKQUOTE>
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]329As you see, names are optional.
330
331<P>
332
333<H2><A NAME="SECTION02116000000000000000">
334The RELATIVE-OID type</A>
335</H2>
336
337<P>
338The RELATIVE-OID type has the semantics of a subtree of an OBJECT
339IDENTIFIER. There may be no need to repeat the whole sequence of numbers
340from the root of the registration tree where the only thing of interest
341is some of the tree's subsequence.
342
343<P>
344
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]345<BLOCKQUOTE><PRE>
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]346this-document&nbsp;RELATIVE-OID&nbsp;::=&nbsp;{&nbsp;docs(2)&nbsp;usage(1)&nbsp;}
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]347&nbsp;
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]348this-example&nbsp;RELATIVE-OID&nbsp;::=&nbsp;{
349&nbsp;&nbsp;&nbsp;&nbsp;this-document&nbsp;assorted-examples(0)&nbsp;this-example(1)&nbsp;}
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]350</PRE>
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]351</BLOCKQUOTE>
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]352
353<P>
354
355<H1><A NAME="SECTION02120000000000000000">
356Some of the ASN.1 String Types</A>
357</H1>
358
359<P>
360
361<H2><A NAME="SECTION02121000000000000000">
362The IA5String type</A>
363</H2>
364
365<P>
366This is essentially the ASCII, with 128 character codes available
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]367(7 lower bits of an 8-bit byte).
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]368
369<P>
370
371<H2><A NAME="SECTION02122000000000000000">
372The UTF8String type</A>
373</H2>
374
375<P>
376This is the character string which encodes the full Unicode range
377(4 bytes) using multibyte character sequences.
378
379<P>
380
381<H2><A NAME="SECTION02123000000000000000">
382The NumericString type</A>
383</H2>
384
385<P>
386This type represents the character string with the alphabet consisting
387of numbers (''0'' to ''9'') and a space.
388
389<P>
390
391<H2><A NAME="SECTION02124000000000000000">
392The PrintableString type</A>
393</H2>
394
395<P>
396The character string with the following alphabet: space, ''<B>'</B>''
397(single quote), ''<B>(</B>'', ''<B>)</B>'', ''<B>+</B>'',
398'','' (comma), ''<B>-</B>'', ''<B>.</B>'', ''<B>/</B>'',
399digits (''0'' to ''9''), ''<B>:</B>'', ''<B>=</B>'', ''<B>?</B>'',
400upper-case and lower-case letters (''A'' to ''Z'' and ''a''
401to ''z'')
402
403<P>
404
405<H2><A NAME="SECTION02125000000000000000">
406The VisibleString type</A>
407</H2>
408
409<P>
410The character string with the alphabet which is more or less a subset
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]411of ASCII between space and ''<B>~</B>'' (tilde).
412Alternatively, the alphabet may be described as the PrintableString
413alphabet presented earlier, plus the following characters: ''<B>!</B>'',
414''<B>''</B>'', ''<B>#</B>'', ''<B>$</B>'', ''<B>%</B>'',
415''<B>&amp;</B>'', ''<B>*</B>'', ''<B>;</B>'', ''<B>&lt;</B>'',
416''<B>&gt;</B>'', ''<B>[</B>'', ''<B>&#92;</B>'',
417''<B>]</B>'', ''<B>&#94;</B>'', ''<B>_</B>'',
418''<B>`</B>'' (single left quote), ''<B>{</B>'', ''<B>|</B>'',
419''<B>}</B>'', ''<B>~</B>''.
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]420
421<P>
422
423<H1><A NAME="SECTION02130000000000000000">
424ASN.1 Constructed Types</A>
425</H1>
426
427<P>
428
429<H2><A NAME="SECTION02131000000000000000">
430The SEQUENCE type</A>
431</H2>
432
433<P>
434This is an ordered collection of other simple or constructed types.
435The SEQUENCE constructed type resembles the C ''struct'' statement.
436
437<P>
438
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]439<BLOCKQUOTE><PRE>
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]440Address&nbsp;::=&nbsp;SEQUENCE&nbsp;{
441&nbsp;&nbsp;&nbsp;&nbsp;--&nbsp;The&nbsp;apartment&nbsp;number&nbsp;may&nbsp;be&nbsp;omitted
442&nbsp;&nbsp;&nbsp;&nbsp;apartmentNumber&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;NumericString&nbsp;OPTIONAL,
443&nbsp;&nbsp;&nbsp;&nbsp;streetName&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;PrintableString,
444&nbsp;&nbsp;&nbsp;&nbsp;cityName&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;PrintableString,
445&nbsp;&nbsp;&nbsp;&nbsp;stateName&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;PrintableString,
446&nbsp;&nbsp;&nbsp;&nbsp;--&nbsp;This&nbsp;one&nbsp;may&nbsp;be&nbsp;omitted&nbsp;too
447&nbsp;&nbsp;&nbsp;&nbsp;zipNo&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;NumericString&nbsp;OPTIONAL
448}
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]449</PRE>
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]450</BLOCKQUOTE>
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]451
452<P>
453
454<H2><A NAME="SECTION02132000000000000000">
455The SET type</A>
456</H2>
457
458<P>
459This is a collection of other simple or constructed types. Ordering
460is not important. The data may arrive in the order which is different
461from the order of specification. Data is encoded in the order not
462necessarily corresponding to the order of specification.
463
464<P>
465
466<H2><A NAME="SECTION02133000000000000000">
467The CHOICE type</A>
468</H2>
469
470<P>
471This type is just a choice between the subtypes specified in it. The
472CHOICE type contains at most one of the subtypes specified, and it
473is always implicitly known which choice is being decoded or encoded.
474This one resembles the C ''union'' statement.
475
476<P>
477The following type defines a response code, which may be either an
478integer code or a boolean ''true''/''false'' code.
479
480<P>
481
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]482<BLOCKQUOTE><PRE>
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]483ResponseCode&nbsp;::=&nbsp;CHOICE&nbsp;{
484&nbsp;&nbsp;&nbsp;&nbsp;intCode&nbsp;&nbsp;&nbsp;&nbsp;INTEGER,
485&nbsp;&nbsp;&nbsp;&nbsp;boolCode&nbsp;&nbsp;&nbsp;BOOLEAN
486}
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]487</PRE>
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]488</BLOCKQUOTE>
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]489
490<P>
491
492<H2><A NAME="SECTION02134000000000000000">
493The SEQUENCE OF type</A>
494</H2>
495
496<P>
497This one is the list (array) of simple or constructed types:
498
499<P>
500
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]501<BLOCKQUOTE><PRE>
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]502--&nbsp;Example&nbsp;1
503ManyIntegers&nbsp;::=&nbsp;SEQUENCE&nbsp;OF&nbsp;INTEGER
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]504&nbsp;
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]505--&nbsp;Example&nbsp;2
506ManyRectangles&nbsp;::=&nbsp;SEQUENCE&nbsp;OF&nbsp;Rectangle
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]507&nbsp;
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]508--&nbsp;More&nbsp;complex&nbsp;example:
509--&nbsp;an&nbsp;array&nbsp;of&nbsp;structures&nbsp;defined&nbsp;in&nbsp;place.
510ManyCircles&nbsp;::=&nbsp;SEQUENCE&nbsp;OF&nbsp;SEQUENCE&nbsp;{
511&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;radius&nbsp;INTEGER
512&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;}
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]513</PRE>
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]514</BLOCKQUOTE>
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]515
516<P>
517
518<H2><A NAME="SECTION02135000000000000000">
519The SET OF type</A>
520</H2>
521
522<P>
523The SET OF type models the bag of structures. It resembles the SEQUENCE
524OF type, but the order is not important: i.e. the elements may arrive
525in the order which is not necessarily the same as the in-memory order
526on the remote machines.
527
528<P>
529
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]530<BLOCKQUOTE><PRE>
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]531--&nbsp;A&nbsp;set&nbsp;of&nbsp;structures&nbsp;defined&nbsp;elsewhere
532SetOfApples&nbsp;::&nbsp;SET&nbsp;OF&nbsp;Apple
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]533&nbsp;
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]534--&nbsp;Set&nbsp;of&nbsp;integers&nbsp;encoding&nbsp;the&nbsp;kind&nbsp;of&nbsp;a&nbsp;fruit
535FruitBag&nbsp;::=&nbsp;SET&nbsp;OF&nbsp;ENUMERATED&nbsp;{&nbsp;apple,&nbsp;orange&nbsp;}
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]536</PRE>
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]537</BLOCKQUOTE>
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]538
539<P>
540
541<H1><A NAME="SECTION03000000000000000000">
542Using the ASN.1 Compiler</A>
543</H1>
544
545<P>
546
547<H1><A NAME="SECTION03100000000000000000">
548Introduction to the ASN.1 Compiler</A>
549</H1>
550
551<P>
552The purpose of the ASN.1 compiler, of which this document is part,
553is to convert the ASN.1 specifications to some other target language
554(currently, only C is supported<A NAME="tex2html1"
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]555 HREF="#foot144"><SUP>2.1</SUP></A>). The compiler reads the specification and emits a series of target
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]556language structures and surrounding maintenance code. For example,
557the C structure which may be created by compiler to represent the
558simple <I>Rectangle</I> specification defined earlier in this document,
559may look like this<A NAME="tex2html2"
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]560 HREF="#foot379"><SUP>2.2</SUP></A>:
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]561
562<P>
563
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]564<BLOCKQUOTE><PRE>
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]565typedef&nbsp;struct&nbsp;Rectangle_s&nbsp;{
566&nbsp;&nbsp;&nbsp;&nbsp;int&nbsp;height;
567&nbsp;&nbsp;&nbsp;&nbsp;int&nbsp;width;
568}&nbsp;Rectangle_t;
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]569</PRE>
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]570</BLOCKQUOTE>
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]571This would not be of much value for such a simple specification, so
572the compiler goes further and actually produces the code which fills
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]573in this structure by parsing the opaque binary<A NAME="tex2html3"
574 HREF="#foot151"><SUP>2.3</SUP></A> data provided in some buffer. It also produces the code that takes
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]575this structure as an argument and performs structure serialization
576by emitting a series of bytes.
577
578<P>
579
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]580<H1><A NAME="SECTION03200000000000000000">
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]581Quick start</A>
582</H1>
583
584<P>
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]585After building and installing the compiler, the <I>asn1c</I><A NAME="tex2html4"
586 HREF="#foot380"><SUP>3.1</SUP></A> command may be used to compile the ASN.1 specification<A NAME="tex2html5"
587 HREF="#foot381"><SUP>3.2</SUP></A>:
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]588
589<P>
590
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]591<BLOCKQUOTE><PRE>
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]592asn1c&nbsp;<I>&lt;spec.asn1&gt;</I>
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]593</PRE>
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]594</BLOCKQUOTE>
595If several specifications contain interdependencies, all of the files
596must be specified altogether:
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]597
598<P>
599
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]600<BLOCKQUOTE><PRE>
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]601asn1c&nbsp;<I>&lt;spec1.asn1&gt;&nbsp;&lt;spec2.asn1&gt;&nbsp;...</I>
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]602</PRE>
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]603</BLOCKQUOTE>
604The compiler <B>-E</B> and <B>-EF</B> options are used for testing
605the parser and the semantic fixer, respectively. These options will
606instruct the compiler to dump out the parsed (and fixed, if <B>-F</B>
607is involved) ASN.1 specification as it was &#34;understood&#34;
608by the compiler. It might be useful to check whether a particular
609syntactic construction is properly supported by the compiler.
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]610
611<P>
612
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]613<BLOCKQUOTE><PRE>
614asn1c&nbsp;<B>-EF</B>&nbsp;<I>&lt;spec-to-test.asn1&gt;</I>
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]615</PRE>
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]616</BLOCKQUOTE>
617The <B>-P</B> option is used to dump the compiled output on the
618screen instead of creating a bunch of .c and .h files on disk in the
619current directory. You would probably want to start with <B>-P</B>
620option instead of creating a mess in your current directory. Another
621option, <B>-R</B>, asks compiler to only generate the files which
622need to be generated, and supress linking in the numerous support
623files.
624
625<P>
626Print the compiled output instead of creating multiple source files:
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]627
628<P>
629
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]630<BLOCKQUOTE><PRE>
631asn1c&nbsp;<B>-P</B>&nbsp;<I>&lt;spec-to-compile-and-print.asn1&gt;</I>
632</PRE>
633</BLOCKQUOTE>
634
635<P>
636
637<H1><A NAME="SECTION03300000000000000000">
638Using the ASN.1 Compiler</A>
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]639</H1>
640
641<P>
642
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]643<H1><A NAME="SECTION03310000000000000000">
644Command-line options</A>
645</H1>
646
647<P>
648The <A HREF=#Table1>Table 1</A> summarizes various options affecting
649the compiler's behavior.
650
651<P>
652<BR><P></P>
653<DIV ALIGN="CENTER"><A NAME="384"></A>
654<TABLE>
655<CAPTION><STRONG><A NAME=Table1>Table 1:</A></STRONG>
656The list of asn1c command line options</CAPTION>
657<TR><TD><TABLE COLS=2 BORDER FRAME=BOX RULES=GROUPS>
658<COLGROUP><COL ALIGN=LEFT><COLGROUP><COL ALIGN=JUSTIFY WIDTH="3in">
659<TBODY>
660<TR><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP>
661<B>Overall Options</B></TD><TD VALIGN=BASELINE ALIGN=LEFT WIDTH="216">
662<B>Description</B></TD></TR>
663</TBODY><TBODY>
664<TR><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP>-E</TD><TD VALIGN=BASELINE ALIGN=LEFT WIDTH="216">
665<FONT SIZE="-1">Stop after the parsing stage and print the reconstructed ASN.1
666specification code to the standard output.</FONT></TD></TR>
667</TBODY><TBODY>
668<TR><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP>-F</TD><TD VALIGN=BASELINE ALIGN=LEFT WIDTH="216">
669<FONT SIZE="-1">Used together with -E, instructs the compiler to stop after
670the ASN.1 syntax tree fixing stage and dump the reconstructed ASN.1
671specification to the standard output.</FONT></TD></TR>
672</TBODY><TBODY>
673<TR><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP>-P</TD><TD VALIGN=BASELINE ALIGN=LEFT WIDTH="216">
674<FONT SIZE="-1">Dump the compiled output to the standard output instead of
675cre- ating the target language files on disk.</FONT></TD></TR>
676</TBODY><TBODY>
677<TR><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP>-R</TD><TD VALIGN=BASELINE ALIGN=LEFT WIDTH="216">
678<FONT SIZE="-1">Restrict the compiler to generate only the ASN.1 tables, omit-
679ting the usual support code.</FONT></TD></TR>
680</TBODY><TBODY>
681<TR><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP>-S <I>&lt;directory&gt;</I></TD><TD VALIGN=BASELINE ALIGN=LEFT WIDTH="216">
682<FONT SIZE="-1">Use the specified directory with ASN.1 skeleton files.</FONT></TD></TR>
683</TBODY><TBODY>
684<TR><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP>-t <I>&lt;data-string&gt;</I></TD><TD VALIGN=BASELINE ALIGN=LEFT WIDTH="216">
685<FONT SIZE="-1">Interpret the data-string as a sequence of hexadecimal values
686representing the start of BER TLV encoding. Print the human readable
687explanation.</FONT></TD></TR>
688</TBODY><TBODY>
689<TR><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP><B>Warning Options</B></TD><TD VALIGN=BASELINE ALIGN=LEFT WIDTH="216">
690<B>Description</B></TD></TR>
691</TBODY><TBODY>
692<TR><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP>-Werror</TD><TD VALIGN=BASELINE ALIGN=LEFT WIDTH="216">
693<FONT SIZE="-1">Treat warnings as errors; abort if any warning is produced.</FONT></TD></TR>
694</TBODY><TBODY>
695<TR><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP>-Wdebug-lexer</TD><TD VALIGN=BASELINE ALIGN=LEFT WIDTH="216">
696<FONT SIZE="-1">Enable lexer debugging during the ASN.1 parsing stage.</FONT></TD></TR>
697</TBODY><TBODY>
698<TR><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP>-Wdebug-fixer</TD><TD VALIGN=BASELINE ALIGN=LEFT WIDTH="216">
699 <FONT SIZE="-1">Enable ASN.1 syntax tree fixer debugging during the
700 fixing stage.</FONT></TD></TR>
701</TBODY><TBODY>
702<TR><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP>-Wdebug-compiler</TD><TD VALIGN=BASELINE ALIGN=LEFT WIDTH="216">
703<FONT SIZE="-1">Enable debugging during the actual compile time.</FONT></TD></TR>
704</TBODY><TBODY>
705<TR><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP><B>Language Options</B></TD><TD VALIGN=BASELINE ALIGN=LEFT WIDTH="216">
706<B>Description</B></TD></TR>
707</TBODY><TBODY>
Lev Walkin71a8aaf2004-09-08 03:10:54 +0000[diff] [blame]708<TR><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP>-fall-defs-global</TD><TD VALIGN=BASELINE ALIGN=LEFT WIDTH="216">
709Normally the compiler hides the definitions (asn1_DEF_xxx) of the
710inner structure elements (members of SEQUENCE, SET and other types).
711This option makes all such definitions global. Enabling this option
712may pollute the namespace by making lots of asn1_DEF_xxx structures
713globally visible, but will allow you to manipulate (encode and decode)
714the individual members of any complex ASN.1 structure.</TD></TR>
715</TBODY><TBODY>
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]716<TR><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP>-fbless-SIZE</TD><TD VALIGN=BASELINE ALIGN=LEFT WIDTH="216">
717<FONT SIZE="-1">Allow SIZE() constraint for INTEGER, ENUMERATED, and other
718types for which this constraint is normally prohibited by the standard.
719This is a violation of an ASN.1 standard and compiler may fail to
720produce the meaningful code.</FONT></TD></TR>
721</TBODY><TBODY>
722<TR><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP>-fnative-integers</TD><TD VALIGN=BASELINE ALIGN=LEFT WIDTH="216">
723<FONT SIZE="-1">Use native machine's integer types whenever possible, instead
724of the complex ASN.1 INTEGER and ENUMERATED types. </FONT></TD></TR>
725</TBODY><TBODY>
726<TR><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP>-funnamed-unions</TD><TD VALIGN=BASELINE ALIGN=LEFT WIDTH="216">
727<FONT SIZE="-1">Enable unnamed unions in the definitions of target language's
728structures.</FONT></TD></TR>
729</TBODY><TBODY>
730<TR><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP>-ftypes88</TD><TD VALIGN=BASELINE ALIGN=LEFT WIDTH="216">
731<FONT SIZE="-1">Use only ASN.1:1988 embedded types.</FONT></TD></TR>
732</TBODY><TBODY>
733<TR><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP><B>Output Options</B></TD><TD VALIGN=BASELINE ALIGN=LEFT WIDTH="216">
734<B>Description</B></TD></TR>
735</TBODY><TBODY>
736<TR><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP>-print-constraints</TD><TD VALIGN=BASELINE ALIGN=LEFT WIDTH="216">
737<FONT SIZE="-1">When -EF are also specified, this option forces the compiler
738to explain its internal understanding of subtype constraints.</FONT></TD></TR>
739</TBODY><TBODY>
740<TR><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP>-print-lines</TD><TD VALIGN=BASELINE ALIGN=LEFT WIDTH="216">
741<FONT SIZE="-1">Generate &#34;- #line&#34; comments in -E output.</FONT></TD></TR>
742</TBODY>
743</TABLE>
744
745<P>
746</TD></TR>
747</TABLE>
748</DIV><P></P><BR>
749
750<P>
751
752<H1><A NAME="SECTION03320000000000000000">
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]753Recognizing compiler output</A>
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]754</H1>
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]755
756<P>
757After compiling, the following entities will be created in your current
758directory:
759
760<P>
761
762<UL>
763<LI>A set of .c and .h files, generally a single pair for each type defined
764in the ASN.1 specifications. These files will be named similarly to
765the ASN.1 types (<I>Rectangle.c</I> and <I>Rectangle.h</I> for the
766specification defined in the beginning of this document).
767</LI>
768<LI>A set of helper .c and .h files which contain generic encoders, decoders
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]769and other useful routines. There will be quite a few of them, some
770of them even are not always necessary, but the overall amount of code
771after compiling will be rather small anyway.
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]772</LI>
773</UL>
774It is your responsibility to create .c file with the <I>int main()</I>
775routine and the Makefile (if needed). Compiler helps you with the
776latter by creating the Makefile.am.sample, containing the skeleton
777definition for the automake, should you want to use autotools.
778
779<P>
780In other words, after compiling the Rectangle module, you have the
781following set of files: { Makefile.am.sample, Rectangle.c, Rectangle.h,
782<B>...</B> }, where <B>''...''</B> stands for the
783set of additional ''helper'' files created by the compiler. If you
784add the simple file with the <I>int main()</I> routine, it would even
785be possible to compile everything with the single instruction:
786
787<P>
788
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]789<BLOCKQUOTE><PRE>
790cc&nbsp;-o&nbsp;rectangle&nbsp;*.c&nbsp;&nbsp;&nbsp;#&nbsp;It&nbsp;could&nbsp;be&nbsp;<I>that</I>&nbsp;simple<A NAME="tex2html7"
791 HREF="#foot387"><SUP>4.1</SUP></A>
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]792</PRE>
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]793</BLOCKQUOTE>
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]794
795<P>
796
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]797<H1><A NAME="SECTION03330000000000000000">
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]798Invoking the ASN.1 helper code from the application</A>
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]799</H1>
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]800
801<P>
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]802First of all, you should to include one or more header files into
803your application. For our Rectangle module, including the Rectangle.h
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]804file is enough:
805
806<P>
807
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]808<BLOCKQUOTE><PRE>
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]809#include&nbsp;&lt;Rectangle.h&gt;
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]810</PRE>
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]811</BLOCKQUOTE>
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]812The header files defines the C structure corresponding to the ASN.1
813definition of a rectangle and the declaration of the ASN.1 type descriptor,
814which is used as an argument to most of the functions provided by
815the ASN.1 module. For example, here is the code which frees the Rectangle_t
816structure:
817
818<P>
819
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]820<BLOCKQUOTE><PRE>
821Rectangle_t&nbsp;*rect&nbsp;=&nbsp;...;
822&nbsp;
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]823asn1_DEF_Rectangle-&gt;free_struct(&amp;asn1_DEF_Rectangle,
824&nbsp;&nbsp;&nbsp;&nbsp;rect,&nbsp;0);
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]825</PRE>
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]826</BLOCKQUOTE>
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]827This code defines a <I>rect</I> pointer which points to the Rectangle_t
828structure which needs to be freed. The second line invokes the generic
829free_struct routine created specifically for this Rectangle_t structure.
830The <I>asn1_DEF_Rectangle</I> is the type descriptor, which holds
831a collection of generic routines to deal with the Rectangle_t structure.
832
833<P>
834There are several generic functions available:
835
836<P>
837<DL>
838<DT><STRONG>check_constraints</STRONG></DT>
839<DD>Check that the contents of the target structure
840are semantically valid and constrained to appropriate implicit or
841explicit subtype constraints. Please refer to Section sub:Validating-the-target.
842</DD>
843<DT><STRONG>ber_decoder</STRONG></DT>
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]844<DD>This is the generic <I>restartable</I><A NAME="tex2html8"
845 HREF="#foot241"><SUP>4.2</SUP></A> BER decoder (Basic Encoding Rules). This decoder would create
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]846and/or fill the target structure for you. Please refer to Section
847[<A HREF="#sub:Decoding-BER">Decoding-BER</A>].
848</DD>
849<DT><STRONG>der_encoder</STRONG></DT>
850<DD>This is the generic DER encoder (Distinguished Encoding
851Rules). This decoder will take the target structure and encode it
852into a series of bytes. Please refer to Section [<A HREF="#sub:Encoding-DER">Encoding-DER</A>].
853</DD>
854<DT><STRONG>print_struct</STRONG></DT>
855<DD>This function convert the contents of the passed target
856structure into human readable form. This form is not formal and cannot
857be converted back into the structure, but it may turn out to be useful
858for debugging or quick-n-dirty printing. Please refer to Section [<A HREF="#sub:Printing-the-target">Printing-the-target</A>].
859</DD>
860<DT><STRONG>free_struct</STRONG></DT>
861<DD>This is a generic disposal which frees the target structure.
862Please refer to Section [<A HREF="#sub:Freeing-the-target">Freeing-the-target</A>].
863</DD>
864</DL>
865Each of the above function takes the type descriptor (<I>asn1_DEF_...</I>)
866and the target structure (<I>rect</I>, in the above example). The
867target structure is typically created by the generic BER decoder or
868by the application itself.
869
870<P>
871Here is how the buffer can be deserialized into the structure:
872
873<P>
874
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]875<BLOCKQUOTE><PRE>
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]876Rectangle_t&nbsp;*
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]877simple_deserializer(const&nbsp;void&nbsp;*buffer,&nbsp;size_t&nbsp;buf_size)&nbsp;{
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]878&nbsp;&nbsp;&nbsp;&nbsp;Rectangle_t&nbsp;*rect&nbsp;=&nbsp;0;&nbsp;&nbsp;&nbsp;&nbsp;/*&nbsp;Note&nbsp;this&nbsp;0!&nbsp;*/
879&nbsp;&nbsp;&nbsp;&nbsp;ber_dec_rval_t&nbsp;rval;
880&nbsp;
881&nbsp;&nbsp;&nbsp;&nbsp;rval&nbsp;=&nbsp;asn1_DEF_Rectangle-&gt;ber_decoder(
882&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&amp;asn1_DEF_Rectangle,
883&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;(void&nbsp;**)&amp;rect,
884&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;buffer,&nbsp;buf_size,
885&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;0);
886&nbsp;
887&nbsp;&nbsp;&nbsp;&nbsp;if(rval<B>.code</B>&nbsp;==&nbsp;RC_OK)&nbsp;{
888&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;return&nbsp;rect;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;/*&nbsp;Decoding&nbsp;succeeded&nbsp;*/
889&nbsp;&nbsp;&nbsp;&nbsp;}&nbsp;else&nbsp;{
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]890&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;/*&nbsp;Free&nbsp;partially&nbsp;decoded&nbsp;rect&nbsp;*/
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]891&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;asn1_DEF_Rectangle-&gt;free_struct(
892&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&amp;asn1_DEF_Rectangle,&nbsp;rect,&nbsp;0);
893&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;return&nbsp;0;
894&nbsp;&nbsp;&nbsp;&nbsp;}
895}
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]896</PRE>
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]897</BLOCKQUOTE>
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]898The code above defines a function, <I>simple_deserializer</I>, which
899takes a buffer and its length and expected to return a pointer to
900the Rectangle_t structure. Inside, it tries to convert the bytes
901passed into the target structure (rect) using the generic BER decoder
902and returns the rect pointer afterwards. If the structure cannot be
903deserialized, it frees the memory which might be left allocated by
904the unfinished <I>ber_decoder</I> routine and returns NULL. <B>This
905freeing is necessary</B> because the ber_decoder is a restartable procedure,
906and may fail just because there is more data needs to be provided
907before decoding could be finalized. The code above obviously does
908not take into account the way the <I>ber_decoder</I> failed, so the
909freeing is necessary because the part of the buffer may already be
910decoded into the structure by the time something goes wrong.
911
912<P>
913Restartable decoding is a little bit trickier: you need to provide
914the old target structure pointer (which might be already half-decoded)
915and react on RC_WMORE return code. This will be explained later in
916Section sub:Decoding-BER
917
918<P>
919
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]920<H2><A NAME="SECTION03331000000000000000"></A><A NAME="sub:Decoding-BER"></A><BR>
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]921Decoding BER
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]922</H2>
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]923
924<P>
925The Basic Encoding Rules describe the basic way how the structure
926can be encoded and decoded. Several other encoding rules (CER, DER)
927define a more restrictive versions of BER, so the generic BER parser
928is also capable of decoding the data encoded by CER and DER encoders.
929The opposite is not true.
930
931<P>
932The ASN.1 compiler provides the generic BER decoder which is implicitly
933capable of decoding BER, CER and DER encoded data.
934
935<P>
936The decoder is restartable (stream-oriented), which means that in
937case the buffer has less data than it is expected, the decoder will
938process whatever it is available and ask for more data to be provided.
939Please note that the decoder may actually process less data than it
940is given in the buffer, which means that you should be able to make
941the next buffer contain the unprocessed part of the previous buffer.
942
943<P>
944Suppose, you have two buffers of encoded data: 100 bytes and 200 bytes.
945
946<P>
947
948<UL>
949<LI>You may concatenate these buffers and feed the BER decoder with 300
950bytes of data, or
951</LI>
952<LI>You may feed it the first buffer of 100 bytes of data, realize that
953the ber_decoder consumed only 95 bytes from it and later feed the
954decoder with 205 bytes buffer which consists of 5 unprocessed bytes
955from the first buffer and the latter 200 bytes from the second buffer.
956</LI>
957</UL>
958This is not as convenient as it could be (like, the BER encoder would
959consume the whole 100 bytes and keep these 5 bytes in some temporary
960storage), but in case of stream-based processing it might actually
961be OK. Suggestions are welcome.
962
963<P>
964There are two ways to invoke a BER decoder. The first one is a direct
965reference of the type-specific decoder. This way was shown in the
966previous example of <I>simple_deserializer</I> function. The second
967way is to invoke a <I>ber_decode</I> function, which is just a simple
968wrapper of the former approach into a less wordy notation:
969
970<P>
971
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]972<BLOCKQUOTE><PRE>
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]973rval&nbsp;=&nbsp;ber_decode(&amp;asn1_DEF_Rectangle,&nbsp;(void&nbsp;**)&amp;rect,
974&nbsp;&nbsp;&nbsp;&nbsp;buffer,&nbsp;buf_size);
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]975</PRE>
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]976</BLOCKQUOTE>
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]977Note that the initial (asn1_DEF_Rectangle-&gt;ber_decoder) reference
978is gone, and also the last argument (0) is no longer necessary.
979
980<P>
981These two ways of invocations are fully equivalent.
982
983<P>
984The BER de<I>coder</I> may fail because (<I>the following RC_...
985codes are defined in ber_decoder.h</I>):
986
987<P>
988
989<UL>
990<LI>RC_WMORE: There is more data expected than it is provided (stream
991mode continuation feature);
992</LI>
993<LI>RC_FAIL: General failure to decode the buffer;
994</LI>
995<LI>... other codes may be defined as well.
996</LI>
997</UL>
998Together with the return code (.code) the ber_dec_rval_t type contains
999the number of bytes which is consumed from the buffer. In the previous
1000hypothetical example of two buffers (of 100 and 200 bytes), the first
1001call to ber_decode() would return with .code = RC_WMORE and .consumed
1002= 95. The .consumed field of the BER decoder return value is <B>always</B>
1003valid, even if the decoder succeeds or fails with any other return
1004code.
1005
1006<P>
1007Please look into ber_decoder.h for the precise definition of ber_decode()
1008and related types.
1009
1010<P>
1011
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]1012<H2><A NAME="SECTION03332000000000000000"></A><A NAME="sub:Encoding-DER"></A><BR>
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]1013Encoding DER
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]1014</H2>
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]1015
1016<P>
1017The Distinguished Encoding Rules is the variant of BER encoding rules
1018which is oriented on representing the structures with length known
1019beforehand. This is probably exactly how you want to encode: either
1020after a BER decoding or after a manual fill-up, the target structure
1021contains the data which size is implicitly known before encoding.
1022The DER encoding is used, for example, to encode X.509 certificates.
1023
1024<P>
1025As with BER decoder, the DER encoder may be invoked either directly
1026from the ASN.1 type descriptor (asn1_DEF_Rectangle) or from the
1027stand-alone function, which is somewhat simpler:
1028
1029<P>
1030
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]1031<BLOCKQUOTE><PRE>
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]1032/*
1033&nbsp;*&nbsp;This&nbsp;is&nbsp;a&nbsp;custom&nbsp;function&nbsp;which&nbsp;writes&nbsp;the
1034&nbsp;*&nbsp;encoded&nbsp;output&nbsp;into&nbsp;some&nbsp;FILE&nbsp;stream.
1035&nbsp;*/
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]1036static&nbsp;int
1037write_stream(const&nbsp;void&nbsp;*buffer,&nbsp;size_t&nbsp;size,&nbsp;void&nbsp;*app_key)&nbsp;{
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]1038&nbsp;&nbsp;&nbsp;&nbsp;FILE&nbsp;*ostream&nbsp;=&nbsp;app_key;
1039&nbsp;&nbsp;&nbsp;&nbsp;size_t&nbsp;wrote;
1040&nbsp;
1041&nbsp;&nbsp;&nbsp;&nbsp;wrote&nbsp;=&nbsp;fwrite(buffer,&nbsp;1,&nbsp;size,&nbsp;ostream);
1042&nbsp;
1043&nbsp;&nbsp;&nbsp;&nbsp;return&nbsp;(wrote&nbsp;==&nbsp;size)&nbsp;?&nbsp;0&nbsp;:&nbsp;-1;
1044}
1045&nbsp;
1046/*
1047&nbsp;*&nbsp;This&nbsp;is&nbsp;the&nbsp;serializer&nbsp;itself,
1048&nbsp;*&nbsp;it&nbsp;supplies&nbsp;the&nbsp;DER&nbsp;encoder&nbsp;with&nbsp;the
1049&nbsp;*&nbsp;pointer&nbsp;to&nbsp;the&nbsp;custom&nbsp;output&nbsp;function.
1050&nbsp;*/
1051ssize_t
1052simple_serializer(FILE&nbsp;*ostream,&nbsp;Rectangle_t&nbsp;*rect)&nbsp;{
1053&nbsp;&nbsp;&nbsp;&nbsp;der_enc_rval_t&nbsp;rval;&nbsp;&nbsp;/*&nbsp;Return&nbsp;value&nbsp;*/
1054&nbsp;
1055&nbsp;&nbsp;&nbsp;&nbsp;rval&nbsp;=&nbsp;der_encode(&amp;asn1_DEF_Rect,&nbsp;rect,
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]1056&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;write_stream,&nbsp;ostream);
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]1057&nbsp;&nbsp;&nbsp;&nbsp;if(rval<B>.encoded</B>&nbsp;==&nbsp;-1)&nbsp;{
1058&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;/*
1059&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*&nbsp;Failure&nbsp;to&nbsp;encode&nbsp;the&nbsp;rectangle&nbsp;data.
1060&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*/
1061&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;fprintf(stderr,&nbsp;''Cannot&nbsp;encode&nbsp;%s:&nbsp;%s&#92;n'',
1062&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;rval<B>.failed_type</B>-&gt;name,
1063&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;strerror(errno));
1064&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;return&nbsp;-1;
1065&nbsp;&nbsp;&nbsp;&nbsp;}&nbsp;else&nbsp;{
1066&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;/*&nbsp;Return&nbsp;the&nbsp;number&nbsp;of&nbsp;bytes&nbsp;*/
1067&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;return&nbsp;rval.encoded;
1068&nbsp;&nbsp;&nbsp;&nbsp;}
1069}
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]1070</PRE>
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]1071</BLOCKQUOTE>
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]1072As you see, the DER encoder does not write into some sort of buffer
1073or something. It just invokes the custom function (possible, multiple
1074times) which would save the data into appropriate storage. The optional
1075argument <I>app_key</I> is opaque for the DER encoder code and just
1076used by <I>_write_stream()</I> as the pointer to the appropriate
1077output stream to be used.
1078
1079<P>
1080If the custom write function is not given (passed as 0), then the
1081DER encoder will essentially do the same thing (i.e., encode the data)
1082but no callbacks will be invoked (so the data goes nowhere). It may
1083prove useful to determine the size of the structure's encoding before
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]1084actually doing the encoding<A NAME="tex2html9"
1085 HREF="#foot313"><SUP>4.3</SUP></A>.
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]1086
1087<P>
1088Please look into der_encoder.h for the precise definition of der_encode()
1089and related types.
1090
1091<P>
1092
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]1093<H2><A NAME="SECTION03333000000000000000"></A><A NAME="sub:Validating-the-target"></A><BR>
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]1094Validating the target structure
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]1095</H2>
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]1096
1097<P>
1098Sometimes the target structure needs to be validated. For example,
1099if the structure was created by the application (as opposed to being
1100decoded from some external source), some important information required
1101by the ASN.1 specification might be missing. On the other hand, the
1102successful decoding of the data from some external source does not
1103necessarily mean that the data is fully valid either. It might well
1104be the case that the specification describes some subtype constraints
1105that were not taken into account during decoding, and it would actually
1106be useful to perform the last check when the data is ready to be encoded
1107or when the data has just been decoded to ensure its validity according
1108to some stricter rules.
1109
1110<P>
1111The asn_check_constraints() function checks the type for various
1112implicit and explicit constraints. It is recommended to use asn_check_constraints()
1113function after each decoding and before each encoding.
1114
1115<P>
1116Please look into constraints.h for the precise definition of asn_check_constraints()
1117and related types.
1118
1119<P>
1120
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]1121<H2><A NAME="SECTION03334000000000000000"></A><A NAME="sub:Printing-the-target"></A><BR>
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]1122Printing the target structure
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]1123</H2>
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]1124
1125<P>
1126There are two ways to print the target structure: either invoke the
1127print_struct member of the ASN.1 type descriptor, or using the asn_fprint()
1128function, which is a simpler wrapper of the former:
1129
1130<P>
1131
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]1132<BLOCKQUOTE><PRE>
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]1133asn_fprint(stdout,&nbsp;&amp;asn1_DEF_Rectangle,&nbsp;rect);
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]1134</PRE>
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]1135</BLOCKQUOTE>
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]1136Please look into constr_TYPE.h for the precise definition of asn_fprint()
1137and related types.
1138
1139<P>
1140
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]1141<H2><A NAME="SECTION03335000000000000000"></A><A NAME="sub:Freeing-the-target"></A><BR>
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]1142Freeing the target structure
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]1143</H2>
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]1144
1145<P>
1146Freeing the structure is slightly more complex than it may seem to.
1147When the ASN.1 structure is freed, all the members of the structure
1148and their submembers etc etc are recursively freed too. But it might
1149not be feasible to free the structure itself. Consider the following
1150case:
1151
1152<P>
1153
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]1154<BLOCKQUOTE><PRE>
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]1155struct&nbsp;my_figure&nbsp;{&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;/*&nbsp;The&nbsp;custom&nbsp;structure&nbsp;*/
1156&nbsp;&nbsp;&nbsp;&nbsp;int&nbsp;flags;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;/*&nbsp;&lt;some&nbsp;custom&nbsp;member&gt;&nbsp;*/
1157&nbsp;&nbsp;&nbsp;&nbsp;/*&nbsp;The&nbsp;type&nbsp;is&nbsp;generated&nbsp;by&nbsp;the&nbsp;ASN.1&nbsp;compiler&nbsp;*/
1158&nbsp;&nbsp;&nbsp;&nbsp;<I>Rectangle_t&nbsp;rect;</I>
1159&nbsp;&nbsp;&nbsp;&nbsp;/*&nbsp;other&nbsp;members&nbsp;of&nbsp;the&nbsp;structure&nbsp;*/
1160};
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]1161</PRE>
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]1162</BLOCKQUOTE>
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]1163In this example, the application programmer defined a custom structure
1164with one ASN.1-derived member (rect). This member is not a reference
1165to the Rectangle_t, but an in-place inclusion of the Rectangle_t
1166structure. If the freeing is necessary, the usual procedure of freeing
1167everything must not be applied to the &amp;rect pointer itself, because
1168it does not point to the memory block directly allocated by memory
1169allocation routine, but instead lies within such a block allocated
1170for my_figure structure.
1171
1172<P>
1173To solve this problem, the free_struct routine has the additional
1174argument (besides the intuitive type descriptor and target structure
1175pointers), which is the flag specifying whether the outer pointer
1176itself must be freed (0, default) or it should be left intact (non-zero
1177value).
1178
1179<P>
1180
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]1181<BLOCKQUOTE><PRE>
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]1182/*&nbsp;Rectangle_t&nbsp;is&nbsp;defined&nbsp;within&nbsp;my_figure&nbsp;*/
1183struct&nbsp;my_figure&nbsp;*mf&nbsp;=&nbsp;<B>...</B>;
1184/*
1185&nbsp;*&nbsp;Freeing&nbsp;the&nbsp;Rectangle_td
1186&nbsp;*&nbsp;without&nbsp;freeing&nbsp;the&nbsp;mf-&gt;rect&nbsp;pointer
1187&nbsp;*/
1188asn1_DEF_Rectangle-&gt;free_struct(
1189&nbsp;&nbsp;&nbsp;&nbsp;&amp;asn1_DEF_Rectangle,&nbsp;&amp;mf-&gt;rect,&nbsp;<I>1</I>&nbsp;/*&nbsp;!free&nbsp;*/);
1190&nbsp;
1191/*&nbsp;Rectangle_t&nbsp;is&nbsp;a&nbsp;stand-alone&nbsp;pointer&nbsp;*/
1192Rectangle_t&nbsp;*rect&nbsp;=&nbsp;<B>...</B>;
1193/*
1194&nbsp;*&nbsp;Freeing&nbsp;the&nbsp;Rectangle_t
1195&nbsp;*&nbsp;and&nbsp;freeing&nbsp;the&nbsp;rect&nbsp;pointer
1196&nbsp;*/
1197asn1_DEF_Rectangle-&gt;free_struct(
1198&nbsp;&nbsp;&nbsp;&nbsp;&amp;asn1_DEF_Rectangle,&nbsp;rect,&nbsp;<I>0</I>&nbsp;/*&nbsp;free&nbsp;the&nbsp;pointer&nbsp;too&nbsp;*/);
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]1199</PRE>
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]1200</BLOCKQUOTE>
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]1201It is safe to invoke the <I>free_struct</I> function with the target
1202structure pointer set to 0 (NULL), the function will do nothing.
1203
1204<P>
1205
1206<H2><A NAME="SECTION04000000000000000000">
1207Bibliography</A>
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]1208</H2><DL COMPACT><DD><P></P><DT><A NAME="ASN1C">ASN1C</A>
Lev Walkin71a8aaf2004-09-08 03:10:54 +0000[diff] [blame]1209<DD>The OpenSource ASN.1 Compiler. http://lionet.info/asn1/
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]1210<P></P><DT><A NAME="Dub00">Dub00</A>
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]1211<DD>Olivier Dubuisson - <I>ASN.1 Communication between heterogeneous
1212systems</I> - Morgan Kaufmann Publishers, 2000. http://asn1.elibel.tm.fr/en/book/.
1213ISBN:0-12-6333361-0.
1214<P></P><DT><A NAME="ITU-T_ASN.1">ITU-T/ASN.1</A>
1215<DD>ITU-T Study Group 17 - Languages for Telecommunication Systems http://www.itu.int/ITU-T/studygroups/com17/languages/</DL>
1216
1217<P>
1218<BR><HR><H4>Footnotes</H4>
1219<DL>
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]1220<DT><A NAME="foot144">... supported</A><A
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]1221 HREF="asn1c-usage.html#tex2html1"><SUP>2.1</SUP></A></DT>
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]1222<DD>C++ is ''supported'' too, as long as an class-based approach is
1223not a definitive factor.
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]1224
1225</DD>
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]1226<DT><A NAME="foot379">... this</A><A
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]1227 HREF="asn1c-usage.html#tex2html2"><SUP>2.2</SUP></A></DT>
1228<DD><I>-fnative-integers</I> compiler option is used to produce basic
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]1229C <I>int</I> types instead of infinite width INTEGER_t structures.
1230See <A HREF=#Table1>Table 1</A>.
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]1231
1232</DD>
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]1233<DT><A NAME="foot151">... binary</A><A
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]1234 HREF="asn1c-usage.html#tex2html3"><SUP>2.3</SUP></A></DT>
1235<DD>BER, CER and DER encodings are binary. However, the XER encoding is
1236text (XML) based.
1237
1238</DD>
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]1239<DT><A NAME="foot380">...asn1c</A><A
1240 HREF="asn1c-usage.html#tex2html4"><SUP>3.1</SUP></A></DT>
1241<DD>The 1 symbol in asn<B>1</B>c is a digit, not an ''ell'' letter.
1242
1243</DD>
1244<DT><A NAME="foot381">... specification</A><A
1245 HREF="asn1c-usage.html#tex2html5"><SUP>3.2</SUP></A></DT>
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]1246<DD>This is probably <B>not</B> what you want to try out right now -
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]1247read through the rest of this chapter to find out about <B>-P</B>
1248and <B>-R</B> options.
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]1249
1250</DD>
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]1251<DT><A NAME="foot387">...that&nbsp;simple</A><A
1252 HREF="asn1c-usage.html#tex2html7"><SUP>4.1</SUP></A></DT>
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]1253<DD>Provided that you've also created a .c file with the <I>int main()</I>
1254routine.
1255
1256</DD>
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]1257<DT><A NAME="foot241">...restartable</A><A
1258 HREF="asn1c-usage.html#tex2html8"><SUP>4.2</SUP></A></DT>
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]1259<DD>Restartable means that if the decoder encounters the end of the buffer,
1260it will fail, but may later be invoked again with the rest of the
1261buffer to continue decoding.
1262
1263</DD>
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]1264<DT><A NAME="foot313">... encoding</A><A
1265 HREF="asn1c-usage.html#tex2html9"><SUP>4.3</SUP></A></DT>
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]1266<DD>It is actually faster too: the encoder might skip over some computations
1267which aren't important for the size determination.
1268
1269</DD>
1270</DL><BR><HR>
1271<ADDRESS>
1272Lev Walkin
Lev Walkin71a8aaf2004-09-08 03:10:54 +0000[diff] [blame]12732004-09-07
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]1274</ADDRESS>
1275</BODY>
1276</HTML>