diff options
Diffstat (limited to 'doc/libtasn1.texi')
| -rw-r--r-- | doc/libtasn1.texi | 402 |
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 |