forked from erlang/otp
-
Notifications
You must be signed in to change notification settings - Fork 0
/
asn1_ug.xml
1597 lines (1527 loc) · 66.4 KB
/
asn1_ug.xml
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
<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE chapter SYSTEM "chapter.dtd">
<chapter>
<header>
<copyright>
<year>1997</year><year>2013</year>
<holder>Ericsson AB. All Rights Reserved.</holder>
</copyright>
<legalnotice>
The contents of this file are subject to the Erlang Public License,
Version 1.1, (the "License"); you may not use this file except in
compliance with the License. You should have received a copy of the
Erlang Public License along with this software. If not, it can be
retrieved online at http://www.erlang.org/.
Software distributed under the License is distributed on an "AS IS"
basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
the License for the specific language governing rights and limitations
under the License.
</legalnotice>
<title>Asn1</title>
<prepared>Kenneth Lundin</prepared>
<docno></docno>
<date>1999-03-25</date>
<rev>D</rev>
<file>asn1_ug.xml</file>
</header>
<section>
<title>Introduction</title>
<section>
<title>Features</title>
<p>The Asn1 application provides:
</p>
<list type="bulleted">
<item>An ASN.1 compiler for Erlang, which generates encode and
decode functions to be used by Erlang programs sending and
receiving ASN.1 specified data.</item>
<item>Run-time functions used by the generated code.</item>
<item>The supported encoding rules are:
<list>
<item>
Basic Encoding Rules (<em>BER</em>)
</item>
<item>
Distinguished Encoding Rules (<em>DER</em>), a specialized form of BER that is used in security-conscious applications.
</item>
<item>
Packed Encoding Rules (<em>PER</em>) both the aligned and unaligned variant.
</item>
</list>
</item>
</list>
</section>
<section>
<title>Overview</title>
<p>ASN.1 (Abstract Syntax Notation 1) is a formal language for describing data structures to be exchanged between distributed computer systems.
The purpose of ASN.1 is to have
a platform and programming language independent notation to express
types using a
standardized set of rules for the transformation of values of
a defined type, into a stream of bytes. This stream of bytes
can then be sent on a communication channel set up by the
lower layers in the stack of communication protocols e.g.
TCP/IP or encapsulated within UDP packets. This way, two
different applications written in two completely different
programming languages running on different computers with
different internal representation of data can exchange
instances of structured data types (instead of exchanging
bytes or bits). This makes programming faster and easier since no code
has to be written to process the transport format of the
data.
</p>
<p>To write a network application which processes ASN.1 encoded
messages, it is prudent and sometimes essential to have a set
of off-line development tools such as an ASN.1 compiler which
can generate the encode and decode logic for the specific ASN.1
data types. It is also necessary to combine this with some
general language-specific runtime support for ASN.1 encoding and
decoding.
</p>
<p>The ASN.1 compiler must be directed towards a target language
or a set of closely related languages. This manual describes a
compiler which is directed towards the functional language
Erlang. In order to use this compiler, familiarity with the
language Erlang is essential. Therefore, the runtime support for ASN.1 is
also closely related to the language Erlang and
consist of a number of functions, which the
compiler uses. The types in ASN.1 and how to represent
values of those types in Erlang are described in this manual.
</p>
<p>The following document is structured so that the first part describes
how to use ASN.1 compiler, and then there are descriptions of all
the primitive and constructed ASN.1 types and their representation
in Erlang,
</p>
</section>
<section>
<title>Prerequisites</title>
<p>It is assumed that the reader is familiar with the ASN.1 notation
as documented in the standard definition [<cite id="X.680"></cite>] which is
the primary text. It may also be helpful, but not necessary,
to read the standard definitions
[<cite id="X.681"></cite>] [<cite id="X.682"></cite>] [<cite id="X.683"></cite>]
[<cite id="X.690"></cite>] [<cite id="X.691"></cite>]. </p>
<p>A very good book explaining those reference texts is
[<cite id="DUBUISSON"></cite>], free to download at
<url href="http://www.oss.com/asn1/dubuisson.html">http://www.oss.com/asn1/dubuisson.html </url>.
</p>
</section>
<section>
<title>Capability</title>
<p>This application covers all features of ASN.1 up to the 1997
edition of the specification. In the 2002 edition of ASN.1 a number of
new features where introduced of which some are supported while
others are not. For example the
ECN (Encoding Control Notation) and XML notation are still
unsupported. Though, the other features of the 2002 edition are
fully or partly supported as shown below:</p>
<list type="bulleted">
<item>
<p>Decimal notation (e.g., "1.5e3") for REAL values. The
NR1, NR2 and NR3 formats as explained in ISO6093 are
supported.</p>
</item>
<item>
<p>The RELATIVE-OID type for relative object identifiers are
fully supported.</p>
</item>
<item>
<p>The subtype constraint (CONTAINING/ENCODED BY) to
constrain the content of an octet string or a bit string is
parsed when compiling, but no further action is taken. This
constraint is not a PER-visible constraint.</p>
</item>
<item>
<p>The subtype constraint by regular expressions (PATTERN) for character string types is parsed when compiling, but no further action is taken. This constraint is not a PER-visible constraint.</p>
</item>
<item>
<p>Multiple-line comments as in C, <c>/* ... */</c>, are
supported.</p>
</item>
</list>
<p>It should also be added here that the encoding formats
supported are <em>BER</em>, <em>DER</em>, <em>PER aligned
basic</em> variant and <em>PER unaligned basic</em> variant.</p>
</section>
</section>
<section>
<title>Getting Started with Asn1</title>
<section>
<title>A First Example</title>
<p>The following example demonstrates the basic functionality used to run
the Erlang ASN.1 compiler.</p>
<p>First, create a file called <c>People.asn</c> containing the following:</p>
<pre>
People DEFINITIONS IMPLICIT TAGS ::=
BEGIN
EXPORTS Person;
Person ::= [PRIVATE 19] SEQUENCE {
name PrintableString,
location INTEGER {home(0),field(1),roving(2)},
age INTEGER OPTIONAL }
END </pre>
<p>This file (<c>people.asn</c>) must be compiled before it can be
used.
The ASN.1 compiler checks that the syntax is correct and that the
text represents proper ASN.1 code before generating an abstract
syntax tree. The code-generator then uses the abstract syntax
tree in order to generate code.
</p>
<p>The generated Erlang files will be placed in the current directory or
in the directory specified with the <c>{outdir,Dir}</c> option.
The following shows how the compiler
can be called from the Erlang shell:</p>
<pre>
1><input>asn1ct:compile("People", [ber]).</input>
ok
2> </pre>
<p>The <c>verbose</c> option can be given to have information
about the generated files printed:</p>
<pre>
2><input>asn1ct:compile("People", [ber,verbose]).</input>
Erlang ASN.1 compiling "People.asn"
--{generated,"People.asn1db"}--
--{generated,"People.hrl"}--
--{generated,"People.erl"}--
ok
3> </pre>
<p>The ASN.1 module People is now accepted and the abstract syntax tree
is saved in the <c>People.asn1db</c> file, the
generated Erlang code is compiled using the Erlang compiler and
loaded into the Erlang runtime system. Now there is a user interface
for <c>encode/2</c> and <c>decode/2</c> in the module People,
which is invoked by:
<br></br>
<c><![CDATA['People':encode(<Type name>,<Value>),]]></c> <br></br>
or <br></br>
<c><![CDATA['People':decode(<Type name>,<Value>),]]></c></p>
<p>Assume there is a network
application which receives instances of the ASN.1 defined
type Person, modifies and sends them back again:</p>
<code type="none">
receive
{Port,{data,Bytes}} ->
case 'People':decode('Person',Bytes) of
{ok,P} ->
{ok,Answer} = 'People':encode('Person',mk_answer(P)),
Port ! {self(),{command,Answer}};
{error,Reason} ->
exit({error,Reason})
end
end, </code>
<p>In the example above, a series of bytes is received from an
external source and the bytes are then decoded into a valid
Erlang term. This was achieved with the call
<c>'People':decode('Person',Bytes)</c> which returned
an Erlang value of the ASN.1 type <c>Person</c>. Then an answer was
constructed and encoded using
<c>'People':encode('Person',Answer)</c> which takes an
instance of a defined ASN.1 type and transforms it to a
binary according to the BER or PER
encoding-rules.
<br></br>
The encoder and the decoder can also be run from
the shell.</p>
<pre>
2> <input>Rockstar = {'Person',"Some Name",roving,50}.</input>
{'Person',"Some Name",roving,50}
3> <input>{ok,Bin} = 'People':encode('Person',Rockstar).</input>
{ok,<<243,17,19,9,83,111,109,101,32,78,97,109,101,2,1,2,
2,1,50>>}
4> <input>{ok,Person} = 'People':decode('Person',Bin).</input>
{ok,{'Person',"Some Name",roving,50}}
5> </pre>
</section>
<section>
<title>Module dependencies</title>
<p>It is common that asn1 modules import defined types, values and
other entities from another asn1 module.</p>
<p>Earlier versions of the asn1 compiler required that modules that
were imported from had to be compiled before the module that
imported. This caused problems when asn1 modules had circular
dependencies.</p>
<p>Now are referenced modules parsed when the compiler finds an
entity that is imported. There will not be any code generated for
the referenced module. However, the compiled module rely on
that the referenced modules also will be compiled.</p>
</section>
</section>
<section>
<title>The Asn1 Application User Interface</title>
<p>The Asn1 application provides two separate user interfaces:</p>
<list type="bulleted">
<item>
<p>The module <c>asn1ct</c> which provides the compile-time functions
(including the compiler).</p>
</item>
<item>
<p>The module <c>asn1rt_nif</c> which provides the run-time functions
for the ASN.1 decoder for the BER back-end.</p>
</item>
</list>
<p>The reason for the division of the interface into compile-time
and run-time
is that only run-time modules (<c>asn1rt*</c>) need to be loaded in
an embedded system.
</p>
<section>
<title>Compile-time Functions</title>
<p>The ASN.1 compiler can be invoked directly from the command-line
by means of the <c>erlc</c> program. This is convenient when compiling
many ASN.1 files from the command-line or when using Makefiles.
Here are some examples of how the <c>erlc</c> command can be used to invoke the
ASN.1 compiler:</p>
<pre>
erlc Person.asn
erlc -bper Person.asn
erlc -bber ../Example.asn
erlc -o ../asnfiles -I ../asnfiles -I /usr/local/standards/asn1 Person.asn </pre>
<p>The useful options for the ASN.1 compiler are:</p>
<taglist>
<tag><c>-b[ber | per | uper]</c></tag>
<item>
<p>Choice of encoding rules, if omitted <c>ber</c> is the
default.</p>
</item>
<tag><c>-o OutDirectory</c></tag>
<item>
<p>Where to put the generated files, default is the current
directory.</p>
</item>
<tag><c>-I IncludeDir</c></tag>
<item>
<p>Where to search for <c>.asn1db</c> files and asn1
source specs in order to resolve references to other
modules. This option can be repeated many times if there
are several places to search in. The compiler will always
search the current directory first.</p>
</item>
<tag><c>+der</c></tag>
<item>
<p>DER encoding rule. Only when using <c>-ber</c> option.</p>
</item>
<tag><c>+asn1config</c></tag>
<item>
<p>This functionality works together with the flags
<c>ber</c>. It enables the
specialized decodes, see the <seealso marker="asn1_spec">Specialized Decode</seealso> chapter.
</p>
</item>
<tag><c>+undec_rest</c></tag>
<item>
<p>A buffer that holds a message, being decoded may
also have some following bytes. Now it is possible to get
those following bytes returned together with the decoded
value. If an asn1 spec is compiled with this option a tuple
<c>{ok,Value,Rest}</c> is returned. <c>Rest</c> may be a
list or a binary. Earlier versions of the compiler ignored
those following bytes.</p>
</item>
<tag><c>+'Any Erlc Option'</c></tag>
<item>
<p>You may add any option to the Erlang compiler when
compiling the generated Erlang files. Any option
unrecognised by the asn1 compiler will be passed to the
Erlang compiler.</p>
</item>
</taglist>
<p>For a complete description of <c>erlc</c> see Erts Reference Manual.</p>
<p>The compiler and other compile-time functions can also be invoked from
the Erlang shell. Below follows a brief
description of the primary functions, for a
complete description of each function see
<seealso marker="asn1ct">the Asn1 Reference Manual</seealso>, the
<c>asn1ct</c> module.</p>
<p>The compiler is invoked by using <c>asn1ct:compile/1</c> with
default options, or <c>asn1ct:compile/2</c> if explicit options
are given.
Example:</p>
<pre>
asn1ct:compile("H323-MESSAGES.asn1"). </pre>
<p>which equals:</p>
<pre>
asn1ct:compile("H323-MESSAGES.asn1",[ber]). </pre>
<p>If one wants PER encoding:</p>
<pre>
asn1ct:compile("H323-MESSAGES.asn1",[per]). </pre>
<p>The generic encode and decode functions can be invoked like this:</p>
<pre>
asn1ct:encode('H323-MESSAGES','SomeChoiceType',{call,"octetstring"}).
asn1ct:decode('H323-MESSAGES','SomeChoiceType',Bytes). </pre>
<p>Or, preferable like:</p>
<pre>
'H323-MESSAGES':encode('SomeChoiceType',{call,"octetstring"}).
'H323-MESSAGES':decode('SomeChoiceType',Bytes). </pre>
</section>
<section>
<title>Run-time Functions</title>
<p>When an ASN.1 specification is compiled with the <c>ber</c>
option, the module <c>asn1rt_nif</c> module and the NIF library in
<c>asn1/priv_dir</c> will be needed at run-time.</p>
<p>By invoking the function <c>info/0</c> in a generated module, one
gets information about which compiler options were used.</p>
</section>
<section>
<title>Errors</title>
<p>Errors detected at
compile time appear on the screen together with
a line number indicating where in the source file the error
was detected. If no errors are found, an Erlang ASN.1 module will
be created as default.</p>
<p>The run-time encoders and decoders execute within a catch and
returns <c>{ok, Data}</c> or
<c>{error, {asn1, Description}}</c> where
<c>Description</c> is
an Erlang term describing the error. </p>
</section>
</section>
<section>
<marker id="inlineExamples"></marker>
<title>Multi File Compilation</title>
<p>There are various reasons for using a multi file compilation:</p>
<list type="bulleted">
<item>You want to choose name for the generated module by
any reason. Maybe you need to compile the same specs for
different encoding/decoding standards.</item>
<item>You want only one resulting module.</item>
</list>
<p>You need to specify which asn1 specs you will
compile in a module that must have the extension
<c>.set.asn</c>. You chose name of the module and provide the
names of the asn1 specs. For instance, if you have the specs
<c>File1.asn</c>, <c>File2.asn</c> and <c>File3.asn</c> your
module <c>MyModule.set.asn</c> will look like:</p>
<pre>
File1.asn
File2.asn
File3.asn </pre>
<p>If you compile with:</p>
<code type="none">
~> erlc MyModule.set.asn </code>
<p>the result will be one merged module <c>MyModule.erl</c> with
the generated code from the three asn1 specs.
</p>
</section>
<section>
<marker id="ASN1Types"></marker>
<title>The ASN.1 Types</title>
<p>This section describes the ASN.1 types including their
functionality, purpose and how values are assigned in Erlang.
</p>
<p>ASN.1 has both primitive and constructed types:</p>
<p></p>
<table>
<row>
<cell align="left" valign="middle"><em>Primitive types</em></cell>
<cell align="left" valign="middle"><em>Constructed types</em></cell>
</row>
<row>
<cell align="left" valign="middle"><seealso marker="#BOOLEAN">BOOLEAN</seealso></cell>
<cell align="left" valign="middle"><seealso marker="#SEQUENCE">SEQUENCE</seealso></cell>
</row>
<row>
<cell align="left" valign="middle"><seealso marker="#INTEGER">INTEGER</seealso></cell>
<cell align="left" valign="middle"><seealso marker="#SET">SET</seealso></cell>
</row>
<row>
<cell align="left" valign="middle"><seealso marker="#REAL">REAL</seealso></cell>
<cell align="left" valign="middle"><seealso marker="#CHOICE">CHOICE</seealso></cell>
</row>
<row>
<cell align="left" valign="middle"><seealso marker="#NULL">NULL</seealso></cell>
<cell align="left" valign="middle"><seealso marker="#SOF">SET OF and SEQUENCE OF</seealso></cell>
</row>
<row>
<cell align="left" valign="middle"><seealso marker="#ENUMERATED">ENUMERATED</seealso></cell>
<cell align="left" valign="middle"><seealso marker="#ANY">ANY</seealso></cell>
</row>
<row>
<cell align="left" valign="middle"><seealso marker="#BIT STRING">BIT STRING</seealso></cell>
<cell align="left" valign="middle"><seealso marker="#ANY">ANY DEFINED BY</seealso></cell>
</row>
<row>
<cell align="left" valign="middle"><seealso marker="#OCTET STRING">OCTET STRING</seealso></cell>
<cell align="left" valign="middle"><seealso marker="#NegotiationTypes">EXTERNAL</seealso></cell>
</row>
<row>
<cell align="left" valign="middle"><seealso marker="#Character Strings">Character Strings</seealso></cell>
<cell align="left" valign="middle"><seealso marker="#NegotiationTypes">EMBEDDED PDV</seealso></cell>
</row>
<row>
<cell align="left" valign="middle"><seealso marker="#OBJECT IDENTIFIER">OBJECT IDENTIFIER</seealso></cell>
<cell align="left" valign="middle"><seealso marker="#NegotiationTypes">CHARACTER STRING</seealso></cell>
</row>
<row>
<cell align="left" valign="middle"><seealso marker="#Object Descriptor">Object Descriptor</seealso></cell>
<cell align="left" valign="middle"></cell>
</row>
<row>
<cell align="left" valign="middle"><seealso marker="#The TIME types">The TIME types</seealso></cell>
<cell align="left" valign="middle"></cell>
</row>
<tcaption>The supported ASN.1 types</tcaption>
</table>
<marker id="TypeNameValue"></marker>
<note>
<p>Values of each ASN.1 type has its own representation in Erlang
described in the following subsections. Users shall provide
these values for encoding according to the representation, as
in the example below.</p>
</note>
<pre>
Operational ::= BOOLEAN --ASN.1 definition </pre>
<p>In Erlang code it may look like:</p>
<pre>
Val = true,
{ok,Bytes}=asn1rt:encode(MyModule,'Operational',Val), </pre>
<p>Below follows a description of how
values of each type can be represented in Erlang.
</p>
<section>
<marker id="BOOLEAN"></marker>
<title>BOOLEAN</title>
<p>Booleans in ASN.1 express values that can be either
TRUE or FALSE.
The meanings assigned to TRUE or FALSE is beyond the scope
of this text. <br></br>
In ASN.1 it is possible to have:</p>
<pre>
Operational ::= BOOLEAN
</pre>
<p>Assigning a value to the type Operational in Erlang is possible by
using the following Erlang code:</p>
<code type="erl">
Myvar1 = true,
</code>
<p>Thus, in Erlang the atoms <c>true</c> and <c>false</c> are used
to encode a boolean value.</p>
</section>
<section>
<marker id="INTEGER"></marker>
<title>INTEGER</title>
<p>ASN.1 itself specifies indefinitely large integers, and the Erlang
systems with versions 4.3 and higher, support very large
integers, in practice indefinitely large integers.</p>
<p>The concept of sub-typing can be applied to integers as well
as to other ASN.1 types. The details of sub-typing are not
explained here, for further info see [<cite id="X.680"></cite>]. A variety
of syntaxes are allowed when defining a type as an integer:</p>
<pre>
T1 ::= INTEGER
T2 ::= INTEGER (-2..7)
T3 ::= INTEGER (0..MAX)
T4 ::= INTEGER (0<..MAX)
T5 ::= INTEGER (MIN<..-99)
T6 ::= INTEGER {red(0),blue(1),white(2)}
</pre>
<p>The Erlang representation of an ASN.1 INTEGER is an integer or
an atom if a so called <c>Named Number List</c> (see T6 above)
is specified.</p>
<p>Below is an example of Erlang code which assigns values for the
above types: </p>
<pre>
T1value = 0,
T2value = 6,
T6value1 = blue,
T6value2 = 0,
T6value3 = white
</pre>
<p>The Erlang variables above are now bound to valid instances of
ASN.1 defined types. This style of value can be passed directly
to the encoder for transformation into a series of bytes.</p>
<p>The decoder will return an atom if the value corresponds to a
symbol in the Named Number List.</p>
</section>
<section>
<marker id="REAL"></marker>
<title>REAL</title>
<p>In this version reals are not implemented. When they are,
the following
ASN.1 type is used:</p>
<pre>
R1 ::= REAL
</pre>
<p>Can be assigned a value in Erlang as:</p>
<pre>
R1value1 = 2.14,
R1value2 = {256,10,-2},
</pre>
<p>In the last line note that the tuple {256,10,-2} is the real number
2.56 in a special notation, which will encode faster than simply
stating the number as 2.56. The arity three tuple is
<c>{Mantissa,Base,Exponent}</c> i.e. Mantissa * Base^Exponent.</p>
</section>
<section>
<marker id="NULL"></marker>
<title>NULL</title>
<p>Null is suitable in cases where supply and recognition of a value
is important but the actual value is not.</p>
<pre>
Notype ::= NULL
</pre>
<p>The NULL type can be assigned in Erlang:</p>
<pre>
N1 = 'NULL',
</pre>
<p>The actual value is the quoted atom 'NULL'.</p>
</section>
<section>
<marker id="ENUMERATED"></marker>
<title>ENUMERATED</title>
<p>The enumerated type can be used, when the value we wish to
describe, may only take one of a set of predefined values.</p>
<pre>
DaysOfTheWeek ::= ENUMERATED {
sunday(1),monday(2),tuesday(3),
wednesday(4),thursday(5),friday(6),saturday(7) }
</pre>
<p>For example to assign a weekday value in Erlang use the same atom
as in the <c>Enumerations</c> of the type definition:</p>
<pre>
Day1 = saturday,
</pre>
<p>The enumerated type is very similar to an integer type, when
defined with a set of predefined values. An enumerated type
differs from an integer in that it may only have specified
values, whereas an integer can also have any other value.</p>
</section>
<section>
<marker id="BIT STRING"></marker>
<title>BIT STRING</title>
<p>The BIT STRING type can be used to model information which
is made up of arbitrary length series of bits. It is intended
to be used for a selection of flags, not for binary files. <br></br>
In ASN.1 BIT STRING definitions may look like:
</p>
<pre>
Bits1 ::= BIT STRING
Bits2 ::= BIT STRING {foo(0),bar(1),gnu(2),gnome(3),punk(14)}
</pre>
<p>There are two notations available for representation of
BIT STRING values in Erlang and as input to the encode functions.</p>
<list type="ordered">
<item>A bitstring. By default, a BIT STRING with no
symbolic names will be decoded to an Erlang bitstring.</item>
<item>A list of atoms corresponding to atoms in the <c>NamedBitList</c>
in the BIT STRING definition. A BIT STRING with symbolic
names will always be decoded to this format.</item>
</list>
<p>Example:</p>
<pre>
Bits1Val1 = <<0:1,1:1,0:1,1:1,1:1>>,
Bits2Val1 = [gnu,punk],
Bits2Val2 = <<2#1110:4>>,
Bits2Val3 = [bar,gnu,gnome],
</pre>
<p><c>Bits2Val2</c> and <c>Bits2Val3</c> above denote the same value.</p>
<p><c>Bits2Val1</c> is assigned symbolic values. The assignment means
that the bits corresponding to <c>gnu</c> and <c>punk</c> i.e. bits
2 and 14 are set to 1 and the rest set to 0. The symbolic values
appear as a list of values. If a named value appears, which is not
specified in the type definition, a run-time error will occur.</p>
<p>BIT STRINGS may also be sub-typed with, for example, a SIZE
specification:</p>
<pre>
Bits3 ::= BIT STRING (SIZE(0..31)) </pre>
<p>This means that no bit higher than 31 can ever be set.</p>
<section>
<title>Deprecated representations for BIT STRING</title>
<p>In addition to the representations described above, the
following deprecated representations are available if the
specification has been compiled with the
<c>legacy_erlang_types</c> option:</p>
<list type="ordered">
<item>A list of binary digits (0 or 1). This format is
accepted as input to the encode functions, and a BIT STRING
will be decoded to this format if the
<em>legacy_bit_string</em> option has been given.
</item>
<item>As <c>{Unused,Binary}</c> where <c>Unused</c> denotes
how many trailing zero-bits 0 to 7 that are unused in the
least significant byte in <c>Binary</c>. This format is
accepted as input to the encode functions, and a <c>BIT
STRING</c> will be decoded to this format if
<em>compact_bit_string</em> has been given.
</item>
<item>A hexadecimal number (or an integer). This format
should be avoided, since it is easy to misinterpret a BIT
STRING value in this format.
</item>
</list>
</section>
</section>
<section>
<marker id="OCTET STRING"></marker>
<title>OCTET STRING</title>
<p>The OCTET STRING is the simplest of all ASN.1 types. The
OCTET STRING only moves or transfers e.g. binary files or other
unstructured information complying to two rules. Firstly, the
bytes consist of octets and secondly, encoding is not
required.</p>
<p>It is possible to have the following ASN.1 type definitions:</p>
<pre>
O1 ::= OCTET STRING
O2 ::= OCTET STRING (SIZE(28)) </pre>
<p>With the following example assignments in Erlang:</p>
<pre>
O1Val = <<17,13,19,20,0,0,255,254>>,
O2Val = <<"must be exactly 28 chars....">>,</pre>
<p>By default, an OCTET STRING is always represented as
an Erlang binary. If the specification has been compiled with
the <c>legacy_erlang_types</c> option, the encode functions
will accept both lists and binaries, and the decode functions
will decode an OCTET STRING to a list.</p>
</section>
<section>
<marker id="Character Strings"></marker>
<title>Character Strings</title>
<p>ASN.1 supports a wide variety of character sets. The main difference
between OCTET STRINGS and the Character strings is that OCTET
STRINGS have no imposed semantics on the bytes delivered.</p>
<p>However, when using for instance the IA5String (which closely
resembles ASCII) the byte 65 (in decimal
notation) <em>means</em> the character 'A'.
</p>
<p>For example, if a defined type is to be a VideotexString and
an octet is received with the unsigned integer value X, then
the octet should be interpreted as specified in the standard
ITU-T T.100,T.101.
</p>
<p>The ASN.1 to Erlang compiler
will not determine the correct interpretation of each BER
(Basic Encoding Rules) string octet value with different
Character strings. Interpretation of octets is the
responsibility of the application. Therefore, from the BER
string point of view, octets appear to be very similar to
character strings and are compiled in the same way.
</p>
<p>It should be noted that when PER (Packed Encoding Rules) is
used, there is a significant difference in the encoding scheme
between OCTET STRINGS and other strings. The constraints
specified for a type are especially important for PER, where
they affect the encoding.
</p>
<p>Please note that <em>all</em> the Character strings are
supported and it is possible to use the following ASN.1 type
definitions:</p>
<pre>
Digs ::= NumericString (SIZE(1..3))
TextFile ::= IA5String (SIZE(0..64000)) </pre>
<p>and the following Erlang assignments:</p>
<pre>
DigsVal1 = "456",
DigsVal2 = "123",
TextFileVal1 = "abc...xyz...",
TextFileVal2 = [88,76,55,44,99,121 .......... a lot of characters here ....] </pre>
<p>The Erlang representation for "BMPString" and
"UniversalString" is either a list of ASCII values or a list
of quadruples. The quadruple representation associates to the
Unicode standard representation of characters. The ASCII
characters are all represented by quadruples beginning with
three zeros like {0,0,0,65} for the 'A' character. When
decoding a value for these strings the result is a list of
quadruples, or integers when the value is an ASCII character.
The following example shows how it works:</p>
<p>In a file <c>PrimStrings.asn1</c> the type <c>BMP</c> is defined as
<br></br>
<c>BMP ::= BMPString</c> then using BER encoding (<c>ber</c>
option)the input/output format will be:</p>
<pre>
1> <input>{ok,Bytes1} = asn1rt:encode('PrimStrings','BMP',[{0,0,53,53},{0,0,45,56}]).</input>
{ok,[30,4,"55-8"]}
2> <input>asn1rt:decode('PrimStrings','BMP',list_to_binary(Bytes1)).</input>
{ok,[{0,0,53,53},{0,0,45,56}]}
3> <input>{ok,Bytes2} = asn1rt:encode('PrimStrings','BMP',[{0,0,53,53},{0,0,0,65}]).</input>
{ok,[30,4,[53,53,0,65]]}
4> <input>asn1rt:decode('PrimStrings','BMP',list_to_binary(Bytes2)).</input>
{ok,[{0,0,53,53},65]}
5> <input>{ok,Bytes3} = asn1rt:encode('PrimStrings','BMP',"BMP string").</input>
{ok,[30,20,[0,66,0,77,0,80,0,32,0,115,0,116,0,114,0,105,0,110,0,103]]}
6> <input>asn1rt:decode('PrimStrings','BMP',list_to_binary(Bytes3)).</input>
{ok,"BMP string"} </pre>
<p>The UTF8String is represented in Erlang as a list of integers,
where each integer represents the unicode value of one
character. When a value shall be encoded one first has to
transform it to a UTF8 encoded binary, then it can be encoded by
asn1. When decoding the result is a UTF8 encoded binary, which
may be transformed to an integer list. The transformation
functions, <c>utf8_binary_to_list</c> and
<c>utf8_list_to_binary</c>, are in the <c>asn1rt</c> module. In
the example below we assume an asn1 definition <c>UTF ::= UTF8String</c> in a module <c>UTF.asn</c>:</p>
<pre>
1> <input>asn1ct:compile('UTF',[ber]).</input>
Erlang ASN.1 version "1.4.3.3" compiling "UTF.asn"
Compiler Options: [ber]
--{generated,"UTF.asn1db"}--
--{generated,"UTF.erl"}--
ok
2> <input>UTF8Val1 = "hello".</input>
"hello"
3> <input>{ok,UTF8bin1} = asn1rt:utf8_list_to_binary(UTF8Val1).</input>
{ok,<<104,101,108,108,111>>}
4> <input>{ok,B}='UTF':encode('UTF',UTF8bin1).</input>
{ok,[12,
5,
<<104,101,108,108,111>>]}
5> <input>Bin = list_to_binary(B).</input>
<<12,5,104,101,108,108,111>>
6> <input>{ok,UTF8bin1}='UTF':decode('UTF',Bin).</input>
{ok,<<104,101,108,108,111>>}
7> <input>asn1rt:utf8_binary_to_list(UTF8bin1).</input>
{ok,"hello"}
8> <input>UTF8Val2 = [16#00,16#100,16#ffff,16#ffffff].</input>
[0,256,65535,16777215]
9> <input>{ok,UTF8bin2} = asn1rt:utf8_list_to_binary(UTF8Val2).</input>
{ok,<<0,196,128,239,191,191,248,191,191,191,191>>}
10> <input>{ok,B2} = 'UTF':encode('UTF',UTF8bin2).</input>
{ok,[12,
11,
<<0,196,128,239,191,191,248,191,191,191,191>>]}
11> <input>Bin2 = list_to_binary(B2).</input>
<<12,11,0,196,128,239,191,191,248,191,191,191,191>>
12> <input>{ok,UTF8bin2} = 'UTF':decode('UTF',Bin2).</input>
{ok,<<0,196,128,239,191,191,248,191,191,191,191>>}
13> <input>asn1rt:utf8_binary_to_list(UTF8bin2).</input>
{ok,[0,256,65535,16777215]}
14> </pre>
</section>
<section>
<marker id="OBJECT IDENTIFIER"></marker>
<title>OBJECT IDENTIFIER</title>
<p>The OBJECT IDENTIFIER is used whenever a unique identity is required.
An ASN.1 module, a transfer syntax, etc. is identified with an
OBJECT IDENTIFIER. Assume the example below:</p>
<pre>
Oid ::= OBJECT IDENTIFIER
</pre>
<p>Therefore, the example below is a valid Erlang instance of the
type 'Oid'.</p>
<pre>
OidVal1 = {1,2,55},
</pre>
<p>The OBJECT IDENTIFIER value is simply a tuple with the
consecutive values which must be integers.
</p>
<p>The first value is limited to the values 0, 1 or 2 and the
second value must be in the range 0..39 when the first value
is 0 or 1.
</p>
<p>The OBJECT IDENTIFIER is a very important type and it is
widely used within different standards to uniquely identify
various objects. In [<cite id="DUBUISSON"></cite>], there is an
easy-to-understand description of the usage of
OBJECT IDENTIFIER.</p>
<p></p>
</section>
<section>
<marker id="Object Descriptor"></marker>
<title>Object Descriptor</title>
<p>Values of this type can be assigned a value as an ordinary string i.e. <br></br>
"This is the value of an Object descriptor"</p>
</section>
<section>
<marker id="The TIME types"></marker>
<title>The TIME Types</title>
<p>Two different time types are defined within ASN.1, Generalized
Time and UTC (Universal Time Coordinated), both are assigned a
value as an ordinary string within double quotes i.e.
"19820102070533.8".</p>
<p>In case of DER encoding the compiler does not check the validity
of the time values. The DER requirements upon those strings is
regarded as a matter for the application to fulfill.</p>
</section>
<section>
<marker id="SEQUENCE"></marker>
<title>SEQUENCE</title>
<p>The structured types of ASN.1 are constructed from other types
in a manner similar to the concepts of array and struct in C.
<br></br>
A SEQUENCE in ASN.1 is
comparable with a struct in C and a record in Erlang.
A SEQUENCE may be defined as:</p>
<pre>
Pdu ::= SEQUENCE {
a INTEGER,
b REAL,
c OBJECT IDENTIFIER,
d NULL } </pre>
<p>This is a 4-component structure called 'Pdu'. The major format
for representation of SEQUENCE in Erlang is the record format.
For each SEQUENCE and <c>SET</c> in an ASN.1 module an Erlang
record declaration is generated. For <c>Pdu</c> above, a record
like this is defined:</p>
<pre>
-record('Pdu',{a, b, c, d}). </pre>
<p>The record declarations for a module <c>M</c> are placed in a
separate <c>M.hrl</c> file.</p>
<p>Values can be assigned in Erlang as shown below:</p>
<pre>
MyPdu = #'Pdu'{a=22,b=77.99,c={0,1,2,3,4},d='NULL'}. </pre>
<p>The decode functions will return a record as result when decoding
a <c>SEQUENCE</c> or a <c>SET</c>.
<marker id="DEFAULT"></marker>
</p>
<p>A <c>SEQUENCE</c> and a <c>SET</c> may contain a component with a
<c>DEFAULT</c> key word followed by the actual value that is the
default value. In case of BER encoding it is optional to encode the
value if it equals the default value. If the application uses the
atom asn1_DEFAULT as value or if the value is a primitive value
that equals the default value the encoding omits the bytes for
this value, which is more efficient and it results in fever
bytes to send to the receiving application.</p>
<p>For instance, if the following types exists in a file "File.asn":</p>
<pre>
Seq1 ::= SEQUENCE {
a INTEGER DEFAULT 1,
b Seq2 DEFAULT {aa TRUE, bb 15}
}
Seq2 ::= SEQUENCE {
aa BOOLEAN,
bb INTEGER
}
</pre>
<p>Some values and the corresponding encoding in an Erlang terminal
is shown below:</p>
<pre>
1> <input>asn1ct:compile('File').</input>
Erlang ASN.1 version "1.3.2" compiling "File.asn1"
Compiler Options: []
--{generated,"File.asn1db"}--
--{generated,"File.hrl"}--
--{generated,"File.erl"}--
ok
2> <input>'File':encode('Seq1',{'Seq1',asn1_DEFAULT,asn1_DEFAULT}).</input>
{ok,["0",[0],[[],[]]]}
3> <input>lists:flatten(["0",[0],[[],[]]]).</input>
[48,0]
4> <input>'File':encode('Seq1',{'Seq1',1,{'Seq2',true,15}}).</input>
{ok,["0","\\b",[[],["\\241",[6],[[[128],[1],"\\377"],[[129],[1],[15]]]]]]}
5> <input>lists:flatten(["0","\\b",[[],["\\241",[6],[[[128],[1],"\\377"],[[129],[1],[15]]]]]]).</input>
[48,8,161,6,128,1,255,129,1,15]
6> </pre>
<p>The result after command line 3, in the example above,shows that the
encoder omits the encoding of default values when they are specific
by asn1_DEFAULT. Line 5 shows that even primitive values that equals
the default value are detected and not encoded. But the constructed
value of component <c>b</c> in <c>Seq1</c> is not recognized as the
default value. Checking of default values in <c>BER</c> is not done
in case of complex values, because it would be to expensive.
<marker id="DEFAULT DER"></marker>
</p>
<p>But, the DER encoding format has stronger requirements regarding
default values both for SET and SEQUENCE. A more elaborate and time
expensive check of default values will take place. The following is
an example with the same types and values as above but with der
encoding format.</p>
<pre>
1> <input>asn1ct:compile('File',[der]).</input>
Erlang ASN.1 version "1.3.2" compiling "File.asn1"
Compiler Options: [der]
--{generated,"File.asn1db"}--
--{generated,"File.hrl"}--
--{generated,"File.erl"}--
ok
2> <input>'File':encode('Seq1',{'Seq1',asn1_DEFAULT,asn1_DEFAULT}).</input>
{ok,["0",[0],[[],[]]]}
3> <input>lists:flatten(["0",[0],[[],[]]]).</input>
[48,0]
4> <input>'File':encode('Seq1',{'Seq1',1,{'Seq2',true,15}}).</input>
{ok,["0",[0],[[],[]]]}
5> <input>lists:flatten(["0",[0],[[],[]]]).</input>
[48,0]
6>
</pre>
<p>Line 5 shows that even values of constructed types is checked and if
it equals the default value it will not be encoded.</p>
</section>
<section>
<marker id="SET"></marker>
<title>SET</title>
<p>The SET type is an unusual construct and normally the SEQUENCE
type is more appropriate to use. Set is also inefficient compared with SEQUENCE, as the components can be in any order. Hence, it must be possible
to distinguish every component in 'SET', both when
encoding and decoding a value of a type defined to be a SET.
The tags of all components must be different from each other
in order to be easily recognizable.</p>
<p>A SET may be defined as:</p>
<pre>
Pdu2 ::= SET {
a INTEGER,
b BOOLEAN,
c ENUMERATED {on(0),off(1)} } </pre>
<p>A SET is represented as an Erlang record.
For each SEQUENCE and <c>SET</c> in
an ASN.1 module an Erlang record declaration is generated. For
<c>Pdu2</c> above a record is defined like this:</p>
<pre>
-record('Pdu2',{a, b, c}). </pre>
<p>The record declarations for a module <c>M</c> are placed in a