doc/libtasn1.texi

   1 \input texinfo   @c -*-texinfo-*-
   2 @comment $Id$
   3 @comment %**start of header
   4 @setfilename libtasn1.info
   5 @include version.texi
   6 @settitle Libtasn1 @value{VERSION}
   7
   8 @c Unify some of the indices.
   9 @syncodeindex tp fn
  10 @syncodeindex pg fn
  11
  12 @comment %**end of header
  13 @copying
  14 This manual is for Libtasn1
  15 (version @value{VERSION}, @value{UPDATED}),
  16 which is a library for Abstract Syntax Notation One (ASN.1) and
  17 Distinguish Encoding Rules (DER) manipulation.
  18
  19 Copyright @copyright{} 2004  Simon Josefsson
  20
  21 Copyright @copyright{} 2001, 2002, 2003  Fabio Fiorina
  22
  23 @quotation
  24 Permission is granted to copy, distribute and/or modify this document
  25 under the terms of the GNU Free Documentation License, Version 1.1 or
  26 any later version published by the Free Software Foundation; with no
  27 Invariant Sections, with the Front-Cover Texts being ``A GNU Manual,''
  28 and with the Back-Cover Texts as in (a) below.  A copy of the
  29 license is included in the section entitled ``GNU Free Documentation
  30 License.''
  31
  32 (a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
  33 this GNU Manual, like GNU software.  Copies published by the Free
  34 Software Foundation raise funds for GNU development.''
  35 @end quotation
  36 @end copying
  37
  38 @dircategory GNU Libraries
  39 @direntry
  40 * libtasn1: (libtasn1). Library for Abstract Syntax Notation One (ASN.1).
  41 @end direntry
  42
  43 @titlepage
  44 @title Libtasn1
  45 @subtitle Abstract Syntax Notation One (ASN.1) library for the GNU system
  46 @subtitle part of the GnuTLS project
  47 @subtitle for version @value{VERSION}, @value{UPDATED}
  48 @author Fabio Fiorina (@email{bug-gnutls@@gnu.org})
  49 @page
  50 @vskip 0pt plus 1filll
  51 @insertcopying
  52 @end titlepage
  53
  54 @contents
  55
  56 @ifnottex
  57 @node Top
  58 @top Libtasn1
  59
  60 @insertcopying
  61 @end ifnottex
  62
  63 @menu
  64 * ASN.1 structure handling::
  65 * Utilities::
  66 * Function reference::
  67 * Copying This Manual::
  68
  69 Indices
  70
  71 * Concept Index::               Index of concepts and programs.
  72 * Function and Data Index::     Index of functions, variables and data types.
  73 @end menu
  74
  75
  76 @node ASN.1 structure handling
  77 @chapter ASN.1 structure handling
  78
  79 This document describes the Libtasn1 library developed for ASN.1
  80 (Abstract Syntax Notation One) structures management.
  81
  82 The main features of this library are:
  83
  84 @itemize @bullet
  85
  86 @item On line ASN1 structure management that doesn't require any
  87 C code file generation.
  88
  89 @item Off line ASN1 structure management with C code file generation
  90 containing an array.
  91
  92 @item DER (Distinguish Encoding Rules) encoding.
  93
  94 @item No limits for INTEGER and ENUMERATED values.
  95
  96 @item It's Free Software.
  97 Anybody can use, modify, and redistribute the library under the terms
  98 of the GNU Lesser General Public License.
  99
 100 @item It's thread-safe.
 101 @cindex threads
 102 No global variables are used and multiple library handles and session
 103 handles may be used in parallel.
 104
 105 @item It's portable.
 106 @cindex Porting
 107 It should work on all Unix like operating systems, including Windows.
 108 The library itself should be portable to any C89 system, not even
 109 POSIX is required.
 110 @end itemize
 111
 112 @menu
 113 * ASN.1 syntax::
 114 * Naming::
 115 * Library Notes::
 116 * Future developments::
 117 @end menu
 118
 119 @node ASN.1 syntax
 120 @section ASN.1 syntax
 121
 122 @cindex ASN.1 schema
 123
 124 The parser is case sensitive. The comments begin with "-- " and end at
 125 the end of lines.  An example is in "pkix.asn" file.  ASN.1
 126 definitions must have this syntax:
 127
 128 @verbatim
 129       definitions_name {<object definition>}
 130
 131       DEFINITIONS <EXPLICIT or IMPLICIT> TAGS ::=
 132
 133       BEGIN
 134
 135       <type and constants definitions>
 136
 137       END
 138 @end verbatim
 139
 140 The token "::=" must be separate from others elements, so this is a
 141 wrong declaration:
 142
 143 @example
 144       ;; INCORRECT
 145       Version ::=INTEGER
 146 @end example
 147
 148 the correct form is:
 149
 150 @example
 151    Version ::= INTEGER
 152 @end example
 153
 154 Here is the list of types that the parser can manage:
 155
 156 @cindex Supported ASN.1 types, list of
 157
 158 @itemize @bullet
 159
 160 @item INTEGER
 161 @item ENUMERATED
 162 @item BOOLEAN
 163 @item OBJECT IDENTIFIER
 164 @item NULL
 165 @item BIT STRING
 166 @item OCTET STRING
 167 @item UTCTime
 168 @item GeneralizedTime
 169 @item GeneralString
 170 @item SEQUENCE
 171 @item SEQUENCE OF
 172 @item SET
 173 @item SET OF
 174 @item CHOICE
 175 @item ANY
 176 @item ANY DEFINED BY
 177
 178 @end itemize
 179
 180 This version doesn't manage REAL type. It doesn't allow the "EXPORT"
 181 and "IMPORT" sections too.
 182
 183 The SIZE constraints are allowed, but no check is done on them.
 184
 185 @node Naming
 186 @section Naming
 187
 188 Consider this definition:
 189
 190 @verbatim
 191       Example { 1 2 3 4 }
 192
 193       DEFINITIONS EXPLICIT TAGS ::=
 194
 195       BEGIN
 196
 197       Group ::= SEQUENCE {
 198          id   OBJECT IDENTIFIER,
 199          value  Value
 200       }
 201
 202       Value ::= SEQUENCE {
 203          value1  INTEGER,
 204          value2  BOOLEAN
 205       }
 206
 207       END
 208 @end verbatim
 209
 210 To identify the type 'Group' you have to use the null terminated
 211 string "Example.Group".  These strings are used in functions that are
 212 described below.
 213
 214 Others examples:
 215
 216 Field 'id' in 'Group' type : "Example.Group.id".
 217
 218 Field 'value1' in field 'value' in type 'Group':
 219 "Example.Group.value.value1".
 220
 221 Elements of structured types that don't have a name, receive the name
 222 "?1","?2", and so on.
 223
 224 The name "?LAST" indicates the last element of a @code{SET_OF} or
 225 @code{SEQUENCE_OF}.
 226
 227 @node Library Notes
 228 @section Library Notes
 229
 230 @cindex Header file libtasn1.h
 231
 232 The header file of this library is @file{libtasn1.h}.
 233
 234 @cindex Main type ASN1_TYPE
 235
 236 The main type used in it is @code{ASN1_TYPE}, and it's used to store
 237 the @acronym{ASN.1} definitions and structures (instances).
 238
 239 The constant @acronym{ASN1_TYPE_EMPTY} can be used for the variable
 240 initialization.  For example:
 241
 242 @example
 243  ASN1_TYPE definitions=ASN1_TYPE_EMPTY;
 244 @end example
 245
 246 Some functions require a parameter named errorDescription of char*
 247 type.  The array must be already allocated and must have at least
 248 @code{MAX_ERROR_DESCRIPTION_SIZE} bytes (E.g, as in @code{char
 249 Description[MAX_ERROR_DESCRIPTION_SIZE];}).
 250
 251 @code{MAX_NAME_SIZE} indicates the maximum number of characters of a
 252 name inside a file with ASN1 definitions.
 253
 254 @node Future developments
 255 @section Future developments
 256 @cindex Future developments
 257
 258 @itemize @bullet
 259
 260 @item Add functions for a C code file generation containing equivalent
 261 data structures (not a single array like now).
 262
 263 @item Type REAL.
 264
 265 @end itemize
 266
 267 @node Utilities
 268 @chapter Utilities
 269
 270 @menu
 271 * Invoking asn1Parser::
 272 * Invoking asn1Coding::
 273 * Invoking asn1Decoding::
 274 @end menu
 275
 276 @node Invoking asn1Parser
 277 @section Invoking asn1Parser
 278 @cindex asn1Parser program
 279
 280 @file{asn1Parser} reads one file with ASN1 definitions and generates a
 281 file with an array to use with libasn1 functions.
 282
 283 @verbatim
 284 Usage:  asn1Parser [options] file
 285
 286 Options:
 287  -h : shows the help message.
 288  -v : shows version information and exit.
 289  -c : checks the syntax only.
 290  -o file : output file.
 291  -n name : array name.
 292 @end verbatim
 293
 294 @node Invoking asn1Coding
 295 @section Invoking asn1Coding
 296 @cindex asn1Coding program
 297
 298 @file{asn1Coding} generates a DER encoding from a file with ASN1
 299 definitions and another one with assignments.
 300
 301 The file with assignments must have this syntax:
 302
 303 @verbatim
 304 InstanceName  Asn1Definition
 305
 306 nameString  value
 307
 308 nameString  value
 309 ...
 310 @end verbatim
 311
 312 The output file is a binary file with the DER encoding.
 313
 314 @verbatim
 315 Usage:  asn1Coding [options] file1 file2
 316  file1 : file with ASN1 definitions.
 317  file2 : file with assignments.
 318 Options:
 319  -h : shows the help message.
 320  -v : shows version information and exit.
 321  -c : checks the syntax only.
 322  -o file : output file.
 323 @end verbatim
 324
 325 @node Invoking asn1Decoding
 326 @section Invoking asn1Decoding
 327 @cindex asn1Decoding program
 328
 329 @file{asn1Decoding} generates an ASN1 structure from a file with ASN1
 330 definitions and a binary file with a DER encoding.
 331
 332 @verbatim
 333 Usage:  asn1Decoding [options] file1 file2 type
 334  file1 : file with ASN1 definitions.
 335  file2 : binary file with a DER encoding.
 336  type : ASN1 definition name.
 337 Options:
 338  -h : shows the help message.
 339  -v : shows version information and exit.
 340  -c : checks the syntax only.
 341  -o file : output file.
 342 @end verbatim
 343
 344 @node Function reference
 345 @chapter Function reference
 346
 347 @menu
 348 * ASN.1 schema functions::
 349 * ASN.1 field functions::
 350 * DER functions::
 351 * Error handling functions::
 352 * Auxilliary functions::
 353 @end menu
 354
 355 @node ASN.1 schema functions
 356 @section ASN.1 schema functions
 357
 358 @include texi/ASN1.c.texi
 359
 360 @node ASN.1 field functions
 361 @section ASN.1 field functions
 362
 363 @include texi/structure.c.texi
 364 @include texi/element.c.texi
 365
 366 @node DER functions
 367 @section DER functions
 368
 369 @include texi/coding.c.texi
 370 @include texi/decoding.c.texi
 371
 372 @node Error handling functions
 373 @section Error handling functions
 374
 375 @include texi/errors.c.texi
 376
 377 @node Auxilliary functions
 378 @section Auxilliary functions
 379
 380 @include texi/parser_aux.c.texi
 381
 382 @node Copying This Manual
 383 @appendix Copying This Manual
 384
 385 @menu
 386 * GNU Free Documentation License::  License for copying this manual.
 387 @end menu
 388
 389 @include fdl.texi
 390
 391
 392 @node Concept Index
 393 @unnumbered Concept Index
 394
 395 @printindex cp
 396
 397 @node Function and Data Index
 398 @unnumbered Function and Data Index
 399
 400 @printindex fn
 401
 402 @bye