Add, rewritten from asn1.tex.

1 files changed, 402 insertions, 0 deletions

diff --git a/doc/libtasn1.texi b/doc/libtasn1.texi
new file mode 100644
index 0000000..44c4bd9
--- /dev/null
+++ b/doc/libtasn1.texi
@@ -0,0 +1,402 @@
+\input texinfo   @c -*-texinfo-*-
+@comment $Id$
+@comment %**start of header
+@setfilename libtasn1.info
+@include version.texi
+@settitle Libtasn1 @value{VERSION}
+
+@c Unify some of the indices.
+@syncodeindex tp fn
+@syncodeindex pg fn
+
+@comment %**end of header
+@copying
+This manual is for Libtasn1
+(version @value{VERSION}, @value{UPDATED}),
+which is a library for Abstract Syntax Notation One (ASN.1) and
+Distinguish Encoding Rules (DER) manipulation.
+
+Copyright @copyright{} 2004  Simon Josefsson
+
+Copyright @copyright{} 2001, 2002, 2003  Fabio Fiorina
+
+@quotation
+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, with the Front-Cover Texts being ``A GNU Manual,''
+and with the Back-Cover Texts as in (a) below.  A copy of the
+license is included in the section entitled ``GNU Free Documentation
+License.''
+
+(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
+this GNU Manual, like GNU software.  Copies published by the Free
+Software Foundation raise funds for GNU development.''
+@end quotation
+@end copying
+
+@dircategory GNU Libraries
+@direntry
+* libtasn1: (libtasn1). Library for Abstract Syntax Notation One (ASN.1).
+@end direntry
+
+@titlepage
+@title Libtasn1
+@subtitle Abstract Syntax Notation One (ASN.1) library for the GNU system
+@subtitle part of the GnuTLS project
+@subtitle for version @value{VERSION}, @value{UPDATED}
+@author Fabio Fiorina (@email{bug-gnutls@@gnu.org})
+@page
+@vskip 0pt plus 1filll
+@insertcopying
+@end titlepage
+
+@contents
+
+@ifnottex
+@node Top
+@top Libtasn1
+
+@insertcopying
+@end ifnottex
+
+@menu
+* ASN.1 structure handling::
+* Utilities::
+* Function reference::
+* Copying This Manual::
+
+Indices
+
+* Concept Index::               Index of concepts and programs.
+* Function and Data Index::     Index of functions, variables and data types.
+@end menu
+
+
+@node ASN.1 structure handling
+@chapter ASN.1 structure handling
+
+This document describes the Libtasn1 library developed for ASN.1
+(Abstract Syntax Notation One) structures management.
+
+The main features of this library are:
+
+@itemize @bullet
+
+@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.
+
+@item It's Free Software.
+Anybody can use, modify, and redistribute the library under the terms
+of the GNU Lesser General Public License.
+
+@item It's thread-safe.
+@cindex threads
+No global variables are used and multiple library handles and session
+handles may be used in parallel.
+
+@item It's portable.
+@cindex Porting
+It should work on all Unix like operating systems, including Windows.
+The library itself should be portable to any C89 system, not even
+POSIX is required.
+@end itemize
+
+@menu
+* ASN.1 syntax::
+* Naming::
+* Library Notes::
+* Future developments::
+@end menu
+
+@node ASN.1 syntax
+@section ASN.1 syntax
+
+@cindex ASN.1 schema
+
+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:
+
+@verbatim
+      definitions_name {<object definition>}
+
+      DEFINITIONS <EXPLICIT or IMPLICIT> TAGS ::=
+
+      BEGIN 
+
+      <type and constants definitions>
+
+      END
+@end verbatim
+
+The token "::=" must be separate from others elements, so this is a
+wrong declaration:
+
+@example
+      ;; INCORRECT
+      Version ::=INTEGER
+@end example
+
+the correct form is:
+
+@example
+   Version ::= INTEGER
+@end example
+
+Here is the list of types that the parser can manage:
+
+@cindex Supported ASN.1 types, list of
+
+@itemize @bullet
+
+@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.
+
+@node Naming
+@section Naming
+
+Consider this definition:
+
+@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".  These strings are used in functions that are
+described below.
+
+Others examples:
+
+Field 'id' in 'Group' type : "Example.Group.id".
+
+Field 'value1' in field 'value' in type 'Group':
+"Example.Group.value.value1".
+
+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 @code{SET_OF} or
+@code{SEQUENCE_OF}.
+
+@node Library Notes
+@section Library Notes
+
+@cindex Header file libtasn1.h
+
+The header file of this library is @file{libtasn1.h}.
+
+@cindex Main type ASN1_TYPE
+
+The main type used in it is @code{ASN1_TYPE}, and it's used to store
+the @acronym{ASN.1} definitions and structures (instances).
+
+The constant @acronym{ASN1_TYPE_EMPTY} can be used for the variable
+initialization.  For example:
+
+@example
+ ASN1_TYPE definitions=ASN1_TYPE_EMPTY;
+@end example
+
+Some functions require a parameter named errorDescription of char*
+type.  The array must be already allocated and must have at least
+@code{MAX_ERROR_DESCRIPTION_SIZE} bytes (E.g, as in @code{char
+Description[MAX_ERROR_DESCRIPTION_SIZE];}).
+
+@code{MAX_NAME_SIZE} indicates the maximum number of characters of a
+name inside a file with ASN1 definitions.
+
+@node Future developments
+@section Future developments
+@cindex Future developments
+
+@itemize @bullet
+
+@item Add functions for a C code file generation containing equivalent 
+data structures (not a single array like now).
+
+@item Type REAL.
+
+@end itemize
+
+@node Utilities
+@chapter Utilities
+
+@menu
+* Invoking asn1Parser::
+* Invoking asn1Coding::
+* Invoking asn1Decoding::
+@end menu
+
+@node Invoking asn1Parser
+@section Invoking asn1Parser
+@cindex asn1Parser program
+
+@file{asn1Parser} reads one file with ASN1 definitions and generates a
+file with an array to use with libasn1 functions.
+
+@verbatim
+Usage:  asn1Parser [options] file
+
+Options:
+ -h : shows the help message.
+ -v : shows version information and exit.
+ -c : checks the syntax only.
+ -o file : output file.
+ -n name : array name.
+@end verbatim
+
+@node Invoking asn1Coding
+@section Invoking asn1Coding
+@cindex asn1Coding program
+
+@file{asn1Coding} generates a DER encoding from a file with ASN1
+definitions and another one with assignments.
+
+The file with assignments must have this syntax:
+
+@verbatim
+InstanceName  Asn1Definition
+
+nameString  value
+
+nameString  value
+...
+@end verbatim
+
+The output file is a binary file with the DER encoding.
+
+@verbatim
+Usage:  asn1Coding [options] file1 file2
+ file1 : file with ASN1 definitions.
+ file2 : file with assignments.
+Options:
+ -h : shows the help message.
+ -v : shows version information and exit.
+ -c : checks the syntax only.
+ -o file : output file.
+@end verbatim
+
+@node Invoking asn1Decoding
+@section Invoking asn1Decoding
+@cindex asn1Decoding program
+
+@file{asn1Decoding} generates an ASN1 structure from a file with ASN1
+definitions and a binary file with a DER encoding.
+
+@verbatim
+Usage:  asn1Decoding [options] file1 file2 type
+ file1 : file with ASN1 definitions.
+ file2 : binary file with a DER encoding.
+ type : ASN1 definition name.
+Options:
+ -h : shows the help message.
+ -v : shows version information and exit.
+ -c : checks the syntax only.
+ -o file : output file.
+@end verbatim
+
+@node Function reference
+@chapter Function reference
+
+@menu
+* ASN.1 schema functions::
+* ASN.1 field functions::
+* DER functions::
+* Error handling functions::
+* Auxilliary functions::
+@end menu
+
+@node ASN.1 schema functions
+@section ASN.1 schema functions
+
+@include texi/ASN1.c.texi
+
+@node ASN.1 field functions
+@section ASN.1 field functions
+
+@include texi/structure.c.texi
+@include texi/element.c.texi
+
+@node DER functions
+@section DER functions
+
+@include texi/coding.c.texi
+@include texi/decoding.c.texi
+
+@node Error handling functions
+@section Error handling functions
+
+@include texi/errors.c.texi
+
+@node Auxilliary functions
+@section Auxilliary functions
+
+@include texi/parser_aux.c.texi
+
+@node Copying This Manual
+@appendix Copying This Manual
+
+@menu
+* GNU Free Documentation License::  License for copying this manual.
+@end menu
+
+@include fdl.texi
+
+
+@node Concept Index
+@unnumbered Concept Index
+
+@printindex cp
+
+@node Function and Data Index
+@unnumbered Function and Data Index
+
+@printindex fn
+
+@bye