yafred/asn1-tool

A java tool to generate Java encoders and decoders from ASN.1 specifications.

ASN.1 Tool

Introduction

This tool compiles ASN.1 specifications into Java source code. You can then use the generated Java objects in your own code to serialize ASN.1 values (encode with Basic Encoding Rules) and deserialize them (decode with BER).

Quick start

Use a web interface to validate and compile your specification, convert data (ASN value to/from BER) and download generated Java code: it's here

Using the compiler

The compiler generates Java classes and encoding/decoding method from an ASN.1 specification.

• Download latest release
• java -jar asn1-compiler.jar
  • -f <input file> ASN.1 specification.
  • -p just print the validated model.
  • -jo <path> generate Java code in the given folder.
  • -jp <package> use this package as a prefix for generated Java code (ASN.1 module names are added to this prefix to get the full package name).
• You can create an alias with alias on Linux or doskey on Windows
• Add asn1-runtime.jar to your classpath and compile the generated Java code

Using the converter

The converter helps testing the classes generated by the compiler. It lets the generated class decode an ASN.1 stream from an input file and encode an ASN.1 stream to an output file.

• Download latest release
• java -cp <path to the generated classes>;asn1-converter.jar com.yafred.asn1.tool.Converter
  • -i <input file> ASN.1 encoded data (BER hexa string or ASN value notation) written by you.
  • -dec type of encoded data in input file (BER or ASN)
  • -o <output file> ASN.1 encoded data (BER hexa string or ASN value notation) written by the converter
  • -enc type of encoded data in output file (BER)
  • -c name of the generated class under test (compiled class must be in the converter classpath)

Example

Write your ASN.1 specification

G-009 DEFINITIONS AUTOMATIC TAGS ::= 
BEGIN 

Flight ::= SEQUENCE {
   origin             IA5String,
   destination        IA5String,
   seats  INTEGER,
   crew-format ENUMERATED { six, eight, ten }
}

END

Validate it

java -jar asn1-compiler.jar -f your_spec.asn -p

G-009 DEFINITIONS AUTOMATIC TAGS ::=
BEGIN

   EXPORTS ALL;
   IMPORTS;

   Flight ::= SEQUENCE {
      origin [0] IMPLICIT IA5String,
      destination [1] IMPLICIT IA5String,
      seats [2] IMPLICIT INTEGER,
      crew-format [3] IMPLICIT ENUMERATED { six(0), eight(1), ten(2) }
   }

END

Generate the java code

java -jar asn1-compiler.jar -f your_spec.asn -jo your_ouput_folder

Integrate the java bindings in your code

Flight obj = new Flight();
obj.setOrigin("Rome");
obj.setDestination("London");
obj.setSeats(Integer.valueOf(250));
obj.setCrewFormat(Flight.CrewFormat.EIGHT);

Add asn1-runtime.jar to your classpath

To compile and execute your code, you will need to add asn1-runtime.jar in your classpath

Use the BER encoders/decoders to serialize/deserialize your objects (binary)

// encode a Flight
ByteArrayOutputStream bufferOut = new ByteArrayOutputStream();
BERWriter berWriter = new BERWriter(bufferOut);
Flight.writePdu(obj, berWriter);

byte[] berEncoded = bufferOut.toByteArray(); 
/*
23 bytes: 30 15 80 04 52 6f 6d 65 81 06 4c 6f 6e 64 6f 6e 82 02 00 fa 83 01 01
T: 30 (CONSTRUCTED_UNIVERSAL_16)
L: 21
 T: 80 (PRIMITIVE_CONTEXT_0)
 L: 4
 V: 52 6f 6d 65
 T: 81 (PRIMITIVE_CONTEXT_1)
 L: 6
 V: 4c 6f 6e 64 6f 6e
 T: 82 (PRIMITIVE_CONTEXT_2)
 L: 2
 V: 00 fa
 T: 83 (PRIMITIVE_CONTEXT_3)
 L: 1
 V: 01
*/

// decode a Flight
ByteArrayInputStream input = new ByteArrayInputStream(berEncoded);
BERReader berReader = new BERReader(input);
Flight obj = Flight.readPdu(berReader);

Use the ASN decoders to serialize/deserialize your objects (text)

String asnValue = "{" + 
		"  origin \"Rome\"," + 
		"  destination \"London\"," + 
		"  seats 250," + 
		"  crew-format eight" + 
		"}";

// decode a Flight ASN value
InputStream inputStream = new ByteArrayInputStream(asnValue.getBytes(StandardCharsets.UTF_8));
ASNValueReader asnValueReader = new ASNValueReader(inputStream);
Flight obj = Flight.readPdu(asnValueReader);

// encode a Flight ASN value
StringWriter stringWriter = new StringWriter(100);
ASNValueWriter asnValueWriter = new ASNValueWriter(new PrintWriter(stringWriter));
Flight.writePdu(obj, asnValueWriter);
System.out.println(asnValueWriter.toString());
/*
{
  origin "Rome"
, destination "London"
, seats 250
, crew-format eight
}
*/

ASN.1 constraints

/*
Flight ::= SEQUENCE {
   origin             IA5String,
   destination        IA5String,
   seats  INTEGER (100..200),
   crew-format ENUMERATED { six, eight, ten }
}
*/
Flight obj = new Flight();
...
try {
   Flight.validate(obj);
}
catch(Exception e) {
   // failed validation
   // no explanation yet
}

Just the beginning ...

• Value range constraint on INTEGER

INTEGER (100..200))

• Value range Size constraint on SET OF and SEQUENCE OF

SEQUENCE (SIZE(0..10)) OF IA5String

Compiler directives

You can put some directives to influence the way code is generated.

Directives are written as ASN.1 comments at the top of the specification file. Their format is:

--> name value

name can be prefixed with the path to a single element in the specification (see example)

As of now only changing INTEGER type mapping is supported. Directive is integerSize

Example

• Specification

--> integerSize 8 // global value. This will be a Long in Java
--> My-Module.Plane.seats.integerSize 2  // this will be a Short in Java
--> My-Module.Plane.unique-id.integerSize huge   // this will be a java.math.BigInteger in Java

My-Module DEFINITIONS AUTOMATIC TAGS ::= 
BEGIN 

Default-Integer ::= INTEGER   -- size 8

Plane ::= SEQUENCE {
   unique-id INTEGER,       -- size huge
   seats INTEGER (0..500)   -- size 2
}

END

• Using the generated code

Plane obj = new Plane();
obj.setUniqueId(new java.math.BigInteger("123456789123456789123456789"));
obj.setSeats(Short.parseShort("100"));