ASN1C V5.4 README

This file contains release notes on the latest release of the ASN1C compiler (version 5.4).

Contents

Introduction

Thank you for downloading this release of the ASN1C software. ASN1C is a powerful ASN.1 compiler capable of parsing and generating C, C++, or Java source code for the most advanced ASN.1 syntax.

This package contains the ASN1C compiler executables and documentation. Separate add-on packages provide the run-time environments for different encoding rules and computer languages. You should have downloaded the main compiler package and one or more run-time encoding rules packages in order to start using the product.

Release Notes

This release of ASN1C adds the following new capabilities to v5.3x:

XML SUPPORT
Support has been added for the XML encoding rules (XER as specified in the ITU-T X.693 standard) to allow XML documents to be encoded and decoded in the same way as other message types (BER, DER, or PER). Support has been added for interfacing with commercial or open source XML parsers via the SAX interface to allow messages read using a parser to be decoded. A possible application for this would be the conversion of a message from XML to one of the other ASN.1 message formats (BER, DER, or PER) and vice-versa.

TABLE CONSTRAINT PROCESSING
Currently ASN1C processes variable type information object references within standard type definitions using open types. This means that when a multi-phase encode is to be performed, the user must manually encode the different parts and populate the open type variable with the resulting encoded message segment. On the decode side, the user must manually decode each segment. An option has been added to v5.4 that uses table constraints and information object set specifications to generate code to encode or decode multi-part messages in a single step. Please see our white paper at: http://www.obj-sys.com/docs/ASN1CInfoObjectsWhitePaper.rtf for more information on this subject.

NEW GENERATED FUNCTIONS
Addition of copy functions, compare functions, and print-to-string functions.

ASN.1 2002 FEATURES
The compiler has been updated to parse all new features present in the 2002 edition of the ASN.1 standards.

64-BIT INTEGER SUPPORT
Support added for mapping the ASN.1 INTEGER type to C/C++ 64-bit integers. Additional functionality has also been added in the area of arbitrary length integer processing (big integers). These are integer value too large to fit in C/C++ integer variables. They are instead represented and manipulated as character string within the code.

PERFORMANCE IMPROVEMENTS
Performance improvements have been made in several areas; particularly in BER/DER decoding. Many message types can now be decoded in half the time as could be done with v5.3x.

IMPROVED STABILITY
Ongoing improvements in the areas of robustness and stability have been made. Extensive testing has been done as a result of the CERT security warnings on ASN.1 and this release includes fixes to all vulnerabilites discovered from these tests.

Compatibility

In an ongoing effort to improve the product, changes have been made in how code is generated in some cases. Users of previous versions of the compiler can achieve backward compatility with their existing code bases by using the compiler '-compat' switch (for example, '-compat 5.3' will generate code compatible with the 5.3 version of the compiler).

The following is a summary of changes that were made in code generation for this release:

Windows Installation

The ASN1C compiler and run-time components are packaged in separate distribution files (kits). This allows for smaller package sizes and allows users to select the run-time components they are interested in (C, C++, or Java).

The steps to install ASN1C on a Windows system are as follows:

  1. Download the main compiler and run-time packages that are of interest to you. The main compiler package includes the ASN1C compiler executables and supporting documentation. The C, C++, and Java run-time libraries are packaged as separate, add-on kits.

  2. First, the self-extracting compiler executable must be installed. This is the executable file that begins with the prefix "accv54" (for example, accv540w32bas.exe). Execute this file and follow the setup instructions.

  3. Next, the optional run-time library component setup files can be installed. Any number of these run-time component libraries can be added to the original installation. Current libraries available include the following:

    rtcv54-w32---.exe C run-time libraries
    rtpv54-w32---.exe C++ run-time libraries
    rtjv54-w32---.exe Java run-time libraries

    (Note: the hyphens (-) are replaced with a minor version number and identification code for the type of run-time kit. For example, rtpv540w32usp.exe denotes version 5.40, unlimited redistribution with run-time source code and PER encode/decode capabilities). Execute the selected file and follow the instructions to add it to the installation base. Make sure the top level directory name that is selected is the same as the one provided in step 2.

  4. Unzip the license.zip file that was attached to the E-mail message that was sent by our auto-responder to the E-mail address that was specified when the software was downloaded. If you did not receive a license file, please contact us.

  5. The acv54lic.dat from inside license.zip must be copied to a location where the compiler and run-time libraries can find it. This can be done one of two ways:

    a. The file can be copied into any of the directories specified within your PATH environment variable, or

    b. The file can be copied to a different directory and an environment variable named 'ACLICDIR' created to point at this directory location.

    Note that licenses from previous versions of ASN1C are not compatible with this release of the product.

The compiler should now be operational. The following command can be executed:

<rootdir>\bin\asn1c

to verify operation.

Contents of the Release

The following subdirectories contain the following files (note: <installdir> refers to the installation directory that was specified during the installation process):

Base Compiler Package

<installdir>\bin\asn1c.exe
<installdir>\bin\asn1c90.exe
The command-line compiler executable files. These are invoked on ASN.1 source files to generate C, C++, or Java encode/decode classes and functions. It is recommended you modify your PATH environment variable to include <installdir>\bin to allow the compiler executable to be run from anywhere.

The special ASN.1 '90 executable (asn1c90.exe) is for parsing older specifications based on the ASN.1 1990 syntax. This compiler contains logic to handle references to ROSE MACROs (OPERATION and ERROR) and SNMP MACROs (OBJECT-TYPE). It will extract the type definitions that are contained within the MACRO definitions for ARGUMENT and RESULT types.

<installdir>\bin\asn1cGUI.exe
The compiler graphic user interface (GUI) wizard executable file. This is the Windows wizard that guides a user through the process of specifying ASN.1 source files and options. This is the program invoked from the start menu or desktop icon.

<installdir>\bin\berfdump.exe
<installdir>\bin\ber2def.exe
<installdir>\bin\ber2indef.exe
Utility programs for operating on BER-encoded files. The first program allows a file to be dumped in a human-readable format. The other two utilities convert files from the use of indefinite to definite length encoding and vice-versa. It can be useful if you need to interoperate with a system that only accepts one of these forms. ASN1C can decode either definite or indefinite length messages. It only encodes definite length messages.

<installdir>\doc\*.pdf
This directory contains the user documentation for the compiler and run-time libraries in Adobe portable document format (.pdf) files.

C run-time libraries and source files

<installdir>\c\dll\*.dll
The ASN1C run-time dynamic link libraries (DLL's). These contain the low-level BER/DER and/or PER run-time functions (note: in this release, XER is not implemented in C, only C++). Link against the library files (.lib) in this directory to use the DLL's.

<installdir>\c\lib\*.lib
The ASN1C run-time static libraries. These contain the low-level BER/DER and/or PER run-time functions (note: in this release, XER is not implemented in C, only C++).

<installdir>\c\libc\*.lib
The compact version of the ASN1C run-time libraries. The compact version has all diagnostic messages, error stack trace and text, and non-essential status checks removed. (Note: these libraries are only available in the licensed version of the product).

<installdir>\c\libd\*.lib
The DLL-ready version of the ASN1C run-time libraries. This version of the library allows linking with other object modules to form dynamic link libraries (DLL's). (Note: these libraries are only available in the licensed version of the product).

<installdir>\c\libdc\*.lib
The DLL-ready / compact version of the ASN.1 run-time libraries. This version of the library allows linking with other object modules to form dynamic link libraries (DLL's) and was built in compact mode (see the description of the libc libraries above). (Note: these libraries are only available in the licensed version of the product).

<installdir>\c\sample_*
The sample directories contain sample programs illustrating the use of the compiler. There are a set of sample programs that correspond to each encoding rule set supported by ASN1C. Most sample programs are broken down into a writer and a reader. The writer encodes a sample data record and writes it to a disk file. The reader reads the encoded message from the file, decodes it, and then prints the results of the decode operation.

<installdir>\rtsrc\*
The installation run-time source directories contain the header files required to compile the compiler generated code. The C or C++ source files will also be located here if the run-time source code kit option was selected.

C++ run-time libraries and source files

The C++ run-time distribution contains all of the files documented in the C section above (under subdirectory cpp instead of c) and adds the following directories/files:

<installdir>\cpp\dllexpat\saxparser.dll
<installdir>\cpp\libexpat\saxparser.lib
The SAX parser DLL and library. These are the interface to XML parser software. The Expat XML parser open source software is bundled in the distribution for use as the default parser. (Note: these files are only present in the XER distribution).

<installdir>\expatsrc
The XML parser run-time source directories contain the source files for the Expat C XML parser and for the SAX abstraction layer for interfacing with the Expat XML parser. (Note: these files are only present in the XER distribution).

<installdir>\msxmlsrc
The MSXML parser run-time source directory contains the source files for the SAX abstraction layer for interfacing with Microsoft XML parser (MSXML). (Note: these files are only present in the XER distribution).

<installdir>\xercessrc
The XERCESC parser run-time source directory contains the source files for the SAX abstraction layer for interfacing with the XERCES XML parser for C++. (Note: these files are only present in the XER distribution).

Java run-time libraries

<installdir>\java\asn1rt.jar
<installdir>\java\asn1rt1.jar
The ASN.1 Java run-time libraries. These contain the low-level BER, PER, and/or XER encode/decode classes. The 'asn1rt.jar' file contains classes compatible with the Java 2 JRE. The 'asn1rt1.jar' file contains classes compatible with the older Java 1.1 standard that is still in widespread use in most web browsers.

<installdir>\java\sample_ber
<installdir>\java\sample_der
<installdir>\java\sample_per
<installdir>\java\sample_xer
Sample programs illustrating the use of the Java version of ASN1C. As was the case for C/C++, most have a writer and a reader. Some contain support code used by other samples (for example, SimpleROSE contains the ROSE headers used by CSTA).
<installdir>/java/doc/*
The ASN.1 Java run-time libraries documentation files. These are html files generated with the javadoc documentation tool. To view the documentation, open the index.html file with a web browser and follow the hyperlinks.

Getting Started with C or C++

The compiler can be run using either the GUI wizard or from the command line. To run the GUI wizard, launch the application and follow the steps. To run a simple test from the command line, do the following:

  1. Open an MS-DOS or other command shell window.

  2. Change directory (cd) to one of the employee sample directories (for example, c/sample_ber/employee).

  3. Execute the nmake utility program:

    nmake

    (note: nmake is a make utility program that comes with the Microsoft Visual C++ compiler. It may be necessary to execute the batch file vcvars32.bat that comes with Visual C++ in order to set up the environment variables to use this utility). If you are using Borland or another compiler, execute the make utility for that compiler.

    This should cause the compiler to be invoked to compile the employee.asn sample file. It will then invoke the Visual C++ compiler to compile the generated C file and the test drivers. The result should be a writer.exe and reader.exe program file which, when invoked, will encode and decode a sample employee record.

  4. Invoke writer from the command line:

    writer

    This will generate an encoded record and write it to a disk file. By default, the file generated is message.dat (in the case of XER, it is message.xml). The test program has a number of command line switches that control the encoding. To view the switches, enter writer ? and a usage display will be shown.

  5. Invoke reader from the command line:

    reader

    This will read the disk file that was just created by the writer program and decode its contents. The resulting decoded data will be written to standard output. The test program has a number of command line switches that control the encoding. To view the switches, enter reader ? and a usage display will be shown.

Getting Started with Java

The compiler can be run using either the GUI wizard or from the command line. To run the GUI wizard, launch the application and follow the steps. To run a simple test from the command line, do the following:

  1. Open an MS-DOS or other command shell window.

  2. Change directory (cd) to one of the employee sample directories (for example, java/sample_ber/Employee).

  3. Execute the build batch file:

    build

    This will cause the ASN1C compiler to be invoked to compile the employee.asn sample file. It will then invoke the Java compiler (javac) to compile all generated java files and the reader and writer programs (Note: JDK 1.4 was used to build all the run-time library classes). It will also automatically execute the writer and reader programs. These programs will produce a writer.log and reader.log file respectively.

    Note: a makefile is also available for use if you have a make utility program available. The makefile is compatible with the GNU make utility and with the Microsoft Visual C++ make utility (nmake).

  4. View the writer and reader log files. The writer.log file will contain a dump of the encoded message contents. The reader.log file will contain a printout of the decoded data.

Known Problems and Issues

There are a few known issues and limitations of the compiler in its current state. The compiler can parse all syntax as defined in the X.680 through X.683 standards (2002) and older X.208 standard. However, no backend code is generated to support the following items:

In addition, the ASN1C compiler is not currently capable of generating forward BER encoders. These encoders encode a message from front-to-back using indefinite length markers for all constructed lengths. Our encoders encode from back-to-front in memory and insert and use definite length markers. The decoders are capable of decoding either form.

It is our desire to make a practical ASN.1 tool that can handle the syntax that people use, not something that can handle every possible syntax. So we are interested in hearing what you are using in practice that doesn't work. In other words, if you create overly complex syntax in order to try and break it, you probably will.

Reporting Problems

Report problems you encounter by sending E-mail to support@obj-sys.com. The preferred format of example programs is the same as the sample programs. Please provide a writer and reader and indicate where in the code the problem occurs.

If you have any further questions or comments on what you would like to see in the product or what is difficult to use or understand, please communicate them to us. Your feedback is important to us. Please let us know how it works out for you - either good or bad.