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