ASN1C V7.7.x README

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

Contents

Introduction

Thank you for downloading this release of the ASN1C software. ASN1C is an ASN.1 compiler (code generator) capable of parsing and generating C, C++, C#, Java, Python, or Go source code for the most advanced ASN.1 syntax.

This package contains the ASN1C compiler executables and run-time libraries. Documentation is available online at https://obj-sys.com/support/asn1c-manuals.php

Release Notes

This release of ASN1C adds the following new capabilities:
Support added for BER/DER encode and decode in Go

Support has been added for generating code in Go to support the Basic and Distinguised Encoding Rules (BER and DER). For BER, this includes support for 3GPP TS 32.297 headers for CDR processing.

New command-line option -go-rt-inc added for Go

The -go-rt-inc (Go run-time include) command-line option has been added to allow a user to force inclusion of a Go run-time module in the compiled module set. Normally Go compilation includes only the dependent modules for a given compilation. The main purpose of this is to allow a user to include a module that they may be interested in using in their main.go file (for example, TS 32.297, TBCD, BCD, or BER dump utility functions).

Elimination of the Windows 32-bit SDK

There is no longer an SDK for Windows 32-bit. Instead, there is a single Windows SDK that contains both 32 and 64 bit run-time libraries. The compiler and ASN1C GUI are built for use on Windows 64-bit systems and will not work on 32-bit.

New default version of Visual Studio for Windows SDKs

The default version of Visual Studio for Windows SDKs is now Visual Studio 2019. The libraries in the c and cpp (or c_64 and cpp_64) hierarchies are now built with Visual Studio 2019. The default format for Visual Studio project files that ASN1C generates is now Visual Studio 2019.

Updated C# project file generation

C# project file generation (the -vcproj qualifier) has been changed to make the default version Visual Studio 2019.

Support for .Net v5 and .Net v6

The ASN1C SDK and C# run-time kits now contain asn1rt DLLs that target .Net v5 and .Net v6. The DLL that targets .Net v4 is still included.

New asn1c command line qualifiers named -dotnetv5 and -dotnetv6 have been added that will cause a .Net v5 or .Net v6 .csproj file to be generated if used with the -csharp and -vcproj qualifiers. If neither of these new qualifiers is specified, a generated .csproj file will target .Net v4.

PLMNidentity support

ASN1C will now recognize a production named PLMNidentity (e.g., from the RANAP specifications) and will treat it as an OCTET STRING. A command line option -noPLMN has been added to disable this special recognition and treat the production as it's defined in the ASN.1. An <isPLMNidentity> configuraton file item has also been added at production level to identify any production as a PLMNidentity. This new functionality is supported for all languages.

In line with the PLMNidentity changes, the following functions and methods have been added:

  • C/C++: rtStringToPLMNidentity(), rtGetMCCFromPLMNidentity(), and rtGetMNCFromPLMNidentity().
  • Java: Asn1Util.stringToPLMNidentity() and Asn1Util.PLMNidentityToString().
  • C#: Asn1Util.StringToPLMNidentity() and Asn1Util.PLMNidentityToString().
  • Python: plmnidentity_str_to_bin() and plmnidentity_bin_to_str() in util.py.
  • Go: StrToPLMNidentity() and PLMNidentityToStr() in PLMNidentityUtils.go

Java XML parser options in the GUI

Java XML parser options (XMLPull and StAX) have been added to the GUI. (A1C-727)

asn1c command in generated code

Generated code will now contain a comment with the asn1c command that was used to do the generation. (A1C-678)

Defined values for tags

Tags can now use defined values for the tag value. The value must be INTEGER type and non-negative.

Addition of the -dynamic command-line option

The -dynamic command-line option has been added which has the same effect as adding <storage>dynamic</storage> at the global level in a configuration file. It will cause dynamic memory to be used for all binary and character string types whether the type has a size constraint or not. It will also cause dynamic arrays to be used for repeating types. In addition, this will also now cause a dynamic array to be used for the set of subidentifiers in an OBJECT IDENTIFIER or RELATIVE-OID structure.

64-bit mingw libraries

The ASN1C 64-bit Windows SDK now includes run-time libraries built with 64-bit mingw.

Named bit support in print to stream and print to string

Code generated for C or C++ with print to stream or print to string enabled will now print names of bits in BIT STRINGs where applicable. This feature was already present in code generated for regular printing.

Modified distribution file names for macOS

Distribution files for macOS now have names that more accurately convey the target platform. For macOS on x64 the distribution file will have macos_x64 in the name, and for macOS on M1 the distribution file will have macos_m1 in the name.

Modified handling of non-fatal C/C++ decoding errors

In v7.6 C/C++ decoding the only non-fatal decoding errors that would be reported at the end of the decode step would be constraint violations. In v7.7 any non-fatal decoding errors will be reported, not just constraint violations.

TBCD utilities for Go

Utilities to convert a TBCD array to a string and to convert a string to a TBCD array have been added in a new file named TBCDUtils.go.

BCD utilities for Python

Utilities to convert a BCD array to a string and to convert a string to a BCD array have been added to the util.py file.

BCD utilities for Go

Utilities to convert a BCD array to a string and to convert a string to a BCD array have been added in a new file named BCDUtils.go.

New Java TS32297Encode sample

A new java/sample_ber/TS32297Encode sample has been added that shows how to encode TS 32.297 headers using Java.

New C# TS32297Encode sample

A new csharp/sample_ber/TS32297Encode sample has been added that shows how to encode TS 32.297 headers using C#.

New Commands added to the ASN1C GUI

The 'File->Open Folder..' and 'Edit->Find in Files/Replace in Files' commands were added to the ASN1C GUI. The former allows opening a folder containing ASN.1 and configuration files all of which will be opened in the editor. The 'Find/Replace in Files' commands allows multiple files to be searched at a time.

Compatibility

The C/C++ types generated for the built-in EXTERNAL and EmbeddedPDV types are different due to the -dynamic option described above. That is because these types are configured to use dynamic storage and this causes a different type to be used for the OBJECT IDENTIFIER's contained within (ASN1DynOBJID instead of ASN1OBJID).

The C/C++ print to string capability has been enhanced so the string that gets created contains the names of bits for BIT STRINGs that have such identifiers. Existing code that uses this functionality may need to be revised to allocate a larger buffer.

In v7.6 C/C++ decoding the only non-fatal decoding errors that would be reported at the end of the decode step would be constraint violations. In v7.7 any non-fatal decoding errors will be reported, not just constraint violations. This change may cause some decode scenarios to terminate with an error that didn't before.

Documentation

Documentation for this release is available online at the following URL:

https://obj-sys.com/support/asn1c-manuals.php

Windows Installation

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

  1. Download the ASN1C SDK which contains the compiler (code generator) and run-times for C/C++, Java, and C#. The C/C++ run-time contains libraries built with the Microsoft Visual Studio 2015, 2017, 2019 and 2022 compilers, the Cygwin gcc compiler (32-bit SDKs only), and the Minimalist GNU for Windows (MinGW) compiler.
  2. ASN1C for Windows is packaged in a self-extracting executable file format. To install, all that is necessary is to double-click the file after downloading and then following the setup wizard instructions from that point.
  3. After installation is complete, the license for the product must be installed. This can come in two forms - as a license file or a license key value. Instructions for installing the license key or file are available the the following URL:

    https://obj-sys.com/support/acguiLicInstall.php

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

    <rootdir>\bin\asn1c

    to verify operation.

  4. To use the Python code generation capability, the Python run-time package must first be installed. This can be done by executing the following command:
    pip install --find-links https://www.obj-sys.com/PythonRuntime --no-deps osyspyrt

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

The command-line compiler executable file. This is invoked on ASN.1 or XSD source files to generate C, C++, C#, Java, Python, or Go 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.

<installdir>\bin\acgui.exe

The compiler graphic user interface (GUI) editor executable file. This GUI guides a user through the process of specifying ASN.1 or XSD source files and options. This is the program invoked from the start menu or desktop icon.

<installdir>\bin\asn2xsd.exe

ASN.1 to XML Schema (XSD) translation tool.

<installdir>\bin\berfdump.exe
<installdir>\bin\berfdump2.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.

<installdir>\bin\dumpasn1.exe

A public-domain ASN.1 BER/DER encoded data dump tool. Thanks to Peter Gutmann for making this available for public use. The full source code for this program can be found in the utils subdirectory of the installation.

<installdir>\bin\xsd2asn1.exe

XSD-to-ASN.1 translation program executable file. This program translates an XSD file to its ASN.1 equivalent as per the ITU-T X.694 standard.

<installdir>\doc

This directory contains documentation files. Note that the bulk of the documentation items are now available online (see the Documentation section above).

<installdir>\scripts

This directory contains Perl script files for doing source code editing and other transformations. The rtport.pl script is included in this release to port existing C/C++ applications that use ASN1C generated code from version 5.8 or lower to be compatible with the latest release of the product.

<installdir>\specs

This directory contains ASN.1 specifications from many standards that have been pre-compiled and tested. In some cases, syntax errors that may have existed in the original standards were fixed.

<installdir>\templates

This directory contains template files for applications such as client and server code generation. It is possible for users to alter these files to customize code that is generated or to add new template files for use with -gen-from-template command-line option.

<installdir>\utils

This directory contains the source code and build makefile for some of the utility programs included in the bin subdirectory.

<installdir>\xsd\lib\asn1.xsd

This directory contains the common XML schema definitions (XSD) library. This contains type mappings for built-in ASN.1 types that do not have an equivalent types defined in XSD.

<installdir>\xsd\sample

This directory contains sample programs related to the conversion of ASN.1 to XML Schema. It also contains the XSD.asn ASN.1 specification which contains the XSD ASN.1 module that is sometimes referenced in ASN.1 files that are the result of an XSD-to-ASN.1 translation.

C/C++ run-time libraries and source files

<installdir>\c\lib\* (Visual C++ 2019 libraries)
<installdir>\c_vs2015\lib\* (Visual C++ 2015 libraries
<installdir>\c_vs2017\lib\* (Visual C++ 2017 libraries
<installdir>\c_vs2022\lib\* (Visual C++ 2022 libraries
<installdir>\c_gnu\lib\*.a (Cygwin GNU gcc) (32-bit SDKs only)
<installdir>\c_mingw\lib\*.a (MinGW gcc)

The ASN1C C run-time library files. These contain low-level run-time functions for the various encoding rules supported by ASN1C. For each encoding rules type, there is a dynamic link library (.dll) and standard library file (.lib) for linking with the DLL. There is also a static library for direct linkage to the object modules (this is the library file with the '_a.lib' suffix). The licensed version of the product also contains a DLL-ready library (compiled with -MD option) for building your own value-added DLL's. Also note that the evaluation and development libraries are not fully optimized (they contain diagnostic tracing and are not compiled with compiler optimization turned on). The deployment libraries are fully optimized.

<installdir>\cpp\lib\* (Visual C++ 2019 libraries)
<installdir>\cpp_vs2015\lib\* (Visual C++ 2015 libraries
<installdir>\cpp_vs2017\lib\* (Visual C++ 2017 libraries
<installdir>\cpp_vs2022\lib\* (Visual C++ 2022 libraries
<installdir>\cpp_gnu\lib\*.a (Cygwin GNU g++) (32-bit SDKs only)
<installdir>\cpp_mingw\lib\*.a (MinGW g++)

The ASN1C C/C++ run-time library files. These are the same as the C run-time libraries above except they contain run-time C++ classes as well as C run-time functions.

<installdir>\c*\lib_opt\*
<installdir>\c*\lib_compact\*
<installdir>\cpp*\lib_opt\*

The optimized and/or compact version of the ASN1C run-time libraries. These libraries have all diagnostic messages, error stack trace and text, and non-essential status checks removed. The optimized libraries are built with C compiler speed optimizations options set; the compact libraries use space optimization options. (Note: these libraries are only available in the licensed deployment version of the product. If you wish to do performance testing, please contact us and we will make them available to you).

<installdir>\c*\lib_debug\*
<installdir>\cpp*\lib_debug\*

The debug DLL versions of the ASN1C run-time libraries. These are the same as the DLL C/C++ run-time libraries above except they are linked with debug versions of Standard C Run-time DLLs. (Note: these libraries are only available in the licensed development version of the product (SDK)).

<installdir>\c\sample_*
<installdir>\cpp\sample_*

The sample directories contain sample programs demonstrating 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\*
<installdir>\rtxsrc\*

Run-time source directories containing common type and class definitions used by all encoding rules. 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.

<installdir>\rt*ersrc\*

Run-time source directories for various ASN.1 encoding rules. These contain common code for encoding and decoding using the specific rules. Directories are currently present for BER/DER/CER, PER (aligned and unaligned), MDER, OER, and XER rules.

<installdir>\rtjsonsrc\*

JSON specific run-time source directory. These contain common code for encoding/decoding JSON messages.

<installdir>\rtxmlsrc\*

XML specific run-time source directory. These contain common code for encoding/decoding XML messages.

Java run-time libraries

<installdir>\java\asn1rt.jar

ASN.1 Java run-time libraries. These contain the low-level encode/decode classes for the various encoding rules supported by ASN1C. The asn1rt.jar file contains classes compatible with the Java 5 JRE.

<installdir>\java\sample_*

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.

<installdir>\java\xmlpull\*

The kXML pull-parser implementation. This parser is used in the generated XER and XML decode classes.

<installdir>\java\xerces\*

The Apache Xerces Java XML parser implementation. This parser is used to support legacy SAX parsing in the generated XER and XML decode classes. Note that SAX parsing is a deprecated feature at this time.

C# run-time libraries

<installdir>\csharp\asn1rt.dll

The ASN.1 C# run-time library DLL, built with Visual Studio 2019 and targeting .Net v4. This contains the low-level BER, PER, and/or XER encode/decode classes.

<installdir>\csharp\vs2019_dotnetv5\asn1rt.dll

The ASN.1 C# run-time library DLL, built with Visual Studio 2019 and targeting .Net v5. This contains the low-level BER, PER, and/or XER encode/decode classes.

<installdir>\csharp\sample_*

Sample programs demonstrating the use of the C# 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).

Python

<installdir>\python\sample_*

Sample programs demonstrating the use of the ASN1C Python code generation capability. These contain Python writer and reader script programs to encode and decode data respectively. Code can be generated using the included makefile or ASN1C GUI project file.

Go

<installdir>\golang\asn1rt

This directory contains the Go ASN.1 run-time source files that are used by the compiler to add the base run-time source code to the generated code to form a complete Go language application.

<installdir>\golang\sample_*

Sample programs demonstrating the use of the ASN1C Go code generation capability. These contain a Go main.go file that contain a writer and reader section to encode and decode data respectively. Code can be generated using the included makefile.

Getting Started with C or C++

The compiler can be run using either the GUI or from the command line. To run the GUI, launch the application and follow these steps. To run a simple test from the command line, do the following:
  1. Open a Windows Command Prompt (Start -> Accessories -> Command Prompt) or other command shell window. If using Visual Studio, it is best to open a command prompt window for that version under the Visual Studio Tools group of the main menu pulldown item.

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 a 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 6 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.

Getting Started with 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. Make sure Microsoft .NET v4 or v5 is installed on your system. If using v5, copy the asn1rt.dll file from the csharp\vs2019_dotnetv5 folder to the csharp folder.
  2. Open the appropriate Visual Studio command prompt (e.g., VS 2019).
  3. Execute the nmake command to run the complete sample program. The makefile will invoke the ASN1C compiler to generate C# code for the ASN.1 definition and then compile the generated C# code.
  4. Execute writer.exe to encode a binary message and write it to a file.
  5. Execute reader.exe to read the file containing encoded binary message and decode it.

Getting Started with Python

Before Python can be used, the Python run-time must be installed using the following command:
pip install --find-links https://www.obj-sys.com/PythonRuntime --no-deps osyspyrt

The compiler can then 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 a Visual Studio command prompt window. Note that this is necessary because the Visual Studio nmake utility is used to run makefiles on Windows. cd to one of the sample directories under the python subdirectory. For example, python\sample_ber\employee.
  2. Execute the nmake command to run the complete sample program. The makefile will invoke the ASN1C compiler to generate Python code for the ASN.1 definition and then compile and run the writer.py and reader.py scripts.
  3. Execute python writer.py to encode a binary message and write it to a file.
  4. Execute python reader.py to read the file containing encoded binary message and decode it.

Note that the evaluation version of the Python code generation capability contains limits on the size of the ASN.1 files that can be compiled. It is inteneded to just demonstrate the basic functionality of this capability. To remove these limits, either a commercial-use license must be purchased, or a special evaluation license agreement signed.

Getting Started with Go

Go sample programs can be run as follows:

  1. Open a Visual Studio command prompt window. Note that this is necessary because the Visual Studio nmake utility is used to run makefiles on Windows. cd to one of the sample directories under the golang subdirectory. For example, golang\sample_per\employee.
  2. Execute the nmake command to run the complete sample program. The makefile will invoke the ASN1C compiler to generate Go code for the ASN.1 definition and then compile and run the compiled Go executable file with writer and reader arguments. The Go executable file is named 'go_test.exe'.
  3. Execute the Go executable with argument writer to encode a binary message and write it to a file. For the employee sample program, the command would be .\go_test writer
  4. Execute the Go executable with argument reader to read the file containing encoded binary message and decode it. For the employee sample program, the command would be .\go_test reader

Go compilation in the evaluation version is a limited to ASN.1 files with 800 lines or less. To have this limit removed, please contact us.

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.