1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
|
\documentclass{book}
\usepackage{fancyheadings}
\newcommand{\HRule}{\rule{\linewidth}{0.4mm}}
\begin{document}
{\Large{ASN.1 structures parser}}
\vspace{-.3cm}
\\
\HRule
\vspace{-.6cm}
\\
\begin{flushright}
This is part of the GnuTLS project\\
\end{flushright}
\vspace*{\stretch{2}}
\begin{center}
\par
Copyright \copyright\ 2001, 2002, 2003 Fabio Fiorina\\
\setlength{\parskip}{4mm}
\par
Permission is granted to copy, distribute and/or modify this
document under the terms of the GNU Free Documentation License,
Version 1.1 or any later version published by the Free Software
Foundation; with no Invariant Sections, no Front-Cover Texts and
no Back-Cover Texts. A copy of the license is included in the
chapter entitled "GNU Free Documentation License".
\end{center}
\setlength{\parindent}{2mm}
\setlength{\parskip}{1mm}
\tableofcontents
\chapter{ASN.1 structures handling}
\section{Introduction}
This document describes the version 0.2.4 of library 'libtasn1' developed
for ASN1 (Abstract Syntax Notation One) structures management.
The main features of this library are:
\begin{itemize}
\item on line ASN1 structure management that doesn't require any
C code file generation.
\item off line ASN1 structure management with C code file generation
containing an array.
\item DER (Distinguish Encoding Rules) encoding
\item no limits for INTEGER and ENUMERATED values
\end{itemize}
\section{ASN.1 syntax}
The parser is case sensitive. The comments begin with "-- " and end at the end of lines.
An example is in "pkix.asn" file.
ASN.1 definitions must have this syntax:
\begin{verbatim}
definitions_name {<object definition>}
DEFINITIONS <EXPLICIT or IMPLICIT> TAGS ::=
BEGIN
<type and constants definitions>
END
\end{verbatim}
\par
The token "::=" must be separate from others elements, so this is a wrong declaration:
Version ::=INTEGER
the correct one is : Version ::= INTEGER
Here is the list of types that the parser can manage:
\begin{itemize}
\item INTEGER
\item ENUMERATED
\item BOOLEAN
\item OBJECT IDENTIFIER
\item NULL
\item BIT STRING
\item OCTET STRING
\item UTCTime
\item GeneralizedTime
\item GeneralString
\item SEQUENCE
\item SEQUENCE OF
\item SET
\item SET OF
\item CHOICE
\item ANY
\item ANY DEFINED BY
\end{itemize}
This version doesn't manage REAL type. It doesn't allow the
"EXPORT" and "IMPORT" sections too.
The SIZE constraints are allowed, but no check is done on them.
\section{Naming}
With this definitions:
\begin{verbatim}
Example { 1 2 3 4 }
DEFINITIONS EXPLICIT TAGS ::=
BEGIN
Group ::= SEQUENCE {
id OBJECT IDENTIFIER,
value Value
}
Value ::= SEQUENCE {
value1 INTEGER,
value2 BOOLEAN
}
END
\end{verbatim}
to identify the type 'Group' you have to use the null terminated string "Example.Group".
Others examples:
Field 'id' in 'Group' type : "Example.Group.id"
Field 'value1' in field 'value' in type 'Group': "Example.Group.value.value1"
These strings are used in functions that are described below.
Elements of structured types that don't have a name, receive the name "?1","?2", and so on.
The name "?LAST" indicates the last element of a SET\_OF or SEQUENCE\_OF.
\section{Library Notes}
The header file of this library is libtasn1.h .
The main type used in it is ASN1\_TYPE, and it's used to
store the ASN1 definitions and structures (instances).
The constant ASN1\_TYPE\_EMPTY can be used for the variable initialization.
\par
Example: ASN1\_TYPE definitions=ASN1\_TYPE\_EMPTY;
\par
Some functions require a parameter named errorDescription of char* type.
The array must be already allocated and must have at least
MAX\_ERROR\_DESCRIPTION\_SIZE bytes
(E.g: char Description[MAX\_ERROR\_DESCRIPTION\_SIZE];).
\par
MAX\_NAME\_SIZE indicates the maximum number of characters of a name inside
a file with ASN1 definitions.
\section{Future developments}
\begin{enumerate}
\item add functions for a C code file generation containing equivalent
data structures (not a single array like now).
\item type REAL
\end{enumerate}
\chapter{Utilities}
\section{asn1Parser}
asn1Parser reads one file with ASN1 definitions and generates a file
with an array to use with libasn1 functions.
\par
Usage: asn1Parser [options] file
\par
Options:
\begin{itemize}
\item -h : shows the help message.
\item -v : shows version information and exit.
\item -c : checks the syntax only.
\item -o file : output file.
\item -n name : array name.
\end{itemize}
\section{asn1Coding}
asn1Coding generates a DER encoding from a file with ASN1 definitions
and another one with assignments.
The file with assignments must have this syntax:
\par
InstanceName Asn1Definition
\par
nameString value
\par
nameString value
\par
...
\par
The output file is a binary file with the DER encoding.
\par
Usage: asn1Coding [options] file1 file2
\begin{itemize}
\item file1 : file with ASN1 definitions.
\item file2 : file with assignments.
\end{itemize}
\par
Options:
\begin{itemize}
\item -h : shows the help message.
\item -v : shows version information and exit.
\item -c : checks the syntax only.
\item -o file : output file.
\end{itemize}
\section{asn1Decoding}
asn1Decoding generates an ASN1 structure from a file with ASN1 definitions
and a binary file with a DER encoding.
\par
Usage: asn1Decoding [options] file1 file2 type
\begin{itemize}
\item file1 : file with ASN1 definitions.
\item file2 : binary file with a DER encoding.
\item type : ASN1 definition name.
\end{itemize}
\par
Options:
\begin{itemize}
\item -h : shows the help message.
\item -v : shows version information and exit.
\item -c : checks the syntax only.
\item -o file : output file.
\end{itemize}
\chapter{Function reference}
\input{asn1-api}
\input{fdl.tex}
\end{document}
|
