     [file version.texi not included]

Libtasn1
********

This manual is for GNU Libtasn1 (version VERSION, UPDATED), which is a library for Abstract Syntax Notation One (ASN.1) and Distinguished Encoding Rules (DER) manipulation.

Copyright © 2001--2022 Free Software Foundation, Inc.

     Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.  A copy of the license is included in the section entitled ``GNU Free Documentation License''.

Introduction
************

This document describes the Libtasn1 library that provides Abstract Syntax Notation One (ASN.1, as specified by the X.680 ITU-T recommendation) parsing and structures management, and Distinguished Encoding Rules (DER, as per X.690) encoding and decoding functions.

The main features of this library are:

  * On-line ASN.1 structure management that doesn't require any C code file generation.

  * Off-line ASN.1 structure management with C code file generation containing an array.

  * Distinguished Encoding Rules (DER) encoding support.

  * No limits for INTEGER and ENUMERATED values.

  * It's Free Software. Anybody can use, modify, and redistribute the library under the terms of the GNU Lesser General Public License version 2.1 or later.  The command line tools, self-tests and build infrastructure are licensed under the GNU General Public License version 3.0 or later.

  * Thread-safety. No global variables are used and multiple library handles and session handles may be used in parallel.

  * Portability. The code should work on all Unix like operating systems, and Windows. The library itself should be portable to any C89 system, not even POSIX is required.

ASN.1 structure handling
************************

ASN.1 syntax
============

The parser is case sensitive.  The comments begin with -- and end either with another --, or at the end of the respective line, whichever comes first.  The C-style /*, */ comments are not supported.

For an example of the syntax, check the pkix.asn file distributed with the library.

ASN.1 definitions must follow the syntax below:

      definitions_name {<object definition>}

      DEFINITIONS <EXPLICIT or IMPLICIT> TAGS ::=

      BEGIN

      <type and constants definitions>

      END

The ::= token must be separate from other elements, so the following declaration is invalid:

        -- INCORRECT
        Version ::=INTEGER

The correct form is:

        Version ::= INTEGER

Here is the list of types that the parser can manage:

  * INTEGER;

  * ENUMERATED;

  * BOOLEAN;

  * OBJECT IDENTIFIER;

  * NULL;

  * BIT STRING;

  * OCTET STRING;

  * UTCTime;

  * GeneralizedTime;

  * GeneralString;

  * NumericString;

  * IA5String;

  * TeletexString;

  * PrintableString;

  * UniversalString;

  * BMPString;

  * UTF8String;

  * VisibleString;

  * SEQUENCE;

  * SEQUENCE OF;

  * SET;

  * SET OF;

  * CHOICE;

  * ANY;

  * ANY DEFINED BY.

This version doesn't handle the REAL type.  It doesn't support the AUTOMATIC TAGS option, and the EXPORT and IMPORT sections, either.

The SIZE constraints are allowed, but no check is done on them.

Naming
======

Consider this definition:

      Example { 1 2 3 4 }

      DEFINITIONS EXPLICIT TAGS ::=

      BEGIN

      Group ::= SEQUENCE {
         id   OBJECT IDENTIFIER,
         value  Value
      }

      Value ::= SEQUENCE {
         value1  INTEGER,
         value2  BOOLEAN
      }

      END

The notation to access the Group type of the Example definition above is Example.Group (as a NUL-terminated string.) Such strings are used in the functions described below.

Others examples:

  * field id of the Group type: Example.Group.id;

  * field value1 of the value field of the Group type: Example.Group.value.value1.

Elements of structured types unnamed by the respective definition receive the names ?1, ?2, and so on.

The ?LAST name indicates the last element of a SET OF or SEQUENCE OF.

Simple parsing
==============

For simple types like OCTET STRING the simple parsing functions listed below may be used instead.

  * asn1_decode_simple_der

  * asn1_encode_simple_der

Library Notes
=============

The header file of this library is libtasn1.h.

The main type used in it is asn1_node, and it's used to store the ASN.1 definitions and structures (instances).

The NULL constant can be used for the variable initialization.  For example:

      asn1_node definitions = NULL;

Some functions require an errorDescription argument of type char *, pointing to a pre-allocated buffer of at least ASN1_MAX_ERROR_DESCRIPTION_SIZE bytes size (e.g., as in char description[ASN1_MAX_ERROR_DESCRIPTION_SIZE];).

ASN1_MAX_NAME_SIZE is the maximum number of characters allowed for an ASN.1 identifier.

Future developments
===================

  * Add functions for a C code file generation containing equivalent data structures (not a single array like now).

  * The REAL type.

Utilities
*********

Invoking asn1Parser
===================

asn1Parser reads a single file with ASN.1 definitions and generates a file with an array to use with libtasn1 functions.

     [file asn1Parser-help.texi not included]

Invoking asn1Coding
===================

asn1Coding generates a DER encoding from a file with ASN.1 definitions and another one with assignments.

The file with assignments must have this syntax:

InstanceName  Asn1Definition

nameString  value

nameString  value
...

To specify the field of a CHOICE to be used, specify its name as a value to the CHOICE element itself.  Use '' to denote the root element itself. (as in the example below.)

The output file is a binary file with the DER encoding.

     [file asn1Coding-help.texi not included]

For example, consider an ASN.1 definitions file as follows:

MYPKIX1 { }

DEFINITIONS IMPLICIT TAGS ::=

BEGIN

OtherStruct := SEQUENCE {
     x       INTEGER,
     y       CHOICE {
         y1 INTEGER,
         y2 OCTET STRING },
}

Dss-Sig-Value ::= SEQUENCE {
     r       INTEGER,
     s       INTEGER,
     other   OtherStruct
     z       INTEGER OPTIONAL,
}

END

And a assignments file as follows:

dp MYPKIX1.Dss-Sig-Value

r 42
s 47
other.x 66
other.y y1
other.y.y1 15
z (NULL)

Running the command below will generate a assign.out file, containing the DER encoding of PKIX1.Dss-Sig-Value.

$ asn1Coding pkix.asn assign.asn1

If the root element is of the CHOICE type, the assignment file may be like (using the types defined in pkix.asn):
elt PKIX1Implicit88.GeneralName

''      dNSName
dNSName example.org

Invoking asn1Decoding
=====================

asn1Decoding generates an ASN.1 structure from a file with ASN.1 definitions and a binary file with a DER encoding.

     [file asn1Decoding-help.texi not included]

For example, after generating the assign.out file from the example section of the asn1Coding command above, the following invocation will decode the DER data.

$ asn1Decoding pkix.asn assign.out PKIX1.Dss-Sig-Value

Function reference
******************

ASN.1 schema functions
======================

     [file ASN1.c.texi not included]

ASN.1 field functions
=====================

     [file structure.c.texi not included]
     [file element.c.texi not included]

DER functions
=============

     [file coding.c.texi not included]
     [file decoding.c.texi not included]

Error handling functions
========================

     [file errors.c.texi not included]

Auxilliary functions
====================

     [file parser_aux.c.texi not included]
     [file version.c.texi not included]

Copying Information
*******************

GNU Free Documentation License
==============================

     [file fdl-1.3.texi not included]