path: root/doc/libtasn1.texi

\input texinfo   @c -*-texinfo-*-
@comment %**start of header
@setfilename libtasn1.info
@include version.texi
@settitle GNU Libtasn1 @value{VERSION}

@c Unify some of the indices.
@syncodeindex tp fn
@syncodeindex pg fn

@comment %**end of header
@copying
This manual is for GNU 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{} 2001-2012 Free Software Foundation, Inc.

@quotation
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 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 section entitled ``GNU Free
Documentation License''.
@end quotation
@end copying

@dircategory Software 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 for version @value{VERSION}, @value{UPDATED}
@author Fabio Fiorina
@author Simon Josefsson (@email{help-libtasn1@@gnu.org})
@page
@vskip 0pt plus 1filll
@insertcopying
@end titlepage

@contents

@ifnottex
@node Top
@top Libtasn1

@insertcopying
@end ifnottex

@menu
* Introduction::
* ASN.1 structure handling::
* Utilities::
* Function reference::
* Copying Information::

Indices

* Concept Index::               Index of concepts and programs.
* Function and Data Index::     Index of functions, variables and data types.
@end menu

@node Introduction
@chapter Introduction

This document describes the Libtasn1 library developed for ASN.1
(Abstract Syntax Notation One) structures management and DER
(Distinguished Encoding Rules) encoding functions.

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 version 2.1 or later.  The
command line tools, self-tests and build infrastructure are licensed
under the GNU General Public License version 3.0 or later.

@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

@node ASN.1 structure handling
@chapter ASN.1 structure handling

@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 asn_node_t

The main type used in it is @code{asn_node_t}, and it's used to store
the ASN.1 definitions and structures (instances).

The constant @code{NULL} can be used for the variable
initialization.  For example:

@example
 asn_node_t definitions=NULL;
@end example

Some functions require a parameter named errorDescription of char*
type.  The array must be already allocated and must have at least
@code{ASN1_MAX_ERROR_DESCRIPTION_SIZE} bytes (E.g, as in @code{char
Description[ASN1_MAX_ERROR_DESCRIPTION_SIZE];}).

@code{ASN1_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 libtasn1 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

For example, consider a ASN.1 definitions file as follows:

@verbatim
PKIX1 { }

DEFINITIONS IMPLICIT TAGS ::=

BEGIN

Dss-Sig-Value ::= SEQUENCE {
     r       INTEGER,
     s       INTEGER
}

END
@end verbatim

And a assignments file as follows:

@verbatim
dp PKIX1.Dss-Sig-Value

r 42
s 47
@end verbatim

Running the command below will generate a file @file{assign.out}
containing the DER encoding of @code{PKIX1.Dss-Sig-Value}.

@verbatim
$ asn1Coding pkix.asn assign.asn1
@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.
 -o file : output file.
@end verbatim

For example, after generating the file @file{assign.out} from the
example section of the @code{asn1Coding} command, the following
invocation will decode the DER data.

@verbatim
$ asn1Decoding pkix.asn assign.out PKIX1.Dss-Sig-Value
@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
@include texi/version.c.texi

@node Copying Information
@appendix Copying Information

@menu
* GNU Free Documentation License::   License for copying this manual.
@end menu

@node GNU Free Documentation License
@appendixsec GNU Free Documentation License

@cindex FDL, GNU Free Documentation License

@include fdl-1.3.texi

@node Concept Index
@unnumbered Concept Index

@printindex cp

@node Function and Data Index
@unnumbered Function and Data Index

@printindex fn

@bye