IvmaiAsn ASN1/ECN/XDR Tools

General

The major goals of this project are:

• develop an editor syntax highlighter for ASN.1 and ECN specifications;
• develop a pretty-printer (HTML generator) for ASN.1 and ECN specifications;
• develop an LL(1) parser for ASN.1:2002 and ECN (EDM/ELM) specifications;
• formally describe the ASN.1 built-in types in terms of ASN.1 itself (to simplify the development of an ASN.1 compiler);
• formally describe the ECN built-in encoding classes in terms of ECN itself and ASN.1 (to simplify the development of an ECN compiler);
• develop an LL(1) parser for XDR specifications;
• develop a specification converter from XDR notation to ASN.1 one;
• using the ECN notation, formally describe the XDR encoding rules (which could be applied to the converted XDR specifications).

Usage guidelines

The pretty-printer for ASN.1 and ECN:

• get and install the Colorer Library;
• install asn1.hrc add-on script into the Colorer Library (as explained in asn1.hrc) if not there;
• optionally install htmlcss.hrd into the Colorer Library (as explained in htmlcss.hrd) if not there;
• use "colorer" executable to generate an HTML file for a given ASN.1 or ECN specification (the input file name must have .asn, .asn1, .ecn, .edm or .elm extension);
• if "htmlcss" schema is used then place "hrdstyle.css" file (either the original one or your "customized" variant of it) along with the generated HTML files (in the same folder).

The editor syntax highlighting support for ASN.1 and ECN:

• get and install the Colorer plugin (only FAR, Eclipse and Midnight Commander have support for the Colorer at present);
• install asn1.hrc add-on script into the Colorer plugin (if not already there) as explained in asn1.hrc.

Notes for the pretty-printer and syntax highlighter support:

• the syntax highlighter script supports both the new (2002) and the old versions of ASN.1 (including the old MACRO notation);
• the syntax highlighter script supports only the new "take5" version of the Colorer Library (or plugin);
• "htmlcss" Colorer HRD script (together with the accompanying "hrdstyle" HTML style sheet) is not related to ASN.1/ECN technologies and has been developed for pretty-printing convenience (as an alternative to the Colorer "-ht" option);
• the latest version of the Colorer Library (available from its public SVN) might already have ASN.1 support (as well as "htmlcss" hrd/text schema).

Guidelines for building the ASN.1/ECN parser manually (that is, without running the supplied build.xml file):

• get and unpack Coco/R for Java V1.15 (the previous or later versions may not fit);
• apply the required bug-fixes to the original Coco/R for Java V1.15 as described in "asn2002s.atg" file and rebuild the Coco/R;
• run the modified Coco/R against "asn2002s.atg";
• modify the generated Scanner and Parser java files as described in "asn2002s.atg";
• compile the modified generated Scanner, Parser and ErrorStream java files.

Notes for the XDR-to-ASN1 converter:

• the converter, for a given XDR specification, produces the equivalent legacy ASN.1 specification (preserving the identifiers);
• to preserve the binary protocol format for a converted XDR specification, "IvmaiAsn-XDR-Encoding" encoding module should be applied to it (this requires an ECN compiler);
• all the comments present in an input XDR specification are preserved in the output ASN.1 specification;
• if xdr2asn1 is invoked without "-d" command-line option then xdr2asn1 only checks the validity (syntax) of the input XDR specification file (the resulting equivalent ASN.1 specification file is not written);
• xdr2asn1 also checks and translates the RPC notation;
• there is no definition of the #REAL encoding class in the current version of ECN (2002), so the XDR floating-point types (in a specification generated by "xdr2asn1" converter) should be manually re-defined as ASN.1 "OCTET STRING" (with the corresponding fixed size constraint) to make an ECN compiler apply "IvmaiAsn-XDR-Encoding" rules correctly;
• "IvmaiAsn-XDR-Encoding" rules set has not been tested thoroughly.

Notes for "IvmaiAsn-ECN-CLASS" and "IvmaiAsn-USEFUL" ASN.1 modules:

• some of the ASN.1 built-in types cannot be precisely described in terms of ASN.1 itself;
• some of the ECN built-in encoding classes have no special encoding class yet (and, thus, cannot be precisely described in terms of ASN.1).

asn2002s information and usage

This program is developed for quick syntax checking of data specifications written in the ASN.1 and/or ECN descriptive languages (strictly the version of year 2002 with Amendment 1). To learn about the ASN.1 (Abstract Syntax Notation One), see ITU-T X.680 .. X.683 documents. To learn about the ECN (Encoding Control Notation), see ITU-T X.692 document.

To do syntax checking, You should run this program with one or more arguments specifying the names of the input files containing the data specifications You need to check (You may also use wildcards to specify a group of files). If no syntax error is found (in every of the specified files supplied for checking) then the program just prints 'Ok' message and exits. Otherwise, the program stops at the first file containing one or more errors, and shows the list of these found errors together with their line numbers.

Program features: strict syntax checking for conformance with the ASN.1 and ECN standards; extremely fast (since it is built on LL(1) parser); every file (every ASN.1 or EDM, or ELM module) is checked independently on the others; the program is free for use. Disadvantage: the semantic errors are not checked by this program.

Abbreviations

The following acronyms are in use:

• ASN.1 - Abstract Syntax Notation One (defined in ITU-T X.680-683);
• ASN.1:2002 - the modern version of ASN.1 (draft published in year 2002);
• ATG - Attributed-Type Grammar (the Coco/R parser generators notation);
• Coco/R - an LL(1) compiler generator;
• ECN - Encoding Control Notation (defined in ITU-T X.692);
• EDM - Encoding Definition Module (part of ECN);
• ELM - Encoding Link Module (part of ECN);
• FAR - console File and Archive Manager program (for Windows);
• IETF - Internet Engineering Task Force (open international community);
• ITU-T - International Telecommunication Union (formerly known as CCITT);
• JRE - Java Runtime Environment (includes a Java Virtual Machine);
• LL(1) - a top-down parser (with one lookahead token) for a subset of the context-free grammars;
• RPC - Remote Procedure Call protocol and specification language (defined in IETF RFC 1831);
• XDR - External Data Representation protocol and specification language (defined in IETF RFC 1832).

List of files

The official binary distributive files contain:

• GNU_GPL.txt - the GNU License;
• README.txt - this file;
• asn2002s.jar (or asn2002s.exe) - IvmaiAsn ASN.1/ECN:2002 Syntax-only Checker;
• xdr2asn1.jar (or xdr2asn1.exe) - IvmaiAsn XDR-to-ASN1 specification converter.

The source collection consists of:

• ChangeLog - the standard changes log file;
• GNU_GPL.txt - the GNU License;
• README.txt - this file;
• asn1prod.txt - the ASN.1:2002 "original" syntax productions (as specified in ITU-T Recommendation X.680 - X.683);
• build-colored-docs.bat - the Windows script generating 'colored' HTML documents for IvmaiAsn-ECN-CLASS.asn, IvmaiAsn-ECN-USEFUL.edm, IvmaiAsn-USEFUL.asn, IvmaiAsn-XDR-Encoding.edm, asn1_hrc_demo.asn and hrdstyle.css files;
• build-win32-x86-jcgo.bat - building script for Win32 target (builds asn2002s and xdr2asn1 tools);
• build.xml - the Apache Ant script for building the binary release (for JRE) containing asn2002s and xdr2asn1 tools (the script requires the original Coco/R for Java V1.15 tar-ball to be unpacked into the newly-created "jcoco115" folder);
• ecnprod.txt - the ECN:2002 "original" syntax productions (as specified in ITU-T Recommendation X.692);
• asnmods/IvmaiAsn-ECN-CLASS.asn [colored view] - the ECN built-in primary encoding classes definition expressed as a valid ASN.1 module (could be used as a user formal reference for ECN notation, or as a part of an ECN compiler);
• asnmods/IvmaiAsn-ECN-USEFUL.edm [colored view] - the ECN built-in derivable encoding classes definition expressed as a valid ECN (EDM) module (could be used as a user formal reference for ECN encoding classes, or as a part of an ECN compiler);
• asnmods/IvmaiAsn-USEFUL.asn [colored view] - the ASN.1 built-in and "useful" types definition expressed as a valid ASN.1 module (expressed as precisely as possible, could be used as a user formal reference for ASN.1 built-in types, or as a part of an ASN.1 compiler);
• asnmods/IvmaiAsn-XDR-Encoding.edm [colored view] - XDR encoding rules expressed as a valid ECN (EDM) module (this EDM module could be applied to ASN.1 specifications generated by "xdr2asn1" converter tool);
• color/asn1.hrc - the Colorer Library add-on script ("colorizing" scheme) for ASN.1/ECN specifications syntax highlighting (in editors) and pretty-printing;
• color/asn1_hrc_demo.asn [colored view] - Syntax highlighting demo for ASN.1 (the purpose of this file is to show how various ASN.1 lexical elements are colorized in the editor or pretty-printer);
• color/hrdstyle.css [colored view] - the customizable style sheet for HTML files produced by the Colorer HTML generator (pretty-printer) with "htmlcss" HRD schema;
• color/htmlcss.hrd - a convenient Colorer add-on HRD schema (script) to produce "colorized" HTML documents having syntax highlighting style fully governed by the customizable "hrdstyle" cascading style sheet file;
• src/asn2002s-jcoco.diff - the required patch for the files produced by the modified Coco/R for asn2002s.atg (the same as described in the file);
• src/asn2002s.atg - ASN.1/ECN:2002 syntax checker source (written in Coco/R for Java ATG);
• src/jcoco115.diff - the patch for "Coco/R for Java" V1.15 (jcoco115) required, at least, for building asn2002s (the same as described in asn2002s.atg);
• src/xdr2asn1-jcoco.diff - the required patch for the files produced by Coco/R for xdr2asn1.atg (the same as described in the file);
• src/xdr2asn1.atg - XDR/RPC syntax checker and XDR-to-ASN1 specification converter (written in Coco/R for Java ATG).

Bibliography

See the Bibliography page.

Web resources

See the Web resources page.

For more links, please visit "Java and C/C++ developer web resources" hosted on the JCGO project (a java2c/java2exe solution) site.

User's feedback

Any questions, suggestions, bug reports and patches are welcomed at the IvmaiAsn site tracker (hosted at SourceForge.net).