1 Introduction
2 Installation
3 Quick start
4 Command line usage
5 Supported ASN.1 standards
6 License
1 Introduction
**************

ffasn1dump compiles ASN.1 sources to memory and converts messages from
one ASN.1 encoding to another.  The supported encodings are BER/DER,
aligned PER, unaligned PER, XER, OER, JER and GSER (RFC 3641).

Because the XER, JER or GSER encoding are human readable, it also allows
easy editing of ASN.1 messages with a text editor.

ffasn1dump is a free demo of the FFASN1 compiler.  This compiler
generates efficient and small C code to encode or decode ASN.1 messages
in all supported encodings.

2 Installation
**************

No specific installation is needed.  The executable 'ffasn1dump' is self
contained.  On a unix system, you can copy it in '/usr/local/bin' for
example.

3 Quick start
*************

Here are a few examples by using the source 'simpletest.asn' from the
'examples' directory:

  1. Dump the message of type 'ObjectList' defined in 'simpletest.asn'
     from BER (file 'simpletest.der') to GSER (default output format is
     GSER to console, default input format is BER):

          ffasn1dump simpletest.asn ObjectList simpletest.der

  2. Dump the unaligned PER message:

          ffasn1dump -I uper simpletest.asn ObjectList simpletest.uper

  3. Convert the aligned PER message to DER:

          ffasn1dump -I aper -O der simpletest.asn ObjectList simpletest.aper simpletest.der

  4. Just compile the ASN.1 source to check it:

          ffasn1dump simpletest.asn

4 Command line usage
********************

Usage:
     ffasn1dump [options] asn1source [type infile [outfile]]

   - ASN1SOURCE is the ASN.1 source file defining the various message
     types.  If no other parameters are provided, then the ASN.1 source
     is just compiled.  It can be used to check for syntactic or
     semantic errors.

   - TYPE is the ASN.1 type of the converted ASN.1 message.  It can be
     optionally prefixed by an ASN.1 module name (syntax
     'module.identifier').

   - INFILE is the input ASN.1 message

   - OUTFILE is the output ASN.1 message.  If none is provided, it is
     output to the standard output.

Options:
'-h'
     help

'-i FILENAME'
     include additionnal ASN.1 source file(s)

'-I [ber|uper|aper|gser|xer|oer|jer|random]'
     input message format (default=ber).

     If 'random' is used, a valid ASN.1 message with random content is
     generated.  In this case, INFILE is a number used as seed by the
     random generator.

'-O [der|uper|aper|gser|xer|oer|jer]'
     set output message format (default=gser)

'-n'
     disable constraint check.

'-c'
     decode messages embedded in OCTET STRING or BIT STRING with a
     CONTAINING constraint.  It only works when outputting to GSER, XER
     or JER. The embedded message is decoded using the input message
     format specified with '-I'.

5 Supported ASN.1 standards
***************************

ffasn1dump supports the following standards: X.680, X.681, X.682, X.683,
X.690, X.691, X.693, X.696, X.697 and RFC 3641.

The 'ANY' type from the older X.208 ASN.1 specification is also
supported.

Limitations:
   - Only PER-visible constraints are tested (but all constraints are
     correctly compiled).  Table constraints are only used to decode the
     open types.

6 License
*********

ffasn1dump is copyright 2011-2023 Fabrice Bellard.

ffasn1dump is available free of charge, but its redistribution on any
medium needs written consent of the author.

ffasn1dump is available without any express or implied warranty.  In no
event will the author be held liable for any damages arising from the
use of this software.

