summaryrefslogtreecommitdiffstats
path: root/docbook/wsdg_src/wsdg_asn2wrs.adoc
blob: e7e021ee7ad5e694f3491c303cf18c35216fac3e (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
[#CreatingAsn1Dissectors]

== Creating ASN.1 Dissectors

The `asn2wrs` compiler can be used to create a dissector from an ASN.1 specification of a protocol.
It is a work in progress but has been used to create a number of dissectors.

It supports:

* ITU-T Recommendation https://www.itu.int/rec/T-REC-X.680/en[X.680]
(07/2002), Information technology - Abstract Syntax Notation One
(ASN.1): Specification of basic notation
* ITU-T Recommendation https://www.itu.int/rec/T-REC-X.681/en[X.681]
(07/2002), Information technology - Abstract Syntax Notation One
(ASN.1): Information object specification
* ITU-T Recommendation https://www.itu.int/rec/T-REC-X.682/en[X.682]
(07/2002), Information technology - Abstract Syntax Notation One
(ASN.1): Constraint specification
* ITU-T Recommendation https://www.itu.int/rec/T-REC-X.683/en[X.683]
(07/2002), Information technology - Abstract Syntax Notation One
(ASN.1): Parameterization of ASN.1 specifications

// Limitations: Add text here

It has inbuilt support for:

* ITU-T Recommendation https://www.itu.int/rec/T-REC-X.880/en[X.880]
(07/1994), Information technology - Remote Operations: Concepts, model
and notation

[#AboutASN1]

=== 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
https://www.itu.int/en/ITU-T/asn1/Pages/asn1_project.aspx[the ASN.1 Consortium's web site].

[#Asn1DissectorRequirements]
=== ASN.1 Dissector Requirements

The compiler needs 4 input files: an ASN.1 description of a protocol, a .cnf file, and two template files.
The 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 deprecated as this creates problems when updating protocols.
The H.248 Binary encoding dissector is a good example of a dissector with relatively small changes.

A complete <<SimpleASN1BasedDissector,simple ASN1 UDP-based dissector>> is also available.

[#BuildingAnASN1BasedPlugin]
==== Building An ASN.1-Based Plugin

The usual way to build an ASN.1-based dissector is to put it into the
_epan/dissectors/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 CMakeFile 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 https://gitlab.com/wireshark/wireshark/-/wikis/ASN1_plugin[Building ASN1 Plugins].

[#UnderstandingErrorMessages]
=== Understanding Error Messages

When running asn2wrs, you could get the following errors:

* A LexToken error (`__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.

* A ParseError (`__main__.ParseError: LexToken(SEMICOLON,';',88)`) means that the ';' (SEMICOLON) is not understood. Maybe removing it will work?

[#HandMassagingTheASN1File]
=== Hand-Massaging The ASN.1 File

If a portion of your ASN.1 file is unsupported you can modify it by hand as needed.
However, the preferred way to resolve the issue is to report it on the link:{wireshark-mailing-lists-url}wireshark-dev[wireshark-dev] mailing list or in the issue tracker so that asn2wrs can be improved.

[#CommandLineSyntax]
=== Command Line Syntax

----
ASN.1 to Wireshark dissector compiler

  asn2wrs [-h|?] [-d dbg] [-b] [-p proto] [-c cnf_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)
    -o name       : Output files name core (default is <proto>)
    -O dir        : Output directory for dissector
    -c cnf_file   : Conformance file
    -I path       : Path for conformance file includes
    -e            : Create conformance file for exported types
    -E            : Just create conformance file for exported types
    -S            : Single output for multiple modules
    -s template   : Single file output (template is input file
                    without .c/.h extension)
    -k            : Keep intermediate files though single file output is used
    -L            : Suppress #line directive from .cnf file
    -D dir        : Directory for input_file(s) (default: '.')
    -C            : Add check for SIZE constraints
    -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
----

[#GeneratedFiles]
=== Generated Files

Asn2wrs creates the following intermediate files:

* 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 described in the <<ConformanceFiles,conformance file examples>>.
Some are optional.

[#ASN1StepByStepInstructions]
=== Step By Step Instructions

. Create a directory for your protocol in the _epan/dissectors/asn1_ directory and put
your ASN.1 file there.
. Copy _CMakeLists.txt_ from another ASN.1 dissector and edit it to suit your needs.
. Create a .cnf file either by copying an existing one and editing it or
using the empty example above.
. Create template files either by copying suitable existing ones and
editing them or use the examples above, putting your protocol name in the
appropriate places.
. Add your dissector to _epan/dissectors/asn1/CMakeLists.txt_
. Test generating your dissector by building the _generate_dissector-*proto*_ target.
. Depending on the outcome you may have to edit your .cnf file, ASN.1 file
etc...
. Build Wireshark.

[#HintsForUsingAsn2wrs]
=== Hints For Using Asn2wrs

Asn2wrs does not support all of ASN.1 yet.
This means you might need to modify the ASN.1 definition before it will compile.
This page lists some tips and tricks that might make your life easier.

[#COMPONENTS_OF]
[discrete]
==== COMPONENTS OF

Asn2wrs does not support the COMPONENTS OF directive.
This means that you will have to modify the asn definition to manually
remove all COMPONENTS OF directives. Fortunately this is pretty easy.
COMPONENTS OF is a directive in ASN.1 which include
all specified fields in the referenced SEQUENCE by those fields as if
they had been explicitly specified.

[#ASN1ComponentsOfExample]
[discrete]
==== Example

Assume you have some definition that looks like this:

----
Foo ::= SEQUENCE {
    field_1 INTEGER,
    field_2 INTEGER
}

Bar ::= SEQUENCE {
    COMPONENTS OF Foo,
    field_3 INTEGER
}
----

Since Asn2wrs can not handle COMPONENTS OF you will have to modify the ASN.1 file so that instead Bar
will look like this :

----
Bar ::= SEQUENCE {
    field_1 INTEGER,
    field_2 INTEGER,
    field_3 INTEGER
}
----

That was pretty easy wasn't it?

[#SemicolonCharacters]
[discrete]
==== Semicolon Characters

In some ASN1 you may have semicolon characters like this:

----
PBAddressString ::= SEQUENCE {
    extension INTEGER(1), natureOfAddressIndicator INTEGER, numberingPlanInd INTEGER, digits OCTET STRING (SIZE(0..19))
};
----

You will have to remove the last semicolon character.

[#ASN1Parameters]
[discrete]
==== Parameters

Parameters will have to be replaced too.
Something like this:

----
AChBillingChargingCharacteristics
    {PARAMETERS-BOUND : bound} ::= OCTET STRING (SIZE (minAChBillingChargingLength ..
maxAChBillingChargingLength))
----

Will have to be replaced with the real values of the parameters:

----
AChBillingChargingCharacteristics ::= OCTET STRING (SIZE (5 .. 177))
----

[#ASN1ANYAndParameterizedTypes]
==== ANY And Parameterized Types

Asn2wrs can handle the type ANY but not parameterized types.
Fortunately this is easy to work around with small changes to the ASN file and some conformance file magic.
Assuming you have a construct that looks something like this:

----
AlgorithmIdentifier ::= SEQUENCE {
    algorithm ALGORITHM.&id({SupportedAlgorithms}),
    parameters ALGORITHM.&Type({SupportedAlgorithms}{@algorithm}) OPTIONAL
}
----

Which is essentially a structure that takes two fields, one field being an object identifier and the second field that can be just about anything, depending on what object identifier was used.
Here we just have to rewrite this SEQUENCE slightly so that it looks like this:

----
AlgorithmIdentifier ::= SEQUENCE {
    algorithm OBJECT IDENTIFIER,
    parameters ANY OPTIONAL
}
----

The only thing remaining now is to add the actual code to manage the dissection of this structure.
We do this by using the <<ASN1CnfDirectiveFN_BODY,\#.FN_BODY conformance file directive>>, which will replace the function body of a dissector with the contents that you specify in the conformance file.
For this one we need a string where we store the OID from AlgorithmIdentifier/algorithm so that we can pick it up and act on later from inside the dissector for AlgorithmIdentifier/parameters.
So we have to add something like this:

[source,c]
----
static char algorithm_id[64]; /* 64 chars should be enough? */
----

to the template file.
Then we add the following to the conformance file:

----
#.FN_BODY AlgorithmIdentifier/algorithmId

offset = dissect_ber_object_identifier(false, pinfo, tree, tvb, offset,
    hf_x509af_algorithm_id, algorithm_id);

#.FN_BODY AlgorithmIdentifier/parameters

offset=call_ber_oid_callback(algorithm_id, tvb, offset, pinfo, tree);
----

This example comes from the X509AF dissector. Please see the code there
for more examples on how to do this.

[#TaggedAssignments]
==== Tagged Assignments

There is currently a bug in Asn2wrs that makes it
generate incorrect code for the case when tagged assignments are used.
The bug is two-fold, first the generated code "forgets" to strip of the
actual tag and length, second it fails to specify 'implicit_tag'
properly.

A tagged assignment is something that looks like this example from the
FTAM asn specification:

----
Degree-Of-Overlap ::=
[APPLICATION 30] IMPLICIT INTEGER {
    normal(0), consecutive(1), concurrent(2)
}
----

I.e. an assignment that also specifies a tag value.

Until Asn2wrs is enhanced to handle these constructs you MUST add a workaround for it to the conformance file:

----
#.FN_BODY Degree-Of-Overlap

int8_t class;
bool pc, ind_field;
int32_t tag;
int32_t len1;

/*
 * XXX asn2wrs can not yet handle tagged assignment yes so this
 * is some conformance file magic to work around that bug
 */

offset = get_ber_identifier(tvb, offset, &class, &pc, &tag);
offset = get_ber_length(tree, tvb, offset, &len1, &ind_field);
offset = dissect_ber_integer(true, pinfo, tree, tvb, offset, hf_index, NULL);
----

This tells Asn2wrs to not
autogenerate any code at all for the Degree-Of-Overlap object instead it
should use the code specified here. Note that we
do have to specify the implicit_tag value explicitly and we can NOT use
the parameter passed to the function from the caller (also due to the
bug in Asn2wrs) this is the true parameter in the call to
dissect_ber_integer(). We specify true here since
the definition of Degree-Of-Overlap was using IMPLICIT tags and would
have specified false if it was not.

The code above can be easily cut-n-pasted into the conformance file with
the exception of the last line that actually calls the next dissector
helper (...dissect_ber_integer... in this case).
The easiest way to find out exactly what this
final line should look like in the conformance file; just generate the
dissector first without this workaround and look at what call was
generated. Then put that line in the conformance directive and replace
`implicit_tag` with either true or false depending on whether IMPLICIT
is used or not.

[#UntaggedCHOICEs]
==== Untagged CHOICEs

Asn2wrs cannot handle untagged CHOICEs within either a SET or a SEQUENCE. For example:

----
MessageTransferEnvelope ::= SET {
  ...
  content-type    ContentType,
  ...
}

ContentType ::= CHOICE {
  built-in        BuiltInContentType,
  extended        ExtendedContentType
}

BuiltInContentType ::= [APPLICATION 6]  INTEGER {
  unidentified(0), external(1), interpersonal-messaging-1984(2), interpersonal-messaging-1988(22),
  edi-messaging(35), voice-messaging(40)}

ExtendedContentType ::= OBJECT IDENTIFIER
----

The Asn2wrs SET/SEQUENCE parsing only looks one level
deep into the dissection tree and does not have access to class/tags of
the elements in the CHOICE.

As with COMPONENTS OF, the solution is to expand the CHOICE in-line
within the SET or SEQUENCE, but *make sure* that each element of the
CHOICE is marked as OPTIONAL. For example,

----
MessageTransferEnvelope ::= SET {
  ...
  built-in  BuiltInContentType OPTIONAL,
  extended  ExtendedContentType OPTIONAL
  ...
}
----

This isn't an entirely correct ASN.1 definition, but should allow
successful parsing.

[#ImportedModuleNameConflicts]
==== Imported Module Name Conflicts

When importing a module using <<ASN1CnfDirectiveINCLUDE,++#++.INCLUDE>> in the conformance file, this
may introduce a definition from the module which contradicts the
definition used in the current ASN.1 file. For example, the X.509
Authentication Framework defines Time as

----
Time ::= CHOICE {utcTime          UTCTime,
                 generalizedTime  GeneralizedTime
}
----

whereas X.411 defines Time as

----
Time ::= UTCTime
----

This can lead to failure to decode the ASN.1 as, in the example,
Asn2wrs will be passed the wrong attributes when trying
to decode an X.411 time. In order to solve this
problem, (if you don't want to globally change the conflicting name
within the ASN.1 module), then you must add an appropriate #.TYPE_ATTR
into the conformance file *before* the <<ASN1CnfDirectiveINCLUDE,++#++.INCLUDE>> line. For example

----
#.TYPE_ATTR
Time TYPE = FT_STRING  DISPLAY = BASE_NONE  STRING = NULL BITMASK = 0
----

[#SimpleASN1BasedDissector]
=== Simple ASN.1-Based Dissector

// https://gitlab.com/wireshark/wireshark/-/wikis/uploads/__moin_import__/attachments/ASN1_sample/foo.tar.gz
// all seven files as gzipped foo directory (suitable for unzipping in
// wireshark/asn1 directory)

The following snippets show the different files that make up a dissector for a “FOO” protocol dissector.

.README.txt
----

        FOO protocol dissector
        ----------------------

This trivial dissector is an example for the struggling dissector developer (me included)
of how to create a dissector for a protocol that is encapsulated in UDP packets
for a specific port, and the packet data is ASN1 PER encoded.

The thing that took me a while to figure out was that in order to see my packet
dissected on the detail pane, I had to:
1. Tell the compiler which block in the ASN1 definition is a PDU definition by adding
   FOO-MESSAGE under the #.PDU directive in the foo.cnf file
2. Add a call to dissect_FOO_MESSAGE_PDU() function in the dissect_foo() function in the
   packet-foo-template.c file.

To build and test it:
1. in foo directory, run make
2. run make copy_files
3. add packet-foo.c and packet-foo.h to epan/dissectors/Makefile.common
4. run top level make

CAVEAT: Makefile.nmake was not tested .

You can take it from here :-)

        --00--
----

.foo.asn
----
-- FOO PROTOCOL
--

FOO-PROTOCOL DEFINITIONS AUTOMATIC TAGS ::=
BEGIN

-- General definitions

MessageId       ::= INTEGER (0..65535)
FlowId          ::= INTEGER (0..65535)

MessageData     ::= SEQUENCE {
    name        OCTET STRING(SIZE(10)),
    value       OCTET STRING(SIZE(10))
}

FOO-MESSAGE ::= SEQUENCE {
    messageId           MessageId,
    flowId              FlowId,
    messageData        MessageData
}

END
----

.foo.cnf
----
# foo.cnf
# FOO conformation file

# $Id$

#.MODULE_IMPORT

#.EXPORTS

#.PDU
FOO-MESSAGE

#.NO_EMIT

#.TYPE_RENAME

#.FIELD_RENAME

#.END
----

.packet-foo-template.h
[source,c]
----
/* packet-foo.h
 * Routines for foo packet dissection
 *
 * Wireshark - Network traffic analyzer
 * By Gerald Combs <gerald@wireshark.org>
 * Copyright 1998 Gerald Combs
 *
 * SPDX-License-Identifier: GPL-2.0-or-later
 */

#ifndef PACKET_FOO_H
#define PACKET_FOO_H

#endif  /* PACKET_FOO_H */
----

.packet-foo-template.c
[source,c]
----
/* packet-foo.c
 * Routines for FOO packet dissection
 *
 * Wireshark - Network traffic analyzer
 * By Gerald Combs <gerald@wireshark.org>
 * Copyright 1998 Gerald Combs
 *
 * SPDX-License-Identifier: GPL-2.0-or-later
 */

#include "config.h"

#include <glib.h>
#include <epan/packet.h>
#include <epan/conversation.h>

#include <stdio.h>
#include <string.h>

#include "packet-per.h"
#include "packet-foo.h"

#define PNAME  "FOO Protocol"
#define PSNAME "FOO"
#define PFNAME "foo"
#define FOO_PORT 5001    /* UDP port */
static dissector_handle_t foo_handle=NULL;

void proto_reg_handoff_foo(void);
void proto_register_foo(void);

/* Initialize the protocol and registered fields */
static int proto_foo = -1;
static int global_foo_port = FOO_PORT;

#include "packet-foo-hf.c"

/* Initialize the subtree pointers */
static int ett_foo = -1;

#include "packet-foo-ett.c"

#include "packet-foo-fn.c"

static void
dissect_foo(tvbuff_t *tvb, packet_info *pinfo, proto_tree *tree)
{
        proto_item      *foo_item = NULL;
        proto_tree      *foo_tree = NULL;
        int                     offset = 0;

        /* make entry in the Protocol column on summary display */
        if (check_col(pinfo->cinfo, COL_PROTOCOL))
                col_set_str(pinfo->cinfo, COL_PROTOCOL, PNAME);

    /* create the foo protocol tree */
    if (tree) {
        foo_item = proto_tree_add_item(tree, proto_foo, tvb, 0, -1, ENC_NA);
        foo_tree = proto_item_add_subtree(foo_item, ett_foo);

        dissect_FOO_MESSAGE_PDU(tvb, pinfo, foo_tree);
    }
}
/*--- proto_register_foo -------------------------------------------*/
void proto_register_foo(void) {

  /* List of fields */
  static hf_register_info hf[] = {

#include "packet-foo-hfarr.c"
  };

  /* List of subtrees */
  static int *ett[] = {
                  &ett_foo,
#include "packet-foo-ettarr.c"
  };

  /* Register protocol */
  proto_foo = proto_register_protocol(PNAME, PSNAME, PFNAME);
  /* Register fields and subtrees */
  proto_register_field_array(proto_foo, hf, array_length(hf));
  proto_register_subtree_array(ett, array_length(ett));



}

/*--- proto_reg_handoff_foo ---------------------------------------*/
void
proto_reg_handoff_foo(void)
{
    static bool inited = false;

    if( !inited ) {

        foo_handle = create_dissector_handle(dissect_foo,
                                                     proto_foo);
        dissector_add("udp.port", global_foo_port, foo_handle);

        inited = true;
    }

}
----

.CMakeLists.txt
----
set( PROTOCOL_NAME foo )

set( PROTO_OPT )

set( EXT_ASN_FILE_LIST
)

set( ASN_FILE_LIST
	Foo.asn
)

set( EXTRA_DIST
	${ASN_FILE_LIST}
	packet-${PROTOCOL_NAME}-template.c
	${PROTOCOL_NAME}.cnf
)

set( SRC_FILES
	${EXTRA_DIST}
	${EXT_ASN_FILE_LIST}
)

set( A2W_FLAGS  )

ASN2WRS()
----

[#ConformanceFiles]
=== Conformance (.cnf) Files

The .cnf file tells the compiler what to do with certain things, such as skipping auto generation for some ASN.1 entries.
They can contain the following directives:

#.OPT::
Compiler options.

#.MODULE and <<ASN1CnfDirectiveMODULE_IMPORT,++#++.MODULE_IMPORT>>::
Assign Wireshark protocol name to ASN.1 module name.

<<ASN1CnfDirectiveINCLUDE,++#++.INCLUDE>>::
Include another conformance file.

<<ASN1CnfDirectiveEXPORTS,++#++.EXPORTS>>::
Export type or information object class.

<<ASN1CnfDirectivePDUAndPDU_NEW,++#++.PDU>>, <<ASN1CnfDirectivePDUAndPDU_NEW,++#++.PDU_NEW>>, <<ASN1CnfDirectiveREGISTERAndREGISTER_NEW,++#++.REGISTER>>, <<ASN1CnfDirectiveREGISTERAndREGISTER_NEW,++#++.REGISTER_NEW>>, and #.SYNTAX::
Create PDU functions and register them optionally to dissector table.


#.CLASS::
Declare or define information object class.

#.ASSIGNED_OBJECT_IDENTIFIER::
Declare assigned object identifier.

#.TABLE_HDR, #.TABLE_BODY, and #.TABLE_FTR::
User tables.

#.OMIT_ASSIGNMENT, #.NO_OMIT_ASSGN, #.OMIT_ALL_ASSIGNMENTS, #.OMIT_ASSIGNMENTS_EXCEPT, #.OMIT_ALL_TYPE_ASSIGNMENTS, #.OMIT_TYPE_ASSIGNMENTS_EXCEPT, #.OMIT_ALL_VALUE_ASSIGNMENTS, and #.OMIT_VALUE_ASSIGNMENTS_EXCEPT::
Ignore assignments from ASN.1 source.

<<ASN1CnfDirectiveNO_EMITAndUSER_DEFINED,++#++.NO_EMIT>> and <<ASN1CnfDirectiveNO_EMITAndUSER_DEFINED,++#++.USER_DEFINED>>::
See linked text for info.

#.VIRTUAL_ASSGN, #.SET_TYPE, #.MAKE_ENUM, #.MAKE_DEFINES, and #.ASSIGN_VALUE_TO_TYPE::
Unknown.

#.TYPE_RENAME, #.FIELD_RENAME, and #.TF_RENAME::
Type/field renaming

#.IMPORT_TAG, #.TYPE_ATTR, #.FIELD_ATTR::
Type attributes


#.FN_HDR, <<ASN1CnfDirectiveFN_BODY,++#++.FN_BODY>>, #.FN_FTR, and #.FN_PARS::
Type function modification

<<ASN1CnfDirectiveEND,++#++.END>>::
End of directive

#.END_OF_CNF::
End of conformance file

[#ExampleCnfFile]
==== Example .cnf File

----
#.MODULE IMPORT
InformationFramework x509if

#.INCLUDE ../x509if/x509if_exp.cnf

#.EXPORTS +
ObjectName

#.PDU
ObjectName

#.REGISTER
Certificate B "2.5.4.36" "id-at-userCertificate"

#.SYNTAX
ObjectName [FriendlyName]

#.NO_EMIT ONLY_VALS
# this can be used with: [WITH_VALS|WITHOUT_VALS|ONLY_VALS]
# using NO_EMIT NO_VALS means it won't generate value_string array for it
Type1

#.USER DEFINED
Type1 [WITH_VALS|WITHOUT_VALS|ONLY_VALS]

#.TYPE_RENAME

#.FIELD_RENAME

#.TYPE_ATTR Ss-Code TYPE = FT_UINT16 DISPLAY = BASE_HEX STRINGS = VALS(ssCode_vals)

# This entry will change the hf definition from the auto-generated one for Ss-Code ::= OCTET STRING(SIZE(1))

    { &hf_gsm_map_ss_Code,
        { "ss-Code", "gsm_map.ss_Code",
            FT_BYTES, BASE_HEX, NULL, 0, "", HFILL }},

# to:

    { &hf_gsm_map_ss_Code,
        { "ss-Code", "gsm_map.ss_Code",
            FT_UINT16, BASE_HEX, VALS(ssCode_vals), 0, "", HFILL }},
----

In the proto_abbr-template.c file the corresponding value string must be
inserted. As an example the following would be included in
proto_abbr-template.c to define ssCode_vals:

----
static const value_string ssCode_vals[] = {
   { 0, "ssCodeString 1" },     /* The string for value 0 */
   { 1, "String 2" },           /* String for value 1 */
   { 5, "String for value 5" }, /* Value String 5 */
   { 0, NULL }                  /* Null terminated array */
}
----

Note that the NULL value must be the final entry and that the index values need not be consecutive.

Foo is expressed in different ways depending on where you want to insert your code and the ASN.1 code in question.

* Foo
* Foo/foo
* Foo/_item/foo

For Tagged type use:

----
Foo/_untag

#.FN_HDR Foo
/* This is code to be inserted into the dissector for Foo BEFORE the BER/PER helper is called. */
tvbuff_t *out_tvb;
fragment_data *fd_head;
tvbuff_t *next_tvb = NULL;

#.FN_BODY Foo
/* This here is code to replace the actual call to the helper completely. */
offset = dissect_ber_octet_string(implicit_tag, pinfo, tree, tvb, offset, hf_index, &out_tvb);

/* Putting %(DEFAULT_BODY)s inside #.FN_BODY will insert the original code there. */

#.FN_FTR Foo
/* This is code to be inserted into the dissector for Foo AFTER the ber/per helper has returned called. */
if (foo_reassemble) {
...
}

#.FN_PARS

#.END
----

[#ExamplePacketProtocolTemplateHFile]
==== Example packet-protocol-template.h File

Example template.h file.
Replace all PROTOCOL/protocol references with the name of your protocol.

[source,c]
----
/* packet-protocol.h
 * Routines for Protocol packet dissection
 *
 * $Id$
 *
 * Wireshark - Network traffic analyzer
 * By Gerald Combs <gerald@wireshark.org>
 * Copyright 1998 Gerald Combs
 *
 * SPDX-License-Identifier: GPL-2.0-or-later
 */

#ifndef PACKET_PROTOCOL_H
#define PACKET_PROTOCOL_H

#include "packet-protocol-exp.h"

#endif  /* PACKET_PROTOCOL_H */
----

[#ExamplePacketProtocolTemplateCFile]
==== Example packet-protocol-template.c File

Example template.c file.
Replace all PROTOCOL/protocol references with the name of your protocol.

[source,c]
----
/* packet-protocol.c
 * Routines for PROTOCOL packet dissection
 *
 * $Id$
 *
 * Wireshark - Network traffic analyzer
 * By Gerald Combs <gerald@wireshark.org>
 * Copyright 1998 Gerald Combs
 *
 * SPDX-License-Identifier: GPL-2.0-or-later
 */

#include "config.h"

#include <glib.h>
#include <epan/packet.h>
#include <epan/conversation.h>

#include <stdio.h>
#include <string.h>

#include "packet-ber.h"
#include "packet-protocol.h"

#define PNAME  "This Is The Protocol Name"
#define PSNAME "PROTOCOL"
#define PFNAME "protocol"

/* Initialize the protocol and registered fields */
int proto_protocol = -1;
#include "packet-protocol-hf.c"

/* Initialize the subtree pointers */
#include "packet-protocol-ett.c"

#include "packet-protocol-fn.c"

/*--- proto_register_protocol ----------------------------------------------*/
void proto_register_protocol(void) {

  /* List of fields */
  static hf_register_info hf[] = {
#include "packet-protocol-hfarr.c"
  };

  /* List of subtrees */
  static int *ett[] = {
#include "packet-protocol-ettarr.c"
  };

  /* Register protocol */
  proto_protocol = proto_register_protocol(PNAME, PSNAME, PFNAME);

  /* Register fields and subtrees */
  proto_register_field_array(proto_protocol, hf, array_length(hf));
  proto_register_subtree_array(ett, array_length(ett));

}

/*--- proto_reg_handoff_protocol -------------------------------------------*/
void proto_reg_handoff_protocol(void) {
#include "packet-protocol-dis-tab.c"
}
----

[#ASN1ConformanceFileDirectiveReference]
=== Conformance File Directive Reference

The following directives can be used in conformance (.cnf) files:

[#ASN1CnfDirectiveEND]
==== #.END

Some of the other directives in the Asn2wrs conformance file consists of multiple lines.
The #.END directive is used to terminate such a directive.
All other “#.” directives (except #.INCLUDE) automatically act as an implicit #.END directive which is why you will not see many #.END directives in the conformance files for the dissectors shipped with Wireshark.

[#ASN1CnfDirectiveEXPORTS]
==== #.EXPORTS

This directive in the Asn2wrs conformation file is used to export functions for type decoding from the dissector.

[#ASN1CnfDirectiveEXPORTSSyntax]
===== Syntax

----
#.EXPORTS

TypeName [WITH_VALS|WITHOUT_VALS|ONLY_VALS] [WS_VAR] [NO_PROT_PREFIX]
...
#.END
----

Options:

* WITH_VALS (default): Exports dissection function and value string table if present.
* WITHOUT_VALS: Exports only the dissection function.
* ONLY_VALS: Exports only the value string table.
* WS_VAR and WS_VAR_IMPORT: Used for value string table so as it can be exported from libwireshark.dll.
* NO_PROT_PREFIX: - value string table name does not have protocol prefix

[#ASN1CnfDirectiveEXPORTSExample]
===== Example

----
#.EXPORTS
NonStandardParameter
RasMessage                      WITH_VALS WS_VAR
H323-UU-PDU/h323-message-body   ONLY_VALS WS_VAR
#.END
----

[#ASN1CnfDirectiveFN_BODY]
==== #.FN_BODY

Sometimes, like when we have ANY types, we might want to replace
whatever function body that Asn2wrs generates with code
of our own. This is what this directive allows us to do.

[#ASN1CnfDirectiveFN_BODYExample]
===== Example: ANY

Asn2wrs can handle the type ANY but we have to help it by adding some small changes to the conformance file.
Assuming you have a construct that looks something like this:

----
AlgorithmIdentifier ::= SEQUENCE {
    algorithm OBJECT IDENTIFIER,
    parameters ANY OPTIONAL
}
----

To handle this we need to specify our own function bodies to both the
algorithm and the parameters fields, which we do using the #.FN_BODY
directive.

This particular example also requires us to keep some state between the
two field dissectors, namely the OBJECT IDENTIFIER from algorithm which
specifies what the content of parameters is. For
this one we need a string where we store the oid from
AlgorithmIdentifier/algorithm so that we can pick it up and act on
later from inside the dissector for AlgorithmIdentifier/parameters.
So we have to add:

----
static char algorithm_id[64]; /* 64 chars should be enough? */
----

to the template file as a placeholder to remember which OID we picked
up. Then we add to the conformance file:

----
#.FN_BODY AlgorithmIdentifier/algorithmId
    offset = dissect_ber_object_identifier(false, pinfo, tree, tvb, offset,
        hf_x509af_algorithm_id, algorithm_id);

#.FN_BODY AlgorithmIdentifier/parameters
    offset=call_ber_oid_callback(algorithm_id, tvb, offset, pinfo, tree);
----

The dissector body we specified for AlgorithmIdentifier/algorithmId
here stores the retrieved OID inside the variable algorithm_id we
specified. +
When we later come to the dissector for
AlgorithmIdentifier/parameters we pick this OID up from the static
variable and just pass it on to the ber/oid dissector helper. +
 +

This example comes from the X509AF dissector. Please see the code there
for more examples on how to do this.



[#ASN1CnfDirectiveMODULE_IMPORTAndINCLUDE]
==== #.MODULE_IMPORT And #.INCLUDE

These directive in the Asn2wrs conformation file are used to manage references to external type definitions, i.e. IMPORTS.
The examples below are all from the X.509 Authentication Framework (x509af) dissector source code in Wireshark.

[#ASN1CnfDirectiveMODULE_IMPORTAndINCLUDEExample]
===== Example ASN

This is an example from the X509AF dissector which amongst other things
imports definitions from X.509 InformationFramework:

----
IMPORTS
    Name, ATTRIBUTE, AttributeType, MATCHING-RULE, Attribute
    FROM InformationFramework informationFramework
----

Which tells the Asn2wrs compiler that the types 'Name',
'ATTRIBUTE', 'AttributeType', 'MATCHING-RULE' and 'Attribute' are
declared inside the external InformationFramework ASN module and
that they are referenced from this module.
In order for Asn2wrs to generate correct code for the
dissection it is necessary to give it some help by telling what kind of
types these are, i.e. are they INTEGERs or SEQUENCEs or something
else.

In order to be able to access these functions from this module it is
important that these types have been declared as #.EXPORTS in the X509
InformationFramework dissector so that they are exported and that we
can link to them.

[#ASN1CnfDirectiveMODULE_IMPORT]
==== #.MODULE_IMPORT

First we need to tell Asn2wrs which protocol name
Wireshark uses for the functions in this external import, so that
Asn2wrs can generate suitable function call signatures to
these external functions. +
We do this by adding a directive to the conformation file :

----
#.MODULE_IMPORT
InformationFramework x509if
----

Where InformationFramework is the ASN name for the module used in
the asn IMPORTS declaration and that x509if is the name we use inside
Wireshark for this protocol. +
This tells Asn2wrs that the function name to call to
dissect Name would be dissect_x509if_Name(...). Without this knowledge
Asn2wrs would not know which function name to generate. +

[#ASN1CnfDirectiveINCLUDE]
==== #.INCLUDE

Second, in order for Asn2wrs to generate correct code it
also needs to know the BER type and class of these types that are
imported, since that would affect how they are to be encoded on the
wire. +
This information about what kind of BER attributes these imported types
have are done using the #.INCLUDE directive in the conformance file:

----
#.INCLUDE ../x509if/x509if_exp.cnf
----

See #.EXPORTS for a description and examples of these types of include
files.

[#ASN1CnfDirectiveNO_EMITAndUSER_DEFINED]
==== #.NO_EMIT And #.USER_DEFINED

These two directives in the conformance file for Asn2wrs
can be used to suppress generation of dissectors
and/or value_strings and similar for a protocol. This is useful when
there are types in the asn definition that either Asn2wrs
can not handle or if we want to handle the dissection ourself inside the
template file to do additional state keeping or things that
Asn2wrs does not know how to manage.

These two directives are very similar. The only
difference between is that #.NO_EMIT will suppress emitting the
dissector for that function and also any value_strings while
#.USER_DEFINED will emit declarations instead of definitions.

I.e. #.USER_DEFINED will emit declarations such
as
`extern const value_string Type_vals[];`
and
`[static] int dissect_Proto_Type(...);`

Use #.NO_EMIT if you dont need to call this function at all from anywhere (except from the template itself) and use #.USER_DEFINED is better if you implement the function inside the template but still want to allow it to be called from other places.
// (need much better explanation here)

[#ASN1CnfDirectiveNO_EMITSyntax]
===== Syntax

----
#.USER_DEFINED
TypeName [WITH_VALS|WITHOUT_VALS|ONLY_VALS]
...
#.END
----

----
#.NO_EMIT
TypeName [WITH_VALS|WITHOUT_VALS|ONLY_VALS]
...
#.END
----

Options:

* WITH_VALS (default): Both dissection function and value string table are user defined and not emitted.
* WITHOUT_VALS: Only dissection function is user defined and not emitted.
* ONLY_VALS: Only value string table is user defined and not emitted.

[#ASN1CnfDirectivePDUAndPDU_NEW]
==== #.PDU and #.PDU_NEW

This directive in the Asn2wrs conformation file will
generate a wrapper function around an object dissector.
This is useful if there is an object inside the
ASN.1 definition that we really want to register as a protocol dissector
or if we want it to have a well known signature.

[#ASN1CnfDirectivePDUFunctionNames]
===== Function Names

The wrapper functions that are created will all be named and have the
following signature:

----
static void dissect_ProtocolName_ObjectName(tvbuff_t *tvb, packet_info *pinfo, proto_tree *tree);
----

Notice that this is exactly the same signature as `dissector_t` which is used by all dissector entry points.

[#ASN1CnfDirectivePDUUsage]
===== Usage

To get Asn2wrs to generate such wrapper functions you
just have to list all objects one by one on the lines following the
#.PDU declaration.

[#ASN1CnfDirectivePDUExample]
===== Example

----
#.PDU
SomeObject
----

This will result in Asn2wrs creating this wrapper function in the packet-foo.c dissector file:

[source,c]
----
static void dissect_SomeObject_PDU(tvbuff_t *tvb, packet_info *pinfo, proto_tree *tree) {
    dissect_foo_SomeObject(false, ...
}
----

This function can then later be called or referenced from the template file or even exported.

[#ASN1CnfDirectiveREGISTERAndREGISTER_NEW]
==== #.REGISTER and #.REGISTER_NEW

This directive in the Asn2wrs conformation file can be used to register a dissector for an object to an OID.
This is very useful for X.509 and similar protocols where structures and objects are frequently associated with an OID.
In particular, some of the structures here encode an OID in a field and then the content in a different field later, and how that field is to be dissected depends on the previously seen OID.

One such example can be seen in the ASN.1 description for X.509/AuthenticationFramework which has a structure defined such as

----
AlgorithmIdentifier ::= SEQUENCE {
    algorithm   ALGORITHM.&id({SupportedAlgorithms}),
    parameters  ALGORITHM.&Type({SupportedAlgorithms}{@algorithm}) OPTIONAL
}
----

Which means that the parameters field in this structure, what this field contains and how it is to be dissected depends entirely upon what OID is stored inside algorithm.
A whole bunch of protocols use similar types of constructs.
While dissection of this particular structure itself currently has to be hand implemented inside the template (see x509af for examples of how this very structure is handled there).
The #.REGISTER option in the conformance file will at least make it easy and painless to attach the actual OID to dissector mappings.

[#ASN1CnfDirectiveREGISTERUsage]
===== Usage

To get Asn2wrs to generate such automatic registration of
OID to dissector mappings just use the #.REGISTER directive in the
conformation file.

[#ASN1CnfDirectiveREGISTERExample]
===== Example

----
#.REGISTER
Certificate  B  "2.5.4.36" "id-at-userCertificate"
----

Which will generate the extra code to make sure that anytime Wireshark needs to dissect the blob associated to the OID "2.5.4.36" it now knows that that is done by calling the subroutine to dissect a Certificate in the current protocol file.
The "id-at-userCertificate" is just a free form text string to make Wireshark print a nice name together with the OID when it presents it in the decode pane. While this can be just about anything you want I would STRONGLY use the name used to this object/oid in the actual ASN.1 definition file.

[#ASN1CnfDirectiveREGISTERIncludeFile]
===== Include File

During the compilation phase Asn2wrs will put all the extra registration code for this in the include file
packet-protocol-dis-tab.c.
Make sure that you include this file from the template file or the registration to an OID will never occur. `#include "packet-protocol-dis-tab.c"` should be included from the proto_reg_handoff_protocol function in the template file.

[#ASN1CnfDirectiveREGISTERSeeAlso]
===== See Also

The various dissectors we have for X.509 such as the X.509AF which contains several examples of how to use this option.
That dissector can also serve as an example on how one would handle structures of the type AlgorithmIdentifier above.
Asn2wrs can NOT handle these types of structures so we need to implement them by hand inside the template.