Skip to content
Projects
Groups
Snippets
Help
Loading...
Help
Support
Keyboard shortcuts
?
Submit feedback
Contribute to GitLab
Sign in / Register
Toggle navigation
A
asn1c
Project overview
Project overview
Details
Activity
Releases
Repository
Repository
Files
Commits
Branches
Tags
Contributors
Graph
Compare
Issues
0
Issues
0
List
Boards
Labels
Milestones
Merge Requests
0
Merge Requests
0
CI / CD
CI / CD
Pipelines
Jobs
Schedules
Analytics
Analytics
CI / CD
Repository
Value Stream
Wiki
Wiki
Snippets
Snippets
Members
Members
Collapse sidebar
Close sidebar
Activity
Graph
Create a new issue
Jobs
Commits
Issue Boards
Open sidebar
Libraries
asn1c
Commits
26587ab2
Commit
26587ab2
authored
Aug 23, 2004
by
Lev Walkin
Browse files
Options
Browse Files
Download
Email Patches
Plain Diff
version 0.9
parent
5f869d00
Changes
3
Hide whitespace changes
Inline
Side-by-side
Showing
3 changed files
with
1005 additions
and
272 deletions
+1005
-272
doc/asn1c-usage.html
doc/asn1c-usage.html
+311
-215
doc/asn1c-usage.lyx
doc/asn1c-usage.lyx
+694
-57
doc/asn1c-usage.pdf
doc/asn1c-usage.pdf
+0
-0
No files found.
doc/asn1c-usage.html
View file @
26587ab2
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<!--Converted with LaTeX2HTML 2002-2-1 (1.70)
original version by: Nikos Drakos, CBLU, University of Leeds
...
...
@@ -11,8 +10,6 @@ original version by: Nikos Drakos, CBLU, University of Leeds
<META
NAME=
"description"
CONTENT=
"Using the Free ASN.1 Compiler"
>
<META
NAME=
"asn1c, ASN.1, free, compiler, BER, DER, PER, XER\"
>
<META
HTTP-EQUIV=
"Content-Type"
CONTENT=
"text/html; charset=iso-8859-1"
>
<META
HTTP-EQUIV=
"Content-Style-Type"
CONTENT=
"text/css"
>
</HEAD>
...
...
@@ -28,6 +25,8 @@ original version by: Nikos Drakos, CBLU, University of Leeds
<P
ALIGN=
"CENTER"
><STRONG>
Lev Walkin
<
vlm@lionet.info
>
</STRONG></P>
</DIV>
<P>
<BR>
<H2><A
NAME=
"SECTION01000000000000000000"
>
...
...
@@ -36,83 +35,97 @@ Contents</A>
<!--Table of Contents-->
<UL>
<LI><A
NAME=
"tex2html
38
"
<LI><A
NAME=
"tex2html
45
"
HREF=
"asn1c-usage.html#SECTION02000000000000000000"
>
ASN.1 Basics
</A>
<UL>
<LI><A
NAME=
"tex2html
39
"
<LI><A
NAME=
"tex2html
46
"
HREF=
"asn1c-usage.html#SECTION02100000000000000000"
>
Abstract Syntax Notation: ASN.1
</A>
<UL>
<LI><A
NAME=
"tex2html4
0
"
<LI><A
NAME=
"tex2html4
7
"
HREF=
"asn1c-usage.html#SECTION02110000000000000000"
>
Some of the ASN.1 Basic Types
</A>
<UL>
<LI><A
NAME=
"tex2html4
1
"
<LI><A
NAME=
"tex2html4
8
"
HREF=
"asn1c-usage.html#SECTION02111000000000000000"
>
The BOOLEAN type
</A>
<LI><A
NAME=
"tex2html4
2
"
<LI><A
NAME=
"tex2html4
9
"
HREF=
"asn1c-usage.html#SECTION02112000000000000000"
>
The INTEGER type
</A>
<LI><A
NAME=
"tex2html
43
"
<LI><A
NAME=
"tex2html
50
"
HREF=
"asn1c-usage.html#SECTION02113000000000000000"
>
The ENUMERATED type
</A>
<LI><A
NAME=
"tex2html
44
"
<LI><A
NAME=
"tex2html
51
"
HREF=
"asn1c-usage.html#SECTION02114000000000000000"
>
The OCTET STRING type
</A>
<LI><A
NAME=
"tex2html
45
"
<LI><A
NAME=
"tex2html
52
"
HREF=
"asn1c-usage.html#SECTION02115000000000000000"
>
The OBJECT IDENTIFIER type
</A>
<LI><A
NAME=
"tex2html
46
"
<LI><A
NAME=
"tex2html
53
"
HREF=
"asn1c-usage.html#SECTION02116000000000000000"
>
The RELATIVE-OID type
</A>
</UL>
<LI><A
NAME=
"tex2html
47
"
<LI><A
NAME=
"tex2html
54
"
HREF=
"asn1c-usage.html#SECTION02120000000000000000"
>
Some of the ASN.1 String Types
</A>
<UL>
<LI><A
NAME=
"tex2html
48
"
<LI><A
NAME=
"tex2html
55
"
HREF=
"asn1c-usage.html#SECTION02121000000000000000"
>
The IA5String type
</A>
<LI><A
NAME=
"tex2html
49
"
<LI><A
NAME=
"tex2html
56
"
HREF=
"asn1c-usage.html#SECTION02122000000000000000"
>
The UTF8String type
</A>
<LI><A
NAME=
"tex2html5
0
"
<LI><A
NAME=
"tex2html5
7
"
HREF=
"asn1c-usage.html#SECTION02123000000000000000"
>
The NumericString type
</A>
<LI><A
NAME=
"tex2html5
1
"
<LI><A
NAME=
"tex2html5
8
"
HREF=
"asn1c-usage.html#SECTION02124000000000000000"
>
The PrintableString type
</A>
<LI><A
NAME=
"tex2html5
2
"
<LI><A
NAME=
"tex2html5
9
"
HREF=
"asn1c-usage.html#SECTION02125000000000000000"
>
The VisibleString type
</A>
</UL>
<LI><A
NAME=
"tex2html
53
"
<LI><A
NAME=
"tex2html
60
"
HREF=
"asn1c-usage.html#SECTION02130000000000000000"
>
ASN.1 Constructed Types
</A>
<UL>
<LI><A
NAME=
"tex2html
54
"
<LI><A
NAME=
"tex2html
61
"
HREF=
"asn1c-usage.html#SECTION02131000000000000000"
>
The SEQUENCE type
</A>
<LI><A
NAME=
"tex2html
55
"
<LI><A
NAME=
"tex2html
62
"
HREF=
"asn1c-usage.html#SECTION02132000000000000000"
>
The SET type
</A>
<LI><A
NAME=
"tex2html
56
"
<LI><A
NAME=
"tex2html
63
"
HREF=
"asn1c-usage.html#SECTION02133000000000000000"
>
The CHOICE type
</A>
<LI><A
NAME=
"tex2html
57
"
<LI><A
NAME=
"tex2html
64
"
HREF=
"asn1c-usage.html#SECTION02134000000000000000"
>
The SEQUENCE OF type
</A>
<LI><A
NAME=
"tex2html
58
"
<LI><A
NAME=
"tex2html
65
"
HREF=
"asn1c-usage.html#SECTION02135000000000000000"
>
The SET OF type
</A>
</UL>
</UL>
</UL><BR>
<LI><A
NAME=
"tex2html
59
"
<LI><A
NAME=
"tex2html
66
"
HREF=
"asn1c-usage.html#SECTION03000000000000000000"
>
Using the ASN.1 Compiler
</A>
<UL>
<LI><A
NAME=
"tex2html6
0
"
<LI><A
NAME=
"tex2html6
7
"
HREF=
"asn1c-usage.html#SECTION03100000000000000000"
>
Introduction to the ASN.1 Compiler
</A>
<LI><A
NAME=
"tex2html68"
HREF=
"asn1c-usage.html#SECTION03200000000000000000"
>
Quick start
</A>
<LI><A
NAME=
"tex2html69"
HREF=
"asn1c-usage.html#SECTION03300000000000000000"
>
Using the ASN.1 Compiler
</A>
<UL>
<LI><A
NAME=
"tex2html61"
HREF=
"asn1c-usage.html#SECTION03110000000000000000"
>
Quick start
</A>
<LI><A
NAME=
"tex2html62"
HREF=
"asn1c-usage.html#SECTION03120000000000000000"
>
Slow start
</A>
<LI><A
NAME=
"tex2html70"
HREF=
"asn1c-usage.html#SECTION03310000000000000000"
>
Command-line options
</A>
<LI><A
NAME=
"tex2html71"
HREF=
"asn1c-usage.html#SECTION03320000000000000000"
>
Recognizing compiler output
</A>
<LI><A
NAME=
"tex2html72"
HREF=
"asn1c-usage.html#SECTION03330000000000000000"
>
Invoking the ASN.1 helper code from the application
</A>
<UL>
<LI><A
NAME=
"tex2html63"
HREF=
"asn1c-usage.html#SECTION03121000000000000000"
>
Recognizing compiler output
</A>
<LI><A
NAME=
"tex2html64"
HREF=
"asn1c-usage.html#SECTION03122000000000000000"
>
Invoking the ASN.1 helper code from the application
</A>
<LI><A
NAME=
"tex2html73"
HREF=
"asn1c-usage.html#SECTION03331000000000000000"
>
Decoding BER
</A>
<LI><A
NAME=
"tex2html74"
HREF=
"asn1c-usage.html#SECTION03332000000000000000"
>
Encoding DER
</A>
<LI><A
NAME=
"tex2html75"
HREF=
"asn1c-usage.html#SECTION03333000000000000000"
>
Validating the target structure
</A>
<LI><A
NAME=
"tex2html76"
HREF=
"asn1c-usage.html#SECTION03334000000000000000"
>
Printing the target structure
</A>
<LI><A
NAME=
"tex2html77"
HREF=
"asn1c-usage.html#SECTION03335000000000000000"
>
Freeing the target structure
</A>
</UL>
</UL>
</UL><BR>
<LI><A
NAME=
"tex2html
65
"
<LI><A
NAME=
"tex2html
78
"
HREF=
"asn1c-usage.html#SECTION04000000000000000000"
>
Bibliography
</A>
</UL>
<!--End of Table of Contents-->
<P>
<P>
<H1><A
NAME=
"SECTION02000000000000000000"
>
ASN.1 Basics
</A>
</H1>
...
...
@@ -157,15 +170,13 @@ Consider the following example:
<P>
<DD><PRE>
<BLOCKQUOTE><PRE>
Rectangle
::=
SEQUENCE
{
height
INTEGER,
width
INTEGER
}
</PRE>
</
DD
>
</
BLOCKQUOTE
>
This ASN.1 specification describes a constructed type,
<I>
Rectangle
</I>
,
containing two integer fields. This specification may tell the reader
that there is this kind of data structure and that some entity may
...
...
@@ -183,28 +194,27 @@ like this:
<P>
<DD><PRE>
<BLOCKQUOTE><PRE>
UsageExampleModule1
{
iso
org(3)
dod(6)
internet(1)
private(4)
enterprise(1)
spelio(9363)
software(1)
asn1c(5)
docs(2)
usage(1)
1
}
AUTOMATIC
TAGS
DEFINITION
S
::=
DEFINITIONS
AUTOMATIC
TAG
S
::=
BEGIN
--
This
is
a
comment
which
describes
nothing.
Rectangle
::=
SEQUENCE
{
height
INTEGER,
--
Height
of
the
rectangle
width
INTEGER
,
--
Width
of
the
rectangle
width
INTEGER
--
Width
of
the
rectangle
}
END
</PRE>
</
DD
>
</
BLOCKQUOTE
>
The module header consists of module name (UsageExampleModule1), the
module object identifier ({...}), some flags (AUTOMATIC TAGS) and
''DEFINITIONS ::= BEGIN''. The module ends with an ''END'' statement.
module object identifier ({...}), a keyword ''DEFINITIONS'', a
set of module flags (AUTOMATIC TAGS) and ''::= BEGIN''. The module
ends with an ''END'' statement.
<P>
...
...
@@ -235,16 +245,16 @@ necessary, the subtype constraints must be used.
<P>
<DD><PRE>
<BLOCKQUOTE><PRE>
SimpleInteger
::=
INTEGER
--
An
integer
with
a
very
limited
range
SmallInt
::=
INTEGER
(0..127)
--
Integer,
negative
NegativeInt
::=
INTEGER
(MIN..0)
</PRE>
</
DD
>
</
BLOCKQUOTE
>
<P>
...
...
@@ -258,11 +268,11 @@ with some integer values explicitly named.
<P>
<DD><PRE>
<BLOCKQUOTE><PRE>
FruitId
::=
ENUMERATED
{
apple(1),
orange(2)
}
--
The
numbers
in
braces
are
optional,
--
the
enumeration
may
be
performed
--
the
enumeration
can
be
performed
--
automatically
by
the
compiler
ComputerOSType
::=
ENUMERATED
{
FreeBSD,
--
will
be
0
...
...
@@ -271,9 +281,8 @@ ComputerOSType ::= ENUMERATED {
Linux,
--
will
be
6
MacOS
--
will
be
7
}
</PRE>
</
DD
>
</
BLOCKQUOTE
>
<P>
...
...
@@ -305,18 +314,18 @@ following OBJECT IDENTIFIER: 1 3 6 1 4 1 9363 1 5 2 1 1.
<P>
<DD><PRE>
<BLOCKQUOTE><PRE>
ExampleOID
::=
OBJECT
IDENTIFIER
usageExampleModule1-oid
ExampleOID
::=
{
1
3
6
1
4
1
9363
1
5
2
1
1
}
--
An
identifier
of
the
Internet.
internet-id
OBJECT
IDENTIFIER
::=
{
iso(1)
identified-organization(3)
dod(6)
internet(1)
}
</PRE>
</
DD
>
</
BLOCKQUOTE
>
As you see, names are optional.
<P>
...
...
@@ -333,14 +342,13 @@ is some of the tree's subsequence.
<P>
<DD><PRE>
<BLOCKQUOTE><PRE>
this-document
RELATIVE-OID
::=
{
docs(2)
usage(1)
}
this-example
RELATIVE-OID
::=
{
this-document
assorted-examples(0)
this-example(1)
}
</PRE>
</
DD
>
</
BLOCKQUOTE
>
<P>
...
...
@@ -356,7 +364,7 @@ The IA5String type</A>
<P>
This is essentially the ASCII, with 128 character codes available
(7 lower bits of 8-bit byte).
(7 lower bits of
an
8-bit byte).
<P>
...
...
@@ -400,15 +408,15 @@ The VisibleString type</A>
<P>
The character string with the alphabet which is more or less a subset
of ASCII between space and ''
~'' (tilde). Alternatively,
the alphabet may be represented as the PrintableString alphabet described
earlier, plus the following characters: ''
<B>
!
</B>
'', ''
<B>
''
</B>
'',
''
<B>
#
</B>
'', ''
<B>
$
</B>
'', ''
<B>
%
</B>
'', ''
<B>
&
</B>
'',
''
<B>
*
</B>
'', ''
<B>
;
</B>
'', ''
<B>
<
</B>
'', ''
<B>
&g
t;
</B>
'',
''
<B>
[
</B>
'', ''
<B>
\
</B>
'', ''
<B>
]
</B>
'',
''
<B>
^
</B>
'', ''
<B>
_
</B>
'', ''
<B>
`
</B>
''
(single left quote), ''
<B>
{
</B>
'', ''
<B>
|
</B>
'', ''
<B>
}
</B>
'',
''
~
''.
of ASCII between space and ''
<B>
~
</B>
'' (tilde).
Alternatively, the alphabet may be described as the PrintableString
alphabet presented earlier, plus the following characters: ''
<B>
!
</B>
'',
''
<B>
''
</B>
'', ''
<B>
#
</B>
'', ''
<B>
$
</B>
'', ''
<B>
%
</B>
'',
''
<B>
&
</B>
'', ''
<B>
*
</B>
'', ''
<B>
;
</B>
'', ''
<B>
&l
t;
</B>
'',
''
<B>
>
</B>
'', ''
<B>
[
</B>
'', ''
<B>
\
</B>
'',
''
<B>
]
</B>
'', ''
<B>
^
</B>
'', ''
<B>
_
</B>
'',
''
<B>
`
</B>
'' (single left quote), ''
<B>
{
</B>
'', ''
<B>
|
</B>
'',
''
<B>
}
</B>
'', ''
<B>
~
</B>
''.
<P>
...
...
@@ -428,8 +436,7 @@ The SEQUENCE constructed type resembles the C ''struct'' statement.
<P>
<DD><PRE>
<BLOCKQUOTE><PRE>
Address
::=
SEQUENCE
{
--
The
apartment
number
may
be
omitted
apartmentNumber
NumericString
OPTIONAL,
...
...
@@ -439,9 +446,8 @@ Address ::= SEQUENCE {
--
This
one
may
be
omitted
too
zipNo
NumericString
OPTIONAL
}
</PRE>
</
DD
>
</
BLOCKQUOTE
>
<P>
...
...
@@ -473,15 +479,13 @@ integer code or a boolean ''true''/''false'' code.
<P>
<DD><PRE>
<BLOCKQUOTE><PRE>
ResponseCode
::=
CHOICE
{
intCode
INTEGER,
boolCode
BOOLEAN
}
</PRE>
</
DD
>
</
BLOCKQUOTE
>
<P>
...
...
@@ -494,20 +498,20 @@ This one is the list (array) of simple or constructed types:
<P>
<DD><PRE>
<BLOCKQUOTE><PRE>
--
Example
1
ManyIntegers
::=
SEQUENCE
OF
INTEGER
--
Example
2
ManyRectangles
::=
SEQUENCE
OF
Rectangle
--
More
complex
example:
--
an
array
of
structures
defined
in
place.
ManyCircles
::=
SEQUENCE
OF
SEQUENCE
{
radius
INTEGER
}
</PRE>
</
DD
>
</
BLOCKQUOTE
>
<P>
...
...
@@ -523,15 +527,14 @@ on the remote machines.
<P>
<DD><PRE>
<BLOCKQUOTE><PRE>
--
A
set
of
structures
defined
elsewhere
SetOfApples
::
SET
OF
Apple
--
Set
of
integers
encoding
the
kind
of
a
fruit
FruitBag
::=
SET
OF
ENUMERATED
{
apple,
orange
}
</PRE>
</
DD
>
</
BLOCKQUOTE
>
<P>
...
...
@@ -549,92 +552,198 @@ Introduction to the ASN.1 Compiler</A>
The purpose of the ASN.1 compiler, of which this document is part,
is to convert the ASN.1 specifications to some other target language
(currently, only C is supported
<A
NAME=
"tex2html1"
HREF=
"#foot1
36
"
><SUP>
2.1
</SUP></A>
). The compiler reads the specification and emits a series of target
HREF=
"#foot1
44
"
><SUP>
2.1
</SUP></A>
). The compiler reads the specification and emits a series of target
language structures and surrounding maintenance code. For example,
the C structure which may be created by compiler to represent the
simple
<I>
Rectangle
</I>
specification defined earlier in this document,
may look like this
<A
NAME=
"tex2html2"
HREF=
"#foot3
15
"
><SUP>
2.2
</SUP></A>
:
HREF=
"#foot3
79
"
><SUP>
2.2
</SUP></A>
:
<P>
<DD><PRE>
<BLOCKQUOTE><PRE>
typedef
struct
Rectangle_s
{
int
height;
int
width;
}
Rectangle_t;
</PRE>
</
DD
>
</
BLOCKQUOTE
>
This would not be of much value for such a simple specification, so
the compiler goes further and actually produces the code which fills
in this structure by parsing the binary
<A
NAME=
"tex2html3"
HREF=
"#foot1
42
"
><SUP>
2.3
</SUP></A>
data provided in some buffer. It also produces the code that takes
in this structure by parsing the
opaque
binary
<A
NAME=
"tex2html3"
HREF=
"#foot1
51
"
><SUP>
2.3
</SUP></A>
data provided in some buffer. It also produces the code that takes
this structure as an argument and performs structure serialization
by emitting a series of bytes.
<P>
<H1><A
NAME=
"SECTION03
11
0000000000000000"
>
<H1><A
NAME=
"SECTION03
20
0000000000000000"
>
Quick start
</A>
</H1>
<P>
After building and installing the compiler, the
asn1c command may
be used to compile the ASN.1 specification
<A
NAME=
"tex2html4
"
HREF=
"#foot3
16"
><SUP>
2.4
</SUP></A>
:
After building and installing the compiler, the
<I>
asn1c
</I><A
NAME=
"tex2html4"
HREF=
"#foot380"
><SUP>
3.1
</SUP></A>
command may be used to compile the ASN.1 specification
<A
NAME=
"tex2html5
"
HREF=
"#foot3
81"
><SUP>
3.2
</SUP></A>
:
<P>
<DD><PRE>
<BLOCKQUOTE><PRE>
asn1c
<I>
<
spec.asn1
>
</I>
</PRE>
</
DD
>
If several specifications contain interdependencies, all of the
m must
be specified
:
</
BLOCKQUOTE
>
If several specifications contain interdependencies, all of the
files
must be specified altogether
:
<P>
<DD><PRE>
<BLOCKQUOTE><PRE>
asn1c
<I>
<
spec1.asn1
> <
spec2.asn1
>
...
</I>
</PRE>
</
DD
>
The compiler
-E and -EF options are used for testing the parser and
the
semantic fixer, respectively. These options will instruct the
compiler to dump out the parsed (and fixed) ASN.1 specification as
i
t was
"
understood
"
by the compiler. It might might
b
e useful to check whether a particular syntactic construction is
properly supported by the compiler.
</
BLOCKQUOTE
>
The compiler
<B>
-E
</B>
and
<B>
-EF
</B>
options are used for testing
the
parser and the semantic fixer, respectively. These options will
instruct the compiler to dump out the parsed (and fixed, if
<B>
-F
</B>
i
s involved) ASN.1 specification as it was
"
understood
"
b
y the compiler. It might be useful to check whether a particular
syntactic construction is
properly supported by the compiler.
<P>
<DD><PRE>
<BLOCKQUOTE><PRE>
asn1c
<B>
-EF
</B>
<I>
<
spec-to-test.asn1
>
</I>
</PRE>
</BLOCKQUOTE>
The
<B>
-P
</B>
option is used to dump the compiled output on the
screen instead of creating a bunch of .c and .h files on disk in the
current directory. You would probably want to start with
<B>
-P
</B>
option instead of creating a mess in your current directory. Another
option,
<B>
-R
</B>
, asks compiler to only generate the files which
need to be generated, and supress linking in the numerous support
files.
<P>
Print the compiled output instead of creating multiple source files:
asn1c
-EF
<I>
<
spec-to-test.asn1
>
</I
>
<P
>
<BLOCKQUOTE><PRE>
asn1c
<B>
-P
</B>
<I>
<
spec-to-compile-and-print.asn1
>
</I>
</PRE>
</DD>
The -P option is used to dump the compiled output on the screen instead
of creating a bunch of .c and .h files on disk in the current directory.
You would probably want to start with -P option instead of creating
a mess in your current directory.
</BLOCKQUOTE>
<P>
<H1><A
NAME=
"SECTION03
12
0000000000000000"
>
Slow start
</A>
<H1><A
NAME=
"SECTION03
30
0000000000000000"
>
Using the ASN.1 Compiler
</A>
</H1>
<P>
<H2><A
NAME=
"SECTION03121000000000000000"
>
<H1><A
NAME=
"SECTION03310000000000000000"
>
Command-line options
</A>
</H1>
<P>
The
<A
HREF=
#Table1
>
Table 1
</A>
summarizes various options affecting
the compiler's behavior.
<P>
<BR><P></P>
<DIV
ALIGN=
"CENTER"
><A
NAME=
"384"
></A>
<TABLE>
<CAPTION><STRONG><A
NAME=
Table1
>
Table 1:
</A></STRONG>
The list of asn1c command line options
</CAPTION>
<TR><TD><TABLE
COLS=
2
BORDER
FRAME=
BOX
RULES=
GROUPS
>
<COLGROUP><COL
ALIGN=
LEFT
><COLGROUP><COL
ALIGN=
JUSTIFY
WIDTH=
"3in"
>
<TBODY>
<TR><TD
VALIGN=
BASELINE
ALIGN=
LEFT
NOWRAP
>
<B>
Overall Options
</B></TD><TD
VALIGN=
BASELINE
ALIGN=
LEFT
WIDTH=
"216"
>
<B>
Description
</B></TD></TR>
</TBODY><TBODY>
<TR><TD
VALIGN=
BASELINE
ALIGN=
LEFT
NOWRAP
>
-E
</TD><TD
VALIGN=
BASELINE
ALIGN=
LEFT
WIDTH=
"216"
>
<FONT
SIZE=
"-1"
>
Stop after the parsing stage and print the reconstructed ASN.1
specification code to the standard output.
</FONT></TD></TR>
</TBODY><TBODY>
<TR><TD
VALIGN=
BASELINE
ALIGN=
LEFT
NOWRAP
>
-F
</TD><TD
VALIGN=
BASELINE
ALIGN=
LEFT
WIDTH=
"216"
>
<FONT
SIZE=
"-1"
>
Used together with -E, instructs the compiler to stop after
the ASN.1 syntax tree fixing stage and dump the reconstructed ASN.1
specification to the standard output.
</FONT></TD></TR>
</TBODY><TBODY>
<TR><TD
VALIGN=
BASELINE
ALIGN=
LEFT
NOWRAP
>
-P
</TD><TD
VALIGN=
BASELINE
ALIGN=
LEFT
WIDTH=
"216"
>
<FONT
SIZE=
"-1"
>
Dump the compiled output to the standard output instead of
cre- ating the target language files on disk.
</FONT></TD></TR>
</TBODY><TBODY>
<TR><TD
VALIGN=
BASELINE
ALIGN=
LEFT
NOWRAP
>
-R
</TD><TD
VALIGN=
BASELINE
ALIGN=
LEFT
WIDTH=
"216"
>
<FONT
SIZE=
"-1"
>
Restrict the compiler to generate only the ASN.1 tables, omit-
ting the usual support code.
</FONT></TD></TR>
</TBODY><TBODY>
<TR><TD
VALIGN=
BASELINE
ALIGN=
LEFT
NOWRAP
>
-S
<I>
<
directory
>
</I></TD><TD
VALIGN=
BASELINE
ALIGN=
LEFT
WIDTH=
"216"
>
<FONT
SIZE=
"-1"
>
Use the specified directory with ASN.1 skeleton files.
</FONT></TD></TR>
</TBODY><TBODY>
<TR><TD
VALIGN=
BASELINE
ALIGN=
LEFT
NOWRAP
>
-t
<I>
<
data-string
>
</I></TD><TD
VALIGN=
BASELINE
ALIGN=
LEFT
WIDTH=
"216"
>
<FONT
SIZE=
"-1"
>
Interpret the data-string as a sequence of hexadecimal values
representing the start of BER TLV encoding. Print the human readable
explanation.
</FONT></TD></TR>
</TBODY><TBODY>
<TR><TD
VALIGN=
BASELINE
ALIGN=
LEFT
NOWRAP
><B>
Warning Options
</B></TD><TD
VALIGN=
BASELINE
ALIGN=
LEFT
WIDTH=
"216"
>
<B>
Description
</B></TD></TR>
</TBODY><TBODY>
<TR><TD
VALIGN=
BASELINE
ALIGN=
LEFT
NOWRAP
>
-Werror
</TD><TD
VALIGN=
BASELINE
ALIGN=
LEFT
WIDTH=
"216"
>
<FONT
SIZE=
"-1"
>
Treat warnings as errors; abort if any warning is produced.
</FONT></TD></TR>
</TBODY><TBODY>
<TR><TD
VALIGN=
BASELINE
ALIGN=
LEFT
NOWRAP
>
-Wdebug-lexer
</TD><TD
VALIGN=
BASELINE
ALIGN=
LEFT
WIDTH=
"216"
>
<FONT
SIZE=
"-1"
>
Enable lexer debugging during the ASN.1 parsing stage.
</FONT></TD></TR>
</TBODY><TBODY>
<TR><TD
VALIGN=
BASELINE
ALIGN=
LEFT
NOWRAP
>
-Wdebug-fixer
</TD><TD
VALIGN=
BASELINE
ALIGN=
LEFT
WIDTH=
"216"
>
<FONT
SIZE=
"-1"
>
Enable ASN.1 syntax tree fixer debugging during the
fixing stage.
</FONT></TD></TR>
</TBODY><TBODY>
<TR><TD
VALIGN=
BASELINE
ALIGN=
LEFT
NOWRAP
>
-Wdebug-compiler
</TD><TD
VALIGN=
BASELINE
ALIGN=
LEFT
WIDTH=
"216"
>
<FONT
SIZE=
"-1"
>
Enable debugging during the actual compile time.
</FONT></TD></TR>
</TBODY><TBODY>
<TR><TD
VALIGN=
BASELINE
ALIGN=
LEFT
NOWRAP
><B>
Language Options
</B></TD><TD
VALIGN=
BASELINE
ALIGN=
LEFT
WIDTH=
"216"
>
<B>
Description
</B></TD></TR>
</TBODY><TBODY>
<TR><TD
VALIGN=
BASELINE
ALIGN=
LEFT
NOWRAP
>
-fbless-SIZE
</TD><TD
VALIGN=
BASELINE
ALIGN=
LEFT
WIDTH=
"216"
>
<FONT
SIZE=
"-1"
>
Allow SIZE() constraint for INTEGER, ENUMERATED, and other
types for which this constraint is normally prohibited by the standard.
This is a violation of an ASN.1 standard and compiler may fail to
produce the meaningful code.
</FONT></TD></TR>
</TBODY><TBODY>
<TR><TD
VALIGN=
BASELINE
ALIGN=
LEFT
NOWRAP
>
-fnative-integers
</TD><TD
VALIGN=
BASELINE
ALIGN=
LEFT
WIDTH=
"216"
>
<FONT
SIZE=
"-1"
>
Use native machine's integer types whenever possible, instead
of the complex ASN.1 INTEGER and ENUMERATED types.
</FONT></TD></TR>
</TBODY><TBODY>
<TR><TD
VALIGN=
BASELINE
ALIGN=
LEFT
NOWRAP
>
-funnamed-unions
</TD><TD
VALIGN=
BASELINE
ALIGN=
LEFT
WIDTH=
"216"
>
<FONT
SIZE=
"-1"
>
Enable unnamed unions in the definitions of target language's
structures.
</FONT></TD></TR>
</TBODY><TBODY>
<TR><TD
VALIGN=
BASELINE
ALIGN=
LEFT
NOWRAP
>
-ftypes88
</TD><TD
VALIGN=
BASELINE
ALIGN=
LEFT
WIDTH=
"216"
>
<FONT
SIZE=
"-1"
>
Use only ASN.1:1988 embedded types.
</FONT></TD></TR>
</TBODY><TBODY>
<TR><TD
VALIGN=
BASELINE
ALIGN=
LEFT
NOWRAP
><B>
Output Options
</B></TD><TD
VALIGN=
BASELINE
ALIGN=
LEFT
WIDTH=
"216"
>
<B>
Description
</B></TD></TR>
</TBODY><TBODY>
<TR><TD
VALIGN=
BASELINE
ALIGN=
LEFT
NOWRAP
>
-print-constraints
</TD><TD
VALIGN=
BASELINE
ALIGN=
LEFT
WIDTH=
"216"
>
<FONT
SIZE=
"-1"
>
When -EF are also specified, this option forces the compiler
to explain its internal understanding of subtype constraints.
</FONT></TD></TR>
</TBODY><TBODY>
<TR><TD
VALIGN=
BASELINE
ALIGN=
LEFT
NOWRAP
>
-print-lines
</TD><TD
VALIGN=
BASELINE
ALIGN=
LEFT
WIDTH=
"216"
>
<FONT
SIZE=
"-1"
>
Generate
"
- #line
"
comments in -E output.
</FONT></TD></TR>
</TBODY>
</TABLE>
<P>
</TD></TR>
</TABLE>
</DIV><P></P><BR>
<P>
<H1><A
NAME=
"SECTION03320000000000000000"
>
Recognizing compiler output
</A>
</H
2
>
</H
1
>
<P>
After compiling, the following entities will be created in your current
...
...
@@ -649,10 +758,9 @@ the ASN.1 types (<I>Rectangle.c</I> and <I>Rectangle.h</I> for the
specification defined in the beginning of this document).
</LI>
<LI>
A set of helper .c and .h files which contain generic encoders, decoders
and other useful routines. There will be many of them, some of them
even not necessary
<A
NAME=
"tex2html5"
HREF=
"#foot161"
><SUP>
2.5
</SUP></A>
, but the overall amount of code after compiling will be rather small
anyway.
and other useful routines. There will be quite a few of them, some
of them even are not always necessary, but the overall amount of code
after compiling will be rather small anyway.
</LI>
</UL>
It is your responsibility to create .c file with the
<I>
int main()
</I>
...
...
@@ -670,33 +778,29 @@ be possible to compile everything with the single instruction:
<P>
<DD><PRE>
cc
-o
rectangle
*.c
#
It
could
be
<I>
that
</I>
simple
<A
NAME=
"tex2html6"
HREF=
"#foot319"
><SUP>
2.6
</SUP></A>
<BLOCKQUOTE><PRE>
cc
-o
rectangle
*.c
#
It
could
be
<I>
that
</I>
simple
<A
NAME=
"tex2html7"
HREF=
"#foot387"
><SUP>
4.1
</SUP></A>
</PRE>
</
DD
>
</
BLOCKQUOTE
>
<P>
<H
2><A
NAME=
"SECTION03122
000000000000000"
>
<H
1><A
NAME=
"SECTION03330
000000000000000"
>
Invoking the ASN.1 helper code from the application
</A>
</H
2
>
</H
1
>
<P>
First of all, you
would want
to include one or more header files into
your application. For
the
Rectangle module, including the Rectangle.h
First of all, you
should
to include one or more header files into
your application. For
our
Rectangle module, including the Rectangle.h
file is enough:
<P>
<DD><PRE>
<BLOCKQUOTE><PRE>
#include
<
Rectangle.h
>
</PRE>
</
DD
>
</
BLOCKQUOTE
>
The header files defines the C structure corresponding to the ASN.1
definition of a rectangle and the declaration of the ASN.1 type descriptor,
which is used as an argument to most of the functions provided by
...
...
@@ -705,14 +809,13 @@ structure:
<P>
<
DD
><PRE>
Rectangle_t
*rect
=
;
<
BLOCKQUOTE
><PRE>
Rectangle_t
*rect
=
...;
 
;
asn1_DEF_Rectangle-
>
free_struct(
&
asn1_DEF_Rectangle,
rect,
0);
</PRE>
</
DD
>
</
BLOCKQUOTE
>
This code defines a
<I>
rect
</I>
pointer which points to the Rectangle_t
structure which needs to be freed. The second line invokes the generic
free_struct routine created specifically for this Rectangle_t structure.
...
...
@@ -730,8 +833,8 @@ are semantically valid and constrained to appropriate implicit or
explicit subtype constraints. Please refer to Section sub:Validating-the-target.
</DD>
<DT><STRONG>
ber_decoder
</STRONG></DT>
<DD>
This is the generic
<I>
restartable
</I><A
NAME=
"tex2html
7
"
HREF=
"#foot
183"
><SUP>
2.7
</SUP></A>
BER decoder (Basic Encoding Rules). This decoder would create
<DD>
This is the generic
<I>
restartable
</I><A
NAME=
"tex2html
8
"
HREF=
"#foot
241"
><SUP>
4.2
</SUP></A>
BER decoder (Basic Encoding Rules). This decoder would create
and/or fill the target structure for you. Please refer to Section
[
<A
HREF=
"#sub:Decoding-BER"
>
Decoding-BER
</A>
].
</DD>
...
...
@@ -761,10 +864,9 @@ Here is how the buffer can be deserialized into the structure:
<P>
<DD><PRE>
<BLOCKQUOTE><PRE>
Rectangle_t
*
simple_deserializer(void
*buffer,
size_t
buf_size)
{
simple_deserializer(
const
void
*buffer,
size_t
buf_size)
{
Rectangle_t
*rect
=
0;
/*
Note
this
0!
*/
ber_dec_rval_t
rval;
...
...
@@ -777,14 +879,14 @@ simple_deserializer(void *buffer, size_t buf_size) {
if(rval
<B>
.code
</B>
==
RC_OK)
{
return
rect;
/*
Decoding
succeeded
*/
}
else
{
/*
Free
partially
decoded
rect
*/
asn1_DEF_Rectangle-
>
free_struct(
&
asn1_DEF_Rectangle,
rect,
0);
return
0;
}
}
</PRE>
</
DD
>
</
BLOCKQUOTE
>
The code above defines a function,
<I>
simple_deserializer
</I>
, which
takes a buffer and its length and expected to return a pointer to
the Rectangle_t structure. Inside, it tries to convert the bytes
...
...
@@ -807,9 +909,9 @@ Section sub:Decoding-BER
<P>
<H
3><A
NAME=
"SECTION031221
00000000000000"
></A><A
NAME=
"sub:Decoding-BER"
></A><BR>
<H
2><A
NAME=
"SECTION033310
00000000000000"
></A><A
NAME=
"sub:Decoding-BER"
></A><BR>
Decoding BER
</H
3
>
</H
2
>
<P>
The Basic Encoding Rules describe the basic way how the structure
...
...
@@ -859,13 +961,11 @@ wrapper of the former approach into a less wordy notation:
<P>
<DD><PRE>
<BLOCKQUOTE><PRE>
rval
=
ber_decode(
&
asn1_DEF_Rectangle,
(void
**)
&
rect,
buffer,
buf_size);
</PRE>
</
DD
>
</
BLOCKQUOTE
>
Note that the initial (asn1_DEF_Rectangle-
>
ber_decoder) reference
is gone, and also the last argument (0) is no longer necessary.
...
...
@@ -901,9 +1001,9 @@ and related types.
<P>
<H
3><A
NAME=
"SECTION031222
00000000000000"
></A><A
NAME=
"sub:Encoding-DER"
></A><BR>
<H
2><A
NAME=
"SECTION033320
00000000000000"
></A><A
NAME=
"sub:Encoding-DER"
></A><BR>
Encoding DER
</H
3
>
</H
2
>
<P>
The Distinguished Encoding Rules is the variant of BER encoding rules
...
...
@@ -920,13 +1020,13 @@ stand-alone function, which is somewhat simpler:
<P>
<DD><PRE>
<BLOCKQUOTE><PRE>
/*
*
This
is
a
custom
function
which
writes
the
*
encoded
output
into
some
FILE
stream.
*/
int
_write_stream(void
*buffer,
size_t
size,
void
*app_key)
{
static
int
write_stream(const
void
*buffer,
size_t
size,
void
*app_key)
{
FILE
*ostream
=
app_key;
size_t
wrote;
...
...
@@ -945,7 +1045,7 @@ simple_serializer(FILE *ostream, Rectangle_t *rect) {
der_enc_rval_t
rval;
/*
Return
value
*/
rval
=
der_encode(
&
asn1_DEF_Rect,
rect,
_
write_stream,
ostream);
write_stream,
ostream);
if(rval
<B>
.encoded
</B>
==
-1)
{
/*
*
Failure
to
encode
the
rectangle
data.
...
...
@@ -959,9 +1059,8 @@ simple_serializer(FILE *ostream, Rectangle_t *rect) {
return
rval.encoded;
}
}
</PRE>
</
DD
>
</
BLOCKQUOTE
>
As you see, the DER encoder does not write into some sort of buffer
or something. It just invokes the custom function (possible, multiple
times) which would save the data into appropriate storage. The optional
...
...
@@ -974,8 +1073,8 @@ If the custom write function is not given (passed as 0), then the
DER encoder will essentially do the same thing (i.e., encode the data)
but no callbacks will be invoked (so the data goes nowhere). It may
prove useful to determine the size of the structure's encoding before
actually doing the encoding
<A
NAME=
"tex2html
8
"
HREF=
"#foot
253"
><SUP>
2.8
</SUP></A>
.
actually doing the encoding
<A
NAME=
"tex2html
9
"
HREF=
"#foot
313"
><SUP>
4.3
</SUP></A>
.
<P>
Please look into der_encoder.h for the precise definition of der_encode()
...
...
@@ -983,9 +1082,9 @@ and related types.
<P>
<H
3><A
NAME=
"SECTION031223
00000000000000"
></A><A
NAME=
"sub:Validating-the-target"
></A><BR>
<H
2><A
NAME=
"SECTION033330
00000000000000"
></A><A
NAME=
"sub:Validating-the-target"
></A><BR>
Validating the target structure
</H
3
>
</H
2
>
<P>
Sometimes the target structure needs to be validated. For example,
...
...
@@ -1011,9 +1110,9 @@ and related types.
<P>
<H
3><A
NAME=
"SECTION031224
00000000000000"
></A><A
NAME=
"sub:Printing-the-target"
></A><BR>
<H
2><A
NAME=
"SECTION033340
00000000000000"
></A><A
NAME=
"sub:Printing-the-target"
></A><BR>
Printing the target structure
</H
3
>
</H
2
>
<P>
There are two ways to print the target structure: either invoke the
...
...
@@ -1022,20 +1121,18 @@ function, which is a simpler wrapper of the former:
<P>
<DD><PRE>
<BLOCKQUOTE><PRE>
asn_fprint(stdout,
&
asn1_DEF_Rectangle,
rect);
</PRE>
</
DD
>
</
BLOCKQUOTE
>
Please look into constr_TYPE.h for the precise definition of asn_fprint()
and related types.
<P>
<H
3><A
NAME=
"SECTION031225
00000000000000"
></A><A
NAME=
"sub:Freeing-the-target"
></A><BR>
<H
2><A
NAME=
"SECTION033350
00000000000000"
></A><A
NAME=
"sub:Freeing-the-target"
></A><BR>
Freeing the target structure
</H
3
>
</H
2
>
<P>
Freeing the structure is slightly more complex than it may seem to.
...
...
@@ -1046,17 +1143,15 @@ case:
<P>
<DD><PRE>
<BLOCKQUOTE><PRE>
struct
my_figure
{
/*
The
custom
structure
*/
int
flags;
/*
<
some
custom
member
>
*/
/*
The
type
is
generated
by
the
ASN.1
compiler
*/
<I>
Rectangle_t
rect;
</I>
/*
other
members
of
the
structure
*/
};
</PRE>
</
DD
>
</
BLOCKQUOTE
>
In this example, the application programmer defined a custom structure
with one ASN.1-derived member (rect). This member is not a reference
to the Rectangle_t, but an in-place inclusion of the Rectangle_t
...
...
@@ -1075,8 +1170,7 @@ value).
<P>
<DD><PRE>
<BLOCKQUOTE><PRE>
/*
Rectangle_t
is
defined
within
my_figure
*/
struct
my_figure
*mf
=
<B>
...
</B>
;
/*
...
...
@@ -1094,9 +1188,8 @@ Rectangle_t *rect = <B>...</B>;
*/
asn1_DEF_Rectangle-
>
free_struct(
&
asn1_DEF_Rectangle,
rect,
<I>
0
</I>
/*
free
the
pointer
too
*/);
</PRE>
</
DD
>
</
BLOCKQUOTE
>
It is safe to invoke the
<I>
free_struct
</I>
function with the target
structure pointer set to 0 (NULL), the function will do nothing.
...
...
@@ -1104,7 +1197,9 @@ structure pointer set to 0 (NULL), the function will do nothing.
<H2><A
NAME=
"SECTION04000000000000000000"
>
Bibliography
</A>
</H2><DL
COMPACT
><DD><P></P><DT><A
NAME=
"Dub00"
>
Dub00
</A>
</H2><DL
COMPACT
><DD><P></P><DT><A
NAME=
"ASN1C"
>
ASN1C
</A>
<DD>
Free ASN.1 Compiler. http://lionet.info/asn1/
<P></P><DT><A
NAME=
"Dub00"
>
Dub00
</A>
<DD>
Olivier Dubuisson -
<I>
ASN.1 Communication between heterogeneous
systems
</I>
- Morgan Kaufmann Publishers, 2000. http://asn1.elibel.tm.fr/en/book/.
ISBN:0-12-6333361-0.
...
...
@@ -1114,51 +1209,52 @@ ISBN:0-12-6333361-0.
<P>
<BR><HR><H4>
Footnotes
</H4>
<DL>
<DT><A
NAME=
"foot1
36
"
>
... supported
</A><A
<DT><A
NAME=
"foot1
44
"
>
... supported
</A><A
HREF=
"asn1c-usage.html#tex2html1"
><SUP>
2.1
</SUP></A></DT>
<DD>
C++ is ''supported'' too, as long as an
object-oriented approach
is
not a definitive factor.
<DD>
C++ is ''supported'' too, as long as an
class-based approach is
not a definitive factor.
</DD>
<DT><A
NAME=
"foot3
15
"
>
... this
</A><A
<DT><A
NAME=
"foot3
79
"
>
... this
</A><A
HREF=
"asn1c-usage.html#tex2html2"
><SUP>
2.2
</SUP></A></DT>
<DD><I>
-fnative-integers
</I>
compiler option is used to produce basic
C
<I>
int
</I>
types instead of generic INTEGER_t.
C
<I>
int
</I>
types instead of infinite width INTEGER_t structures.
See
<A
HREF=
#Table1
>
Table 1
</A>
.
</DD>
<DT><A
NAME=
"foot1
42
"
>
... binary
</A><A
<DT><A
NAME=
"foot1
51
"
>
... binary
</A><A
HREF=
"asn1c-usage.html#tex2html3"
><SUP>
2.3
</SUP></A></DT>
<DD>
BER, CER and DER encodings are binary. However, the XER encoding is
text (XML) based.
</DD>
<DT><A
NAME=
"foot316"
>
... specification
</A><A
HREF=
"asn1c-usage.html#tex2html4"
><SUP>
2.4
</SUP></A></DT>
<DD>
This is probably
<B>
not
</B>
what you want to try out right now -
read through the rest of this chapter to find out about -P option.
<DT><A
NAME=
"foot380"
>
...asn1c
</A><A
HREF=
"asn1c-usage.html#tex2html4"
><SUP>
3.1
</SUP></A></DT>
<DD>
The 1 symbol in asn
<B>
1
</B>
c is a digit, not an ''ell'' letter.
</DD>
<DT><A
NAME=
"foot161"
>
... necessary
</A><A
HREF=
"asn1c-usage.html#tex2html5"
><SUP>
2.5
</SUP></A></DT>
<DD>
Soon the compiler will be modified to emit the smallest subset of
necessary files.
<DT><A
NAME=
"foot381"
>
... specification
</A><A
HREF=
"asn1c-usage.html#tex2html5"
><SUP>
3.2
</SUP></A></DT>
<DD>
This is probably
<B>
not
</B>
what you want to try out right now -
read through the rest of this chapter to find out about
<B>
-P
</B>
and
<B>
-R
</B>
options.
</DD>
<DT><A
NAME=
"foot3
19
"
>
...that
simple
</A><A
HREF=
"asn1c-usage.html#tex2html
6"
><SUP>
2.6
</SUP></A></DT>
<DT><A
NAME=
"foot3
87
"
>
...that
simple
</A><A
HREF=
"asn1c-usage.html#tex2html
7"
><SUP>
4.1
</SUP></A></DT>
<DD>
Provided that you've also created a .c file with the
<I>
int main()
</I>
routine.
</DD>
<DT><A
NAME=
"foot
183
"
>
...restartable
</A><A
HREF=
"asn1c-usage.html#tex2html
7"
><SUP>
2.7
</SUP></A></DT>
<DT><A
NAME=
"foot
241
"
>
...restartable
</A><A
HREF=
"asn1c-usage.html#tex2html
8"
><SUP>
4.2
</SUP></A></DT>
<DD>
Restartable means that if the decoder encounters the end of the buffer,
it will fail, but may later be invoked again with the rest of the
buffer to continue decoding.
</DD>
<DT><A
NAME=
"foot
25
3"
>
... encoding
</A><A
HREF=
"asn1c-usage.html#tex2html
8"
><SUP>
2.8
</SUP></A></DT>
<DT><A
NAME=
"foot
31
3"
>
... encoding
</A><A
HREF=
"asn1c-usage.html#tex2html
9"
><SUP>
4.3
</SUP></A></DT>
<DD>
It is actually faster too: the encoder might skip over some computations
which aren't important for the size determination.
...
...
@@ -1166,7 +1262,7 @@ which aren't important for the size determination.
</DL><BR><HR>
<ADDRESS>
Lev Walkin
2004-08-
06
2004-08-
23
</ADDRESS>
</BODY>
</HTML>
doc/asn1c-usage.lyx
View file @
26587ab2
#LyX 1.3 created this file. For more info see http://www.lyx.org/
\lyxformat 221
\textclass book
\begin_preamble
%\fancyhf{}
%\renewcommand{\chaptermark}[1]{\markboth{\thechapter.\ #1\ sdf}{}}
%\renewcommand{\sectionmark}[1]{\markright{\MakeUppercase{\thesection.\ #1}}}
%\fancyhead[LE,RO]{\thepage}
%\fancyhead[LO]{\rightmark}
%\fancyhead[RE]]{\leftmark}
\usepackage{extramarks}
\lhead{\firstxmark}
\rfoot{\lastxmark}
\end_preamble
\language english
\inputencoding latin1
\fontscheme
ae
\fontscheme
times
\graphics default
\paperfontsize default
\spacing single
...
...
@@ -21,8 +32,8 @@
\quotes_language swedish
\quotes_times 2
\papercolumns 1
\papersides
1
\paperpagestyle
default
\papersides
2
\paperpagestyle
fancy
\layout Title
...
...
@@ -38,11 +49,37 @@ Lev Walkin <
\layout Standard
\begin_inset ERT
status Open
\layout Standard
\backslash
extramarks{Document version 0.9}{}
\end_inset
\layout Standard
\begin_inset LatexCommand \tableofcontents{}
\end_inset
\layout Standard
\begin_inset ERT
status Collapsed
\layout Standard
\backslash
pagestyle{headings}
\end_inset
\layout Part
ASN.1 Basics
...
...
@@ -159,7 +196,7 @@ UsageExampleModule1
asn1c(5) docs(2) usage(1) 1 }
\layout LyX-Code
AUTOMATIC TAGS DEFINITION
S ::=
DEFINITIONS AUTOMATIC TAG
S ::=
\layout LyX-Code
BEGIN
...
...
@@ -177,7 +214,7 @@ Rectangle ::= SEQUENCE {
height INTEGER, -- Height of the rectangle
\layout LyX-Code
width INTEGER
,
-- Width of the rectangle
width INTEGER
-- Width of the rectangle
\layout LyX-Code
}
...
...
@@ -190,11 +227,19 @@ END
\layout Standard
The module header consists of module name (UsageExampleModule1), the module
object identifier ({...}),
some flags (AUTOMATIC TAGS) an
d
object identifier ({...}),
a keywor
d
\begin_inset Quotes sld
\end_inset
DEFINITIONS ::= BEGIN
DEFINITIONS
\begin_inset Quotes srd
\end_inset
, a set of module flags (AUTOMATIC TAGS) and
\begin_inset Quotes sld
\end_inset
::= BEGIN
\begin_inset Quotes srd
\end_inset
...
...
@@ -232,12 +277,18 @@ The INTEGER type is a signed natural number type without any restrictions
SimpleInteger ::= INTEGER
\layout LyX-Code
\layout LyX-Code
-- An integer with a very limited range
\layout LyX-Code
SmallInt ::= INTEGER (0..127)
\layout LyX-Code
\layout LyX-Code
-- Integer, negative
\layout LyX-Code
...
...
@@ -254,10 +305,13 @@ The ENUMERATED type is semantically equivalent to the INTEGER type with
FruitId ::= ENUMERATED { apple(1), orange(2) }
\layout LyX-Code
\layout LyX-Code
-- The numbers in braces are optional,
\layout LyX-Code
-- the enumeration
may
be performed
-- the enumeration
can
be performed
\layout LyX-Code
-- automatically by the compiler
...
...
@@ -315,12 +369,18 @@ For example, the very first ASN.1 module in this document has the following
ExampleOID ::= OBJECT IDENTIFIER
\layout LyX-Code
\layout LyX-Code
usageExampleModule1-oid ExampleOID
\layout LyX-Code
::= { 1 3 6 1 4 1 9363 1 5 2 1 1 }
\layout LyX-Code
\layout LyX-Code
-- An identifier of the Internet.
\layout LyX-Code
...
...
@@ -348,6 +408,9 @@ The RELATIVE-OID type has the semantics of a subtree of an OBJECT IDENTIFIER.
this-document RELATIVE-OID ::= { docs(2) usage(1) }
\layout LyX-Code
\layout LyX-Code
this-example RELATIVE-OID ::= {
\layout LyX-Code
...
...
@@ -361,7 +424,7 @@ The IA5String type
\layout Standard
This is essentially the ASCII, with 128 character codes available (7 lower
bits of 8-bit byte).
bits of
an
8-bit byte).
\layout Subsection
The UTF8String type
...
...
@@ -584,13 +647,17 @@ The character string with the alphabet which is more or less a subset of
\begin_inset Quotes sld
\end_inset
\series bold
~
\series default
\begin_inset Quotes srd
\end_inset
(tilde).
Alternatively, the alphabet may be
represent
ed as the PrintableString alphabet
describ
ed earlier, plus the following characters:
Alternatively, the alphabet may be
describ
ed as the PrintableString alphabet
present
ed earlier, plus the following characters:
\begin_inset Quotes sld
\end_inset
...
...
@@ -828,7 +895,11 @@ _
\begin_inset Quotes sld
\end_inset
\series bold
~
\series default
\begin_inset Quotes srd
\end_inset
...
...
@@ -954,12 +1025,18 @@ This one is the list (array) of simple or constructed types:
ManyIntegers ::= SEQUENCE OF INTEGER
\layout LyX-Code
\layout LyX-Code
-- Example 2
\layout LyX-Code
ManyRectangles ::= SEQUENCE OF Rectangle
\layout LyX-Code
\layout LyX-Code
-- More complex example:
\layout LyX-Code
...
...
@@ -990,6 +1067,9 @@ The SET OF type models the bag of structures.
SetOfApples :: SET OF Apple
\layout LyX-Code
\layout LyX-Code
-- Set of integers encoding the kind of a fruit
\layout LyX-Code
...
...
@@ -1018,7 +1098,7 @@ supported
\begin_inset Quotes srd
\end_inset
too, as long as an
object-orient
ed approach is not a definitive factor.
too, as long as an
class-bas
ed approach is not a definitive factor.
\end_inset
).
...
...
@@ -1043,7 +1123,13 @@ collapsed false
\emph on
int
\emph default
types instead of generic INTEGER_t.
types instead of infinite width INTEGER_t structures.
See Table
\begin_inset LatexCommand \vref{cap:asn1c-cmdopts}
\end_inset
.
\end_inset
:
...
...
@@ -1063,9 +1149,9 @@ typedef struct Rectangle_s {
This would not be of much value for such a simple specification, so the
compiler goes further and actually produces the code which fills in this
structure by parsing the binary
structure by parsing the
opaque
binary
\begin_inset Foot
collapsed
fals
e
collapsed
tru
e
\layout Standard
...
...
@@ -1076,13 +1162,37 @@ BER, CER and DER encodings are binary.
data provided in some buffer.
It also produces the code that takes this structure as an argument and
performs structure serialization by emitting a series of bytes.
\layout
Section
\layout
Chapter
Quick start
\layout Standard
After building and installing the compiler, the asn1c command may be used
to compile the ASN.1 specification
After building and installing the compiler, the
\emph on
asn1c
\begin_inset Foot
collapsed false
\layout Standard
The 1 symbol in asn
\series bold
1
\series default
c is a digit, not an
\begin_inset Quotes sld
\end_inset
ell
\begin_inset Quotes srd
\end_inset
letter.
\end_inset
\emph default
command may be used to compile the ASN.1 specification
\begin_inset Foot
collapsed false
...
...
@@ -1093,7 +1203,15 @@ This is probably
not
\series default
what you want to try out right now -- read through the rest of this chapter
to find out about -P option.
to find out about
\series bold
-P
\series default
and
\series bold
-R
\series default
options.
\end_inset
:
...
...
@@ -1104,8 +1222,8 @@ asn1c
<spec.asn1>
\layout Standard
If several specifications contain interdependencies, all of the
m must be
specified
:
If several specifications contain interdependencies, all of the
files must
be specified altogether
:
\layout LyX-Code
asn1c
...
...
@@ -1113,27 +1231,536 @@ asn1c
<spec1.asn1> <spec2.asn1> ...
\layout Standard
The compiler -E and -EF options are used for testing the parser and the
semantic fixer, respectively.
These options will instruct the compiler to dump out the parsed (and fixed)
ASN.1 specification as it was "understood" by the compiler.
It might might be useful to check whether a particular syntactic construction
The compiler
\series bold
-E
\series default
and
\series bold
-EF
\series default
options are used for testing the parser and the semantic fixer, respectively.
These options will instruct the compiler to dump out the parsed (and fixed,
if
\series bold
-F
\series default
is involved) ASN.1 specification as it was "understood" by the compiler.
It might be useful to check whether a particular syntactic construction
is properly supported by the compiler.
\layout LyX-Code
asn1c -EF
asn1c
\series bold
-EF
\series default
\emph on
<spec-to-test.asn1>
\layout Standard
The -P option is used to dump the compiled output on the screen instead
of creating a bunch of .c and .h files on disk in the current directory.
You would probably want to start with -P option instead of creating a mess
in your current directory.
The
\series bold
-P
\series default
option is used to dump the compiled output on the screen instead of creating
a bunch of .c and .h files on disk in the current directory.
You would probably want to start with
\series bold
-P
\series default
option instead of creating a mess in your current directory.
Another option,
\series bold
-R
\series default
, asks compiler to only generate the files which need to be generated, and
supress linking in the numerous support files.
\layout Standard
Print the compiled output instead of creating multiple source files:
\layout LyX-Code
asn1c
\series bold
-P
\series default
\emph on
<spec-to-compile-and-print.asn1>
\layout LyX-Code
\layout Chapter
Using the ASN.1 Compiler
\layout Section
Slow start
\layout Subsection
Command-line options
\layout Standard
The Table
\begin_inset LatexCommand \vref{cap:asn1c-cmdopts}
\end_inset
summarizes various options affecting the compiler's behavior.
\layout Standard
\begin_inset Float table
wide false
collapsed true
\layout Standard
\begin_inset Tabular
<lyxtabular version="3" rows="20" columns="2">
<features>
<column alignment="left" valignment="top" leftline="true" width="0">
<column alignment="block" valignment="top" leftline="true" rightline="true" width="3in">
<row topline="true" bottomline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text
\layout Standard
\series bold
Overall Options
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text
\layout Standard
\series bold
Description
\end_inset
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text
\layout Standard
-E
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text
\layout Standard
\size small
Stop after the parsing stage and print the reconstructed ASN.1 specification
code to the standard output.
\end_inset
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text
\layout Standard
-F
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text
\layout Standard
\size small
Used together with -E, instructs the compiler to stop after the ASN.1 syntax
tree fixing stage and dump the reconstructed ASN.1 specification to the
standard output.
\end_inset
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text
\layout Standard
-P
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text
\layout Standard
\size small
Dump the compiled output to the standard output instead of cre- ating the
target language files on disk.
\end_inset
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text
\layout Standard
-R
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text
\layout Standard
\size small
Restrict the compiler to generate only the ASN.1 tables, omit- ting the usual
support code.
\end_inset
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text
\layout Standard
-S
\emph on
<directory>
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text
\layout Standard
\size small
Use the specified directory with ASN.1 skeleton files.
\end_inset
</cell>
</row>
<row topline="true" bottomline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text
\layout Standard
-t
\emph on
<data-string>
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text
\layout Standard
\size small
Interpret the data-string as a sequence of hexadecimal values representing
the start of BER TLV encoding.
Print the human readable explanation.
\end_inset
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text
\layout Standard
\series bold
Warning Options
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text
\layout Standard
\series bold
Description
\end_inset
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text
\layout Standard
-Werror
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text
\layout Standard
\size small
Treat warnings as errors; abort if any warning is produced.
\end_inset
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text
\layout Standard
-Wdebug-lexer
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text
\layout Standard
\size small
Enable lexer debugging during the ASN.1 parsing stage.
\end_inset
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text
\layout Standard
-Wdebug-fixer
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text
\layout Standard
\size small
Enable ASN.1 syntax tree fixer debugging during the fixing stage.
\end_inset
</cell>
</row>
<row topline="true" bottomline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text
\layout Standard
-Wdebug-compiler
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text
\layout Standard
\size small
Enable debugging during the actual compile time.
\end_inset
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text
\layout Standard
\series bold
Language Options
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text
\layout Standard
\series bold
Description
\end_inset
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text
\layout Standard
-fbless-SIZE
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text
\layout Standard
\size small
Allow SIZE() constraint for INTEGER, ENUMERATED, and other types for which
this constraint is normally prohibited by the standard.
This is a violation of an ASN.1 standard and compiler may fail to produce
the meaningful code.
\end_inset
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text
\layout Standard
-fnative-integers
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text
\layout Standard
\size small
Use native machine's integer types whenever possible, instead of the complex
ASN.1 INTEGER and ENUMERATED types.
\end_inset
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text
\layout Standard
-funnamed-unions
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text
\layout Standard
\size small
Enable unnamed unions in the definitions of target language's structures.
\end_inset
</cell>
</row>
<row topline="true" bottomline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text
\layout Standard
-ftypes88
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text
\layout Standard
\size small
Use only ASN.1:1988 embedded types.
\end_inset
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text
\layout Standard
\series bold
Output Options
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text
\layout Standard
\series bold
Description
\end_inset
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text
\layout Standard
-print-constraints
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text
\layout Standard
\size small
When -EF are also specified, this option forces the compiler to explain
its internal understanding of subtype constraints.
\end_inset
</cell>
</row>
<row topline="true" bottomline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text
\layout Standard
-print-lines
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text
\layout Standard
\size small
Generate "-- #line" comments in -E output.
\end_inset
</cell>
</row>
</lyxtabular>
\end_inset
\layout Caption
\begin_inset LatexCommand \label{cap:asn1c-cmdopts}
\end_inset
The list of asn1c command line options
\end_inset
\layout Section
Recognizing compiler output
\layout Standard
...
...
@@ -1157,17 +1784,8 @@ Rectangle.h
A set of helper .c and .h files which contain generic encoders, decoders and
other useful routines.
There will be many of them, some of them even not necessary
\begin_inset Foot
collapsed false
\layout Standard
Soon the compiler will be modified to emit the smallest subset of necessary
files.
\end_inset
, but the overall amount of code after compiling will be rather small anyway.
There will be quite a few of them, some of them even are not always necessary,
but the overall amount of code after compiling will be rather small anyway.
\layout Standard
It is your responsibility to create .c file with the
...
...
@@ -1233,14 +1851,14 @@ int main()
\end_inset
\layout S
ubs
ection
\layout Section
Invoking the ASN.1 helper code from the application
\layout Standard
First of all, you
would want to include one or more header files into your
applicati
on.
For
the
Rectangle module, including the Rectangle.h file is enough:
First of all, you
should to include one or more header files into your applicati
on.
For
our
Rectangle module, including the Rectangle.h file is enough:
\layout LyX-Code
#include <Rectangle.h>
...
...
@@ -1252,7 +1870,10 @@ The header files defines the C structure corresponding to the ASN.1 definition
For example, here is the code which frees the Rectangle_t structure:
\layout LyX-Code
Rectangle_t *rect = ;
Rectangle_t *rect = ...;
\layout LyX-Code
\layout LyX-Code
asn1_DEF_Rectangle->free_struct(&asn1_DEF_Rectangle,
...
...
@@ -1366,7 +1987,7 @@ Here is how the buffer can be deserialized into the structure:
Rectangle_t *
\layout LyX-Code
simple_deserializer(void *buffer, size_t buf_size) {
simple_deserializer(
const
void *buffer, size_t buf_size) {
\layout LyX-Code
Rectangle_t *rect = 0; /* Note this 0! */
...
...
@@ -1409,6 +2030,9 @@ simple_deserializer(void *buffer, size_t buf_size) {
} else {
\layout LyX-Code
/* Free partially decoded rect */
\layout LyX-Code
asn1_DEF_Rectangle->free_struct(
\layout LyX-Code
...
...
@@ -1461,7 +2085,7 @@ Restartable decoding is a little bit trickier: you need to provide the old
\end_inset
\layout Subs
ubs
ection
\layout Subsection
\begin_inset LatexCommand \label{sub:Decoding-BER}
...
...
@@ -1575,7 +2199,7 @@ always
Please look into ber_decoder.h for the precise definition of ber_decode()
and related types.
\layout Subs
ubs
ection
\layout Subsection
\begin_inset LatexCommand \label{sub:Encoding-DER}
...
...
@@ -1610,7 +2234,10 @@ As with BER decoder, the DER encoder may be invoked either directly from
*/
\layout LyX-Code
int _write_stream(void *buffer, size_t size, void *app_key) {
static int
\layout LyX-Code
write_stream(const void *buffer, size_t size, void *app_key) {
\layout LyX-Code
FILE *ostream = app_key;
...
...
@@ -1667,7 +2294,7 @@ simple_serializer(FILE *ostream, Rectangle_t *rect) {
rval = der_encode(&asn1_DEF_Rect, rect,
\layout LyX-Code
_
write_stream, ostream);
write_stream, ostream);
\layout LyX-Code
if(rval
...
...
@@ -1760,7 +2387,7 @@ It is actually faster too: the encoder might skip over some computations
Please look into der_encoder.h for the precise definition of der_encode()
and related types.
\layout Subs
ubs
ection
\layout Subsection
\begin_inset LatexCommand \label{sub:Validating-the-target}
...
...
@@ -1791,7 +2418,7 @@ The asn_check_constraints() function checks the type for various implicit
Please look into constraints.h for the precise definition of asn_check_constraint
s() and related types.
\layout Subs
ubs
ection
\layout Subsection
\begin_inset LatexCommand \label{sub:Printing-the-target}
...
...
@@ -1811,7 +2438,7 @@ asn_fprint(stdout, &asn1_DEF_Rectangle, rect);
Please look into constr_TYPE.h for the precise definition of asn_fprint()
and related types.
\layout Subs
ubs
ection
\layout Subsection
\begin_inset LatexCommand \label{sub:Freeing-the-target}
...
...
@@ -1937,6 +2564,16 @@ free_struct
\emph default
function with the target structure pointer set to 0 (NULL), the function
will do nothing.
\layout Bibliography
\bibitem [ASN1C]{ASN1C}
Free ASN.1 Compiler.
\begin_inset LatexCommand \htmlurl{http://lionet.info/asn1/}
\end_inset
\layout Bibliography
\bibitem [Dub00]{Dub00}
...
...
doc/asn1c-usage.pdf
View file @
26587ab2
No preview for this file type
Write
Preview
Markdown
is supported
0%
Try again
or
attach a new file
Attach a file
Cancel
You are about to add
0
people
to the discussion. Proceed with caution.
Finish editing this message first!
Cancel
Please
register
or
sign in
to comment