1asn1ct(3) Erlang Module Definition asn1ct(3)
2
6 asn1ct - ASN.1 compiler and compile-time support functions
7
9 The ASN.1 compiler takes an ASN.1 module as input and generates a cor‐
10 responding Erlang module, which can encode and decode the specified
11 data types. Alternatively, the compiler takes a specification module
12 specifying all input modules, and generates a module with encode/decode
13 functions. In addition, some generic functions can be used during de‐
14 velopment of applications that handles ASN.1 data (encoded as BER or
15 PER).
16 Note:
18 By default in OTP 17, the representation of the BIT STRING and OCTET
19 STRING types as Erlang terms were changed. BIT STRING values are now
20 Erlang bit strings and OCTET STRING values are binaries. Also, an unde‐
21 coded open type is now wrapped in an asn1_OPENTYPE tuple. For details,
22 see BIT STRING, OCTET STRING, and ASN.1 Information Objects in the
23 User's Guide.
24 To revert to the old representation of the types, use option legacy_er‐
26 lang_types.
27 Note:
30 In OTP R16, the options were simplified. The back end is chosen using
31 one of the options ber, per, uper or jer. Options optimize, nif, and
32 driver options are no longer necessary (and the ASN.1 compiler gener‐
33 ates a warning if they are used). Options ber_bin, per_bin, and
34 uper_bin options still work, but generates a warning.
35 Another change in OTP R16 is that the generated function encode/2 al‐
37 ways returns a binary. Function encode/2 for the BER back end used to
38 return an iolist.
39
42 compile(Asn1module) -> ok | {error, Reason}
43 compile(Asn1module, Options) -> ok | {error, Reason}
44 Types:
46 Asn1module = atom() | string()
48 Options = [Option| OldOption]
49 Option = ber | per | uper | jer | der | compact_bit_string |
50 legacy_bit_string | legacy_erlang_types | noobj | {n2n, Enum‐
51 TypeName} |{outdir, Dir} | {i, IncludeDir} | asn1config | un‐
52 dec_rest | no_ok_wrapper | {macro_name_prefix, Prefix} |
53 {record_name_prefix, Prefix} | verbose | warnings_as_errors |
54 deterministic
55 OldOption = ber | per
56 Reason = term()
57 Prefix = string()
58 Compiles the ASN.1 module Asn1module and generates an Erlang
60 module Asn1module.erl with encode and decode functions for the
61 types defined in Asn1module. For each ASN.1 value defined in the
62 module, an Erlang function that returns the value in Erlang rep‐
63 resentation is generated.
64 If Asn1module is a filename without extension, first ".asn1" is
66 assumed, then ".asn", and finally ".py" (to be compatible with
67 the old ASN.1 compiler). Asn1module can be a full pathname (rel‐
68 ative or absolute) including filename with (or without) exten‐
69 sion.
70 If it is needed to compile a set of ASN.1 modules into an Erlang
72 file with encode/decode functions, ensure to list all involved
73 files in a configuration file. This configuration file must have
74 a double extension ".set.asn" (".asn" can alternatively be
75 ".asn1" or ".py"). List the input file names within quotation
76 marks (""), one at each row in the file. If the input files are
77 File1.asn, File2.asn, and File3.asn, the configuration file must
78 look as follows:
79 File1.asn
81 File2.asn
82 File3.asn
83 The output files in this case get their names from the configu‐
85 ration file. If the configuration file is named SetOf‐
86 Files.set.asn, the names of the output files are SetOfFiles.hrl,
87 SetOfFiles.erl, and SetOfFiles.asn1db.
88 Sometimes in a system of ASN.1 modules, different default tag
90 modes, for example, AUTOMATIC, IMPLICIT, or EXPLICIT. The multi-
91 file compilation resolves the default tagging as if the modules
92 were compiled separately.
93 Name collisions is another unwanted effect that can occur in
95 multi file-compilation. The compiler solves this problem in one
96 of two ways:
97 * If the definitions are identical, the output module keeps
99 only one definition with the original name.
100 * If the definitions have the same name and differs in the
102 definition, they are renamed. The new names are the defini‐
103 tion name and the original module name concatenated.
104 If a name collision occurs, the compiler reports a "NOTICE: ..."
106 message that tells if a definition was renamed, and the new name
107 that must be used to encode/decode data.
108 Options is a list with options specific for the ASN.1 compiler
110 and options that are applied to the Erlang compiler. The latter
111 are not recognized as ASN.1 specific. The available options are
112 as follows:
113 ber | per | uper | jer:
115 The encoding rule to be used. The supported encoding rules
116 are Basic Encoding Rules (ber), Packed Encoding Rules (per)
117 aligned, PER unaligned (uper) and JSON Encoding Rules (jer).
118 The jer option can be used by itself to generate a module
119 that only supports encoding/decoding to JER or it can be
120 used as a supplementary option to ber, per and uper. In the
121 latter case a module with for both the main encoding rules
122 and JER will be generated. The exported functions for JER
123 will then be jer_encode(Type, Value) and jer_decode(Type,
124 Bytes).
125 The jer encoding rules (ITU-T X.697) are experimental in OTP
127 22. There is support for a subset of the X.697 standard, for
128 example there is no support for:
129 * JER encoding instructions
131 * the REAL type
133 Also note that when using the jer encoding rules the gener‐
135 ated module will get a dependency to an external json compo‐
136 nent. The generated code is currently tested together with:
137 * jsx which currently is the default.
139 * jsone can be chosen instead of jsx by providing the option
141 {d,jsone}.
142 If the encoding rule option is omitted, ber is the default.
144 The generated Erlang module always gets the same name as the
146 ASN.1 module. Therefore, only one encoding rule per ASN.1
147 module can be used at runtime.
148 der:
150 With this option the Distinguished Encoding Rules (der) is
151 chosen. DER is regarded as a specialized variant of the BER
152 encoding rule. Therefore, this option only makes sense to‐
153 gether with option ber. This option sometimes adds sorting
154 and value checks when encoding, which implies a slower en‐
155 coding. The decoding routines are the same as for ber.
156 maps:
158 This option changes the representation of the types SEQUENCE
159 and SET to use maps (instead of records). This option also
160 suppresses the generation of .hrl files.
161 For details, see Section Map representation for SEQUENCE
163 and SET in the User's Guide.
164 compact_bit_string:
166 The BIT STRING type is decoded to "compact notation". This
167 option is not recommended for new code. This option cannot
168 be combined with the option maps.
169 For details, see Section BIT STRING in the User's Guide.
171 This option implies option legacy_erlang_types.
173 legacy_bit_string:
175 The BIT STRING type is decoded to the legacy format, that
176 is, a list of zeroes and ones. This option is not recom‐
177 mended for new code. This option cannot be combined with the
178 option maps.
179 For details, see Section BIT STRING in the User's Guide
181 This option implies option legacy_erlang_types.
183 legacy_erlang_types:
185 Use the same Erlang types to represent BIT STRING and OCTET
186 STRING as in OTP R16.
187 For details, see Section BIT STRING and Section OCTET STRING
189 in the User's Guide.
190 This option is not recommended for new code. This option
192 cannot be combined with the option maps.
193 {n2n, EnumTypeName}:
195 Tells the compiler to generate functions for conversion be‐
196 tween names (as atoms) and numbers and conversely for the
197 specified EnumTypeName. There can be multiple occurrences of
198 this option to specify several type names. The type names
199 must be declared as ENUMERATIONS in the ASN.1 specification.
200 If EnumTypeName does not exist in the ASN.1 specification,
202 the compilation stops with an error code.
203 The generated conversion functions are named name2num_Enum‐
205 TypeName/1 and num2name_EnumTypeName/1.
206 noobj:
208 Do not compile (that is, do not produce object code) the
209 generated .erl file. If this option is omitted, the gener‐
210 ated Erlang module is compiled.
211 {i, IncludeDir}:
213 Adds IncludeDir to the search-path for .asn1db and ASN.1
214 source files. The compiler tries to open an .asn1db file
215 when a module imports definitions from another ASN.1 module.
216 If no .asn1db file is found, the ASN.1 source file is
217 parsed. Several {i, IncludeDir} can be given.
218 {outdir, Dir}:
220 Specifies directory Dir where all generated files are to be
221 placed. If this option is omitted, the files are placed in
222 the current directory.
223 asn1config:
225 When using one of the specialized decodes, exclusive or se‐
226 lective decode, instructions must be given in a configura‐
227 tion file. Option asn1config enables specialized decodes and
228 takes the configuration file in concern. The configuration
229 file has the same name as the ASN.1 specification, but with
230 extension .asn1config.
231 For instructions for exclusive decode, see Section Exclusive
233 Decode in the User's Guide.
234 For instructions for selective decode, see Section Selective
236 Decode in the User's Guide.
237 undec_rest:
239 A buffer that holds a message, being decoded it can also
240 have some following bytes. Those following bytes can now be
241 returned together with the decoded value. If an ASN.1 speci‐
242 fication is compiled with this option, a tuple {ok, Value,
243 Rest} is returned. Rest can be a list or a binary. Earlier
244 versions of the compiler ignored those following bytes.
245 no_ok_wrapper:
247 With this option, the generated encode/2 and decode/2 func‐
248 tions do not wrap a successful return value in an {ok,...}
249 tuple. If any error occurs, an exception will be raised.
250 {macro_name_prefix, Prefix}:
252 All macro names generated by the compiler are prefixed with
253 Prefix. This is useful when multiple protocols that contain
254 macros with identical names are included in a single module.
255 {record_name_prefix, Prefix}:
257 All record names generated by the compiler are prefixed with
258 Prefix. This is useful when multiple protocols that contain
259 records with identical names are included in a single mod‐
260 ule.
261 verbose:
263 Causes more verbose information from the compiler describing
264 what it is doing.
265 warnings_as_errors:
267 Causes warnings to be treated as errors.
268 deterministic:
270 Causes all non-deterministic options to be stripped from the
271 -asn1_info() attribute.
272 Any more option that is applied is passed to the final step when
274 the generated .erl file is compiled.
275 The compiler generates the following files:
277 * Asn1module.hrl (if any SET or SEQUENCE is defined)
279 * Asn1module.erl - Erlang module with encode, decode, and
281 value functions
282 * Asn1module.asn1db - Intermediate format used by the compiler
284 when modules IMPORT definitions from each other.
285 value(Module, Type) -> {ok, Value} | {error, Reason}
287 Types:
289 Module = Type = atom()
291 Value = term()
292 Reason = term()
293 Returns an Erlang term that is an example of a valid Erlang rep‐
295 resentation of a value of the ASN.1 type Type. The value is a
296 random value and subsequent calls to this function will for most
297 types return different values.
298 Note:
300 Currently, the value function has many limitations. Essentially,
301 it will mostly work for old specifications based on the 1997
302 standard for ASN.1, but not for most modern-style applications.
303 Another limitation is that the value function may not work if
304 options that change code generations strategies such as the op‐
305 tions macro_name_prefix and record_name_prefix have been used.
306 test(Module) -> ok | {error, Reason}
309 test(Module, Type | Options) -> ok | {error, Reason}
310 test(Module, Type, Value | Options) -> ok | {error, Reason}
311 Types:
313 Module = Type = atom()
315 Value = term()
316 Options = [{i, IncludeDir}]
317 Reason = term()
318 Performs a test of encode and decode of types in Module. The
320 generated functions are called by this function. This function
321 is useful during test to secure that the generated encode and
322 decode functions as well as the general runtime support work as
323 expected.
324 Note:
326 Currently, the test functions have many limitations. Essen‐
327 tially, they will mostly work for old specifications based on
328 the 1997 standard for ASN.1, but not for most modern-style ap‐
329 plications. Another limitation is that the test functions may
330 not work if options that change code generations strategies such
331 as the options macro_name_prefix and record_name_prefix have
332 been used.
333 * test/1 iterates over all types in Module.
336 * test/2 tests type Type with a random value.
338 * test/3 tests type Type with Value.
340 Schematically, the following occurs for each type in the module:
342 {ok, Value} = asn1ct:value(Module, Type),
344 {ok, Bytes} = Module:encode(Type, Value),
345 {ok, Value} = Module:decode(Type, Bytes).
346 The test functions use the *.asn1db files for all included mod‐
348 ules. If they are located in a different directory than the cur‐
349 rent working directory, use the include option to add paths.
350 This is only needed when automatically generating values. For
351 static values using Value no options are needed.
352Ericsson AB asn1 5.0.21 asn1ct(3)