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