doc/libtasn1.texi

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