Cryptix ASN.1 Kit

Version 0.1.10 - Build 29

What is it?
What are the pre-requisites?
How to install?
Are there any examples on how to use it?
Where is the API documentation?
Are there any good references on ASN.1?
How much does it cost?
What sort of licence is it under?
Changes since last release
Known limitations
Roadmap

1. What is it?

The Cryptix ASN.1 Kit is a collection of software programs -collectively referred to as Software- that allows a programmer to:

Generate .java source files that model ASN.1 types defined in input text files containing well formed ASN.1 constructs (according to a subset of the ASN.1:1990 syntax).
Use the generated .java source files as the basis for customised or proprietary added features in other applications.

The Software aims at facilitating the task programmers face in coding, accessing and generating java-bound both types and values defined as ASN.1 constructs or encoded as such. At the same time, the Software demonstrates the power of ASN.1 in separating the notation from its encoding(s). The test classes, included in the distribution, use a DER encoder/decoder as well as a XER encoder to demonstrate how one can:

Define an ASN.1 construct, from a given specifications file; ie. parse that file, generate the .java classes and compile them;
Decode an instance from a DER input data stream,
Encode the same to an XML output data stream.

2. What are the pre-requisites?

As a User

The Kit uses the following tools in addition to a JDK 2 (this release has been tested with the JDK 1.3.1):

The SableCC compiler's compiler tool, hosted at SourceForge,
The log4j logging framework: an Apache project,
The java-getopt package from Aaron Renn.

As a Developer

This software is being developed, tested and maintained using the following tools:

The Jikes Java compiler,
The GNU Cygwin Tools, especially bash and make.
The JUnit regression test framework from junit.org.

This project is hosted on .

To actively participate in its on-going development, register as a developer and e-mail me your user name and ID.

3. How to install?

Unpack the distribution to a directory;
Get copies of the required software, extract the relevant .jar from each of them and put it in the lib folder inside the installation directory / folder.
For the getopt package only, just rename the .jar file to java-getopt.jar.

4. Are there any examples on how to use it?

There are two examples included in the distribution. They are part of the test package (located in src/test in the distribution folder). Both test classes assume that the .java classes for an ASN.1 specifications file (cryptix.asn in the etc folder inside the installation folder) have been already generated and compiled --The Makefile test target does just that:

test.TestDer
- Reads a file containing a DER encoded Certificate instance, already generated according to the profile described in the previously mentioned specifications (etc/cryptix.asn). The file is assumed to be src/test/1eecert.x509 in the distribution folder;
- Instantiates a DER Decoder and decodes the file's contents populating an instance of a Certificate in memory;
- Compares OID values in two different fields;
- Extract some other fields and print them to System.out;
- Manufactures a new Certificate instance using random and pre-programmed values;
- Signs the newly created instance with an MD5withRSA signature algorithm;
- Sets the signature field of this Certificate instance to the calculated value;
- Prints the Certificate to System.out;
- Instantiates a XER Encoder;
- Uses this encoder to encode the manufactured Certificate instance;
- Decodes the data again; and finally
- Prints the decoded data to System.out.
test.TestXer:
- Does similar things to TestDer, except that the Encoder is a XER one, and the output is saved into a file (anX509.xer in the current working directory), so it can be viewed after the program terminates.

5. Where is the API documentation?

To access the on-line version of the documentation, click here.

The Javadoc API documentation can be generated from the source files which are included in the distribution. If you have installed the GNU Cygwin Tools then:

cd to the installation directory,
invoke make docs.

If you have already generated the documentation as described earlier, then click here to browse your local copy.

If you are not a developer, then the only additional documentation is how to use the Main tool of the distribution which is effectively the Java code generator. To view a usage of the tool, type the following at your console:

java -jar lib/cryptix-asn1.jar -h
or
java -jar lib/cryptix-asn1.jar --help

you should see something like the following displayed on your console:

Cryptix ASN.1 Kit ASN.1-to-Java compiler
Copyright (C) 1997-2001 The Cryptix Foundation Limited.
All rights reserved.

Revision:
Date:

Usage:
  java -jar cryptix-asn1.jar [options] [--] specification...
or
  java cryptix.asn1.tools.Main [options] [--] specification...

Where options are:
  -h
  --help
     Prints this text.
  -D[
directory]
  --Destination=[
directory]
     The name of the destination directory for generated sources.
     If unspecified, then the current directory is assumed.
  -P 
module-name=
package-name
  -P

module-name=
package-name=

  --Package=

module-name=
package-name
     The name of a package to map an ASN.1 module name to. This may
     be repeated as many times as required. If no mapping is found,
     the ASN.1 module name will be used as the package name.
  specification
     A non-empty, space separated, list of ASN.1 specifications
     file(s) to process.

Example:
  java -jar cryptix-asn1.jar \
     -Dtmp \
     -P CryptixUsefulDefinitions=cryptix.asn1.common \
     -P PKCS-6=cryptix.asn1.pkc6 \
     cryptix.asn pkcs6

6. Are there any good references on ASN.1?

Specification of Basic Notation (X.680), and Specification of Basic Encoding Rules (BER), Canonical Encoding Rules (CER) and Distinguished Encoding Rules (DER) (X.690) documents. Also available on the net in PDF (X.680, X.690).
A Layman's Guide to a Subset of ASN.1, BER, and DER.
Understanding OSI, (by Professor John Larmouth), University of Salford; Chapter 8:
XER (XML Encoding Rules),
ASN.1 Complete, by Professor John Larmouth,
ASN.1 Homepage (by Philipp Hoschka),
ASN.1 Information Site.

7. How much does it cost?

The Software is free for commercial and non-commercial use. The Software also includes the .java source files.

8. What sort of licence is it under?

The Software is licensed under the Cryptix General Licence (CGL). A copy of the CGL is included in the distribution. It is also available from the Cryptix home page.

9. Changes since last release

The complete list of changes is detailed in the ChangeLog file included in the distribution.

The major change though is the use of SableCC instead of JavaCC for the underlying compiler-generator tool.

10. Known limitations

The generated .java classes do not contain accessors for a value-set at a given index in a SEQUENCE/SET [OF]. But the ability to traverse the values of such constructs, using the iterator() method, offers a neat workaround. For example:

    Assuming you have:

    Name ::= RDNSequence
    RDNSequence ::= SEQUENCE OF RelativeDistinguishedName
    RelativeDistinguishedName ::= SET OF AttributeValueAssertion
    AttributeValueAssertion ::= SEQUENCE {
        attributeType AttributeType,
        attributeValue AttributeValue
    }

    Then, with the Java generated class, you can do things like:

    Name name = new Name();
    RelativeDistinguishedName rdn1 = new RelativeDistinguishedName();
    AttributeValueAssertion cn = new AttributeValueAssertion();
    cn.setAttributeType(new AttributeType(ID_AT_COMMON_NAME_OID));
    cn.setAttributeValue(new AttributeValue(FORGE));
    rdn1.iterator().add(cn);
    name.iterator().add(rdn1);
Translation of ASN.1 names to Java identifiers: Currently the code generator uses the ASN.1 names as is; i.e. the code generator does not apply any transformation rule on ASN.1 names to obtain a valid Java identifier. This may cause compilation problems if/when the ASN.1 name is not a well-formed Java identifier, since ASN.1 names may contain invalid (from the Java languages specifications view point) characters.
Not enough documentation.

11. Roadmap

Go Beta with the next release unless major problems with the design become apparent.
Add support for more ASN.1 constructs: REAL, etc...
Better handling of ANY.
May be add BER encoder and decoder --everybody wants them, but nobody is willing to write them!

Contact

The maintainer of this project is Raif S. Naffah.