General
The asn2wrs compiler can be used to create a dissector from an ASN.1 specification of a protocol. It is work in progress but has been used to create a number of dissectors.
It supports:
ITU-T Recommendation X.680 (07/2002), Information technology - Abstract Syntax Notation One (ASN.1): Specification of basic notation
ITU-T Recommendation X.681 (07/2002), Information technology - Abstract Syntax Notation One (ASN.1): Information object specification
ITU-T Recommendation X.682 (07/2002), Information technology - Abstract Syntax Notation One (ASN.1): Constraint specification
ITU-T Recommendation X.683 (07/2002), Information technology - Abstract Syntax Notation One (ASN.1): Parameterization of ASN.1 specifications
Limitations: Add text here
Inbuilt support for:
ITU-T Recommendation X.880 (07/1994), Information technology - Remote Operations: Concepts, model and notation
About ASN.1
The most useful first step in writing an ASN.1-based dissector is to learn about ASN.1. There are a number of free resources available to help with this. One collection of such resources is maintained on the ASN.1 Consortium's web site.
How to
The compiler needs 4 input files, an ASN.1 description of a protocol, a .cnf file, and two template files. An ASN.1 specification may have to be edited to work, however work is in progress to at least read all ASN1 specifications. Changing the ASN1 file is being depreciated as this creates problems when updating protocols. The H.248 Binary encoding dissector is a good example of a dissector with relatively small changes (work in progress) http://anonsvn.wireshark.org/viewvc/viewvc.cgi/trunk/asn1/h248/ ... add more here
A complete simple ASN1 UDP-based dissector is available.
Building an ASN.1-based plugin
The usual way to build an ASN.1-based dissector is to put it into the asn1 subtree. This works well and is somewhat simpler than building as a plugin, but there are two reasons one might want to build as a plugin:
- to speed development, since only the plugin needs to be recompiled
- to allow flexibility in deploying an updated plugin, since only the plugin needs to be distributed
Reasons one might not want to build as a plugin:
- the code is somewhat more complex
- the makefile is quite a bit more complex
- building under the asn1 subtree keeps all such dissectors together
If you still think you'd like to build your module as a plugin, see Building ASN1 Plugins.
Understanding error messages
When running asn2wrs, you could get the following errors:
LexToken error An error like this:
__main__.ParseError: LexToken(DOT,'.',71)
means that something is not understood in the ASN1 file, line 71, around the dot (.) - can be the dot itself.
__main__.ParseError: LexToken(SEMICOLON,';',88)
- means that the ';' (SEMICOLON) is not understood. Maybe removing it will work?
Handmassaging the ASN file
This is being depreciated. Instead if something is unsupported then preferred way is to report it on the Wireshark dev-mailng list or in bugzilla so asn2wrs can be updated.
Commandline syntax
asn2wrs [-h|?] [-d dbg] [-b] [-p proto] [-c conform_file] [-e] input_file(s) ...
-h|? : usage
-b : BER (default is PER)
-u : unaligned (default is aligned)
-p proto : protocol name (implies -S)
default is module-name from input_file (renamed by #.MODULE if
present)
-F : create 'field functions'
-T : tagged type support (experimental)
-o name : output files name core (default is <proto>)
-O dir : output directory
-c conform_file : conformation file
-I path : path for conformance file includes
-e : create conformation file for exported types
-S : single output for multiple modules
-s template : single file output (template is input file without .c/.h exten
sion)
-k : keep intermediate files though single file output is used
-L : suppress #line directive from .cnf file
-r prefix : remove the prefix from type names
input_file(s) : input ASN.1 file(s)
-d dbg : debug output, dbg = [l][y][p][s][a][t][c][m][o]
l - lex
y - yacc
p - parsing
s - internal ASN.1 structure
a - list of assignments
t - tables
c - conformance values
m - list of compiled modules with dependency
o - list of output files
Generated files
Intermediate files created:
- packet-proto-ett.c
- packet-proto-ettarr.c
- packet-proto-fn.c
- packet-proto-hf.c
- packet-proto-hfarr.c
- packet-proto-val.h
- packet-proto-exp.h
- packet-proto-table.c
- packet-proto-syn-reg.c
These files should be included in the template file as in the examples(some are optional).
Explanation for .cnf file and template file .cnf file keywords
Step by step instruction
- Create a directory for your protocol in the /asn1 directory and put your asn1 file there.
- Copy makefile.nmake and Makefile from another asn1 dissector and edit the protocol name asn1 filename and the parameters to asn2wrs.py to suite your needs.
- Create an .cnf file either by copying an existing one and edit it or use the empty example above.
- Create template files either by copying suitable existing ones and edit them or use the examples above puting your protocol name in the appropriate places.
- Test generate your dissector by running the makefile in the directory of your dissector.
- Depending on the outcome you may have to edit your .cnf file asn1 file etc...
- to compile run "make copy_files" in the directory of your dissector which will generate the files and copies the generated dissector to /epan/dissectors/
- Add your dissector to makefile.common in the asn1 directory.
- Add the resulting dissector to makefile.common in the /epan/dissectors directory.
- Compile your dissector by running make in the top level directory.
Discussion
sy: Separate the page into two