asn1/doc/asn1.tex

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