\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}








