ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/Convert-BER-XS/XS.pm
(Generate patch)

Comparing Convert-BER-XS/XS.pm (file contents):
Revision 1.23 by root, Sat Apr 20 14:53:29 2019 UTC vs.
Revision 1.30 by root, Sat Apr 20 15:46:57 2019 UTC

… …
8 8
9 my $ber = ber_decode $buf, $Convert::BER::XS::SNMP_PROFILE 9 my $ber = ber_decode $buf, $Convert::BER::XS::SNMP_PROFILE
10 or die "unable to decode SNMP message"; 10 or die "unable to decode SNMP message";
11 11
12 # The above results in a data structure consisting of 12 # The above results in a data structure consisting of
13 # (class, tag, # constructed, data) 13 # (class, tag, flags, data)
14 # tuples. Below is such a message, SNMPv1 trap 14 # tuples. Below is such a message, SNMPv1 trap
15 # with a Cisco mac change notification. 15 # with a Cisco mac change notification.
16 # Did you know that Cisco is in the news almost 16 # Did you know that Cisco is in the news almost
17 # every week because of some backdoor password 17 # every week because of some backdoor password
18 # or other extremely stupid security bug? 18 # or other extremely stupid security bug?
19 19
20 [ ASN_UNIVERSAL, ASN_SEQUENCE, 1, 20 [ ASN_UNIVERSAL, ASN_SEQUENCE, 1,
21 [ 21 [
22 [ ASN_UNIVERSAL, ASN_INTEGER32, 0, 0 ], # snmp version 1 22 [ ASN_UNIVERSAL, ASN_INTEGER, 0, 0 ], # snmp version 1
23 [ ASN_UNIVERSAL, 4, 0, "public" ], # community 23 [ ASN_UNIVERSAL, 4, 0, "public" ], # community
24 [ ASN_CONTEXT, 4, 1, # CHOICE, constructed - trap PDU 24 [ ASN_CONTEXT, 4, 1, # CHOICE, constructed - trap PDU
25 [ 25 [
26 [ ASN_UNIVERSAL, ASN_OBJECT_IDENTIFIER, 0, "1.3.6.1.4.1.9.9.215.2" ], # enterprise oid 26 [ ASN_UNIVERSAL, ASN_OBJECT_IDENTIFIER, 0, "1.3.6.1.4.1.9.9.215.2" ], # enterprise oid
27 [ ASN_APPLICATION, SNMP_IPADDRESS, 0, "10.0.0.1" ], # SNMP IpAddress 27 [ ASN_APPLICATION, SNMP_IPADDRESS, 0, "10.0.0.1" ], # SNMP IpAddress
28 [ ASN_UNIVERSAL, ASN_INTEGER32, 0, 6 ], # generic trap 28 [ ASN_UNIVERSAL, ASN_INTEGER, 0, 6 ], # generic trap
29 [ ASN_UNIVERSAL, ASN_INTEGER32, 0, 1 ], # specific trap 29 [ ASN_UNIVERSAL, ASN_INTEGER, 0, 1 ], # specific trap
30 [ ASN_APPLICATION, SNMP_TIMETICKS, 0, 1817903850 ], # SNMP TimeTicks 30 [ ASN_APPLICATION, SNMP_TIMETICKS, 0, 1817903850 ], # SNMP TimeTicks
31 [ ASN_UNIVERSAL, ASN_SEQUENCE, 1, # the varbindlist 31 [ ASN_UNIVERSAL, ASN_SEQUENCE, 1, # the varbindlist
32 [ 32 [
33 [ ASN_UNIVERSAL, ASN_SEQUENCE, 1, # a single varbind, "key value" pair 33 [ ASN_UNIVERSAL, ASN_SEQUENCE, 1, # a single varbind, "key value" pair
34 [ 34 [
… …
42 # let's decode it a bit with some helper functions 42 # let's decode it a bit with some helper functions
43 43
44 my $msg = ber_is_seq $ber 44 my $msg = ber_is_seq $ber
45 or die "SNMP message does not start with a sequence"; 45 or die "SNMP message does not start with a sequence";
46 46
47 ber_is $msg->[0], ASN_UNIVERSAL, ASN_INTEGER32, 0 47 ber_is $msg->[0], ASN_UNIVERSAL, ASN_INTEGER, 0
48 or die "SNMP message does not start with snmp version\n"; 48 or die "SNMP message does not start with snmp version\n";
49 49
50 # message is SNMP v1 or v2c? 50 # message is SNMP v1 or v2c?
51 if ($msg->[0][BER_DATA] == 0 || $msg->[0][BER_DATA] == 1) { 51 if ($msg->[0][BER_DATA] == 0 || $msg->[0][BER_DATA] == 1) {
52 52
… …
55 my $trap = $msg->[2][BER_DATA]; 55 my $trap = $msg->[2][BER_DATA];
56 56
57 # check whether trap is a cisco mac notification mac changed message 57 # check whether trap is a cisco mac notification mac changed message
58 if ( 58 if (
59 (ber_is_oid $trap->[0], "1.3.6.1.4.1.9.9.215.2") # cmnInterfaceObjects 59 (ber_is_oid $trap->[0], "1.3.6.1.4.1.9.9.215.2") # cmnInterfaceObjects
60 and (ber_is_i32 $trap->[2], 6) 60 and (ber_is_int $trap->[2], 6)
61 and (ber_is_i32 $trap->[3], 1) # mac changed msg 61 and (ber_is_int $trap->[3], 1) # mac changed msg
62 ) { 62 ) {
63 ... and so on 63 ... and so on
64 64
65 # finally, let's encode it again and hope it results in the same bit pattern 65 # finally, let's encode it again and hope it results in the same bit pattern
66 66
… …
100 100
101=item C<:const_index> 101=item C<:const_index>
102 102
103The BER tuple array index constants: 103The BER tuple array index constants:
104 104
105 BER_CLASS BER_TAG BER_CONSTRUCTED BER_DATA 105 BER_CLASS BER_TAG BER_FLAGS BER_DATA
106 106
107=item C<:const_asn> 107=item C<:const_asn>
108 108
109ASN class values (these are C<0>, C<1>, C<2> and C<3>, respectively - 109ASN class values (these are C<0>, C<1>, C<2> and C<3>, respectively -
110exactly thw two topmost bits from the identifier octet shifted 6 bits to 110exactly thw two topmost bits from the identifier octet shifted 6 bits to
… …
113 ASN_UNIVERSAL ASN_APPLICATION ASN_CONTEXT ASN_PRIVATE 113 ASN_UNIVERSAL ASN_APPLICATION ASN_CONTEXT ASN_PRIVATE
114 114
115ASN tag values (some of which are aliases, such as C<ASN_OID>). Their 115ASN tag values (some of which are aliases, such as C<ASN_OID>). Their
116numerical value corresponds exactly to the numbers used in BER/X.690. 116numerical value corresponds exactly to the numbers used in BER/X.690.
117 117
118 ASN_BOOLEAN ASN_INTEGER32 ASN_BIT_STRING ASN_OCTET_STRING ASN_NULL ASN_OBJECT_IDENTIFIER 118 ASN_BOOLEAN ASN_INTEGER ASN_BIT_STRING ASN_OCTET_STRING ASN_NULL ASN_OBJECT_IDENTIFIER
119 ASN_OBJECT_DESCRIPTOR ASN_OID ASN_EXTERNAL ASN_REAL ASN_SEQUENCE ASN_ENUMERATED 119 ASN_OBJECT_DESCRIPTOR ASN_OID ASN_EXTERNAL ASN_REAL ASN_SEQUENCE ASN_ENUMERATED
120 ASN_EMBEDDED_PDV ASN_UTF8_STRING ASN_RELATIVE_OID ASN_SET ASN_NUMERIC_STRING 120 ASN_EMBEDDED_PDV ASN_UTF8_STRING ASN_RELATIVE_OID ASN_SET ASN_NUMERIC_STRING
121 ASN_PRINTABLE_STRING ASN_TELETEX_STRING ASN_T61_STRING ASN_VIDEOTEX_STRING ASN_IA5_STRING 121 ASN_PRINTABLE_STRING ASN_TELETEX_STRING ASN_T61_STRING ASN_VIDEOTEX_STRING ASN_IA5_STRING
122 ASN_ASCII_STRING ASN_UTC_TIME ASN_GENERALIZED_TIME ASN_GRAPHIC_STRING ASN_VISIBLE_STRING 122 ASN_ASCII_STRING ASN_UTC_TIME ASN_GENERALIZED_TIME ASN_GRAPHIC_STRING ASN_VISIBLE_STRING
123 ASN_ISO646_STRING ASN_GENERAL_STRING ASN_UNIVERSAL_STRING ASN_CHARACTER_STRING ASN_BMP_STRING 123 ASN_ISO646_STRING ASN_GENERAL_STRING ASN_UNIVERSAL_STRING ASN_CHARACTER_STRING ASN_BMP_STRING
… …
140 140
141=item C<:decode> 141=item C<:decode>
142 142
143C<ber_decode> and the match helper functions: 143C<ber_decode> and the match helper functions:
144 144
145 ber_decode ber_is ber_is_seq ber_is_i32 ber_is_oid 145 ber_decode ber_is ber_is_seq ber_is_int ber_is_oid
146 146
147=item C<:encode> 147=item C<:encode>
148 148
149C<ber_encode> and the construction helper functions: 149C<ber_encode> and the construction helper functions:
150 150
151 ber_encode ber_i32 151 ber_encode ber_int
152 152
153=back 153=back
154 154
155=head2 ASN.1/BER/DER/... BASICS 155=head2 ASN.1/BER/DER/... BASICS
156 156
157ASN.1 is a strange language that can be used to describe protocols and 157ASN.1 is a strange language that can be used to describe protocols and
158data structures. It supports various mappings to JSON, XML, but most 158data structures. It supports various mappings to JSON, XML, but most
159importantly, to a various binary encodings such as BER, that is the topic 159importantly, to a various binary encodings such as BER, that is the topic
160of this module, and is used in SNMP or LDAP for example. 160of this module, and is used in SNMP, LDAP or X.509 for example.
161 161
162While ASN.1 defines a schema that is useful to interpret encoded data, 162While ASN.1 defines a schema that is useful to interpret encoded data,
163the BER encoding is actually somewhat self-describing: you might not know 163the BER encoding is actually somewhat self-describing: you might not know
164whether something is a string or a number or a sequence or something else, 164whether something is a string or a number or a sequence or something else,
165but you can nevertheless decode the overall structure, even if you end up 165but you can nevertheless decode the overall structure, even if you end up
… …
167 167
168This works because BER values are tagged with a type and a namespace, 168This works because BER values are tagged with a type and a namespace,
169and also have a flag that says whether a value consists of subvalues (is 169and also have a flag that says whether a value consists of subvalues (is
170"constructed") or not (is "primitive"). 170"constructed") or not (is "primitive").
171 171
172Tags are simple integers, and ASN.1 defines a somewhat weird assortment of 172Tags are simple integers, and ASN.1 defines a somewhat weird assortment
173those - for example, you have 32 bit signed integers and 16(!) different 173of those - for example, you have one integers and 16(!) different
174string types, but there is no Unsigned32 type for example. Different 174string types, but there is no Unsigned32 type for example. Different
175applications work around this in different ways, for example, SNMP defines 175applications work around this in different ways, for example, SNMP defines
176application-specific Gauge32, Counter32 and Unsigned32, which are mapped 176application-specific Gauge32, Counter32 and Unsigned32, which are mapped
177to two different tags: you can distinguish between Counter32 and the 177to two different tags: you can distinguish between Counter32 and the
178others, but not between Gause32 and Unsigned32, without the ASN.1 schema. 178others, but not between Gause32 and Unsigned32, without the ASN.1 schema.
… …
182=head2 DECODED BER REPRESENTATION 182=head2 DECODED BER REPRESENTATION
183 183
184This module represents every BER value as a 4-element tuple (actually an 184This module represents every BER value as a 4-element tuple (actually an
185array-reference): 185array-reference):
186 186
187 [CLASS, TAG, CONSTRUCTED, DATA] 187 [CLASS, TAG, FLAGS, DATA]
188 188
189For example: 189For example:
190 190
191 [ASN_UNIVERSAL, ASN_INTEGER32, 0, 177] # the integer 177 191 [ASN_UNIVERSAL, ASN_INTEGER, 0, 177] # the integer 177
192 [ASN_UNIVERSAL, ASN_OCTET_STRING, 0, "john"] # the string "john" 192 [ASN_UNIVERSAL, ASN_OCTET_STRING, 0, "john"] # the string "john"
193 [ASN_UNIVERSAL, ASN_OID, 0, "1.3.6.133"] # some OID 193 [ASN_UNIVERSAL, ASN_OID, 0, "1.3.6.133"] # some OID
194 [ASN_UNIVERSAL, ASN_SEQUENCE, 1, [ [ASN_UNIVERSAL... # a sequencE 194 [ASN_UNIVERSAL, ASN_SEQUENCE, 1, [ [ASN_UNIVERSAL... # a sequence
195 195
196To avoid non-descriptive hardcoded array index numbers, this module 196To avoid non-descriptive hardcoded array index numbers, this module
197defines symbolic constants to access these members: C<BER_CLASS>, 197defines symbolic constants to access these members: C<BER_CLASS>,
198C<BER_TAG>, C<BER_CONSTRUCTED> and C<BER_DATA>. 198C<BER_TAG>, C<BER_FLAGS> and C<BER_DATA>.
199 199
200Also, the first three members are integers with a little caveat: for 200Also, the first three members are integers with a little caveat: for
201performance reasons, these are readonly and shared, so you must not modify 201performance reasons, these are readonly and shared, so you must not modify
202them (increment, assign to them etc.) in any way. You may modify the 202them (increment, assign to them etc.) in any way. You may modify the
203I<DATA> member, and you may re-assign the array itself, e.g.: 203I<DATA> member, and you may re-assign the array itself, e.g.:
204 204
205 $ber = ber_decode $binbuf; 205 $ber = ber_decode $binbuf;
206 206
207 # the following is NOT legal: 207 # the following is NOT legal:
208 $ber->[BER_CLASS] = ASN_PRIVATE; # ERROR, CLASS/TAG/CONSTRUCTED are READ ONLY(!) 208 $ber->[BER_CLASS] = ASN_PRIVATE; # ERROR, CLASS/TAG/FLAGS are READ ONLY(!)
209 209
210 # but all of the following are fine: 210 # but all of the following are fine:
211 $ber->[BER_DATA] = "string"; 211 $ber->[BER_DATA] = "string";
212 $ber->[BER_DATA] = [ASN_UNIVERSAL, ASN_INTEGER32, 0, 123]; 212 $ber->[BER_DATA] = [ASN_UNIVERSAL, ASN_INTEGER, 0, 123];
213 @$ber = (ASN_APPLICATION, SNMP_TIMETICKS, 0, 1000); 213 @$ber = (ASN_APPLICATION, SNMP_TIMETICKS, 0, 1000);
214 214
215I<CLASS> is something like a namespace for I<TAG>s - there is the 215I<CLASS> is something like a namespace for I<TAG>s - there is the
216C<ASN_UNIVERSAL> namespace which defines tags common to all ASN.1 216C<ASN_UNIVERSAL> namespace which defines tags common to all ASN.1
217implementations, the C<ASN_APPLICATION> namespace which defines tags for 217implementations, the C<ASN_APPLICATION> namespace which defines tags for
218specific applications (for example, the SNMP C<Unsigned32> type is in this 218specific applications (for example, the SNMP C<Unsigned32> type is in this
219namespace), a special-purpose context namespace (C<ASN_CONTEXT>, used e.g. 219namespace), a special-purpose context namespace (C<ASN_CONTEXT>, used e.g.
220for C<CHOICE>) and a private namespace (C<ASN_PRIVATE>). 220for C<CHOICE>) and a private namespace (C<ASN_PRIVATE>).
221 221
222The meaning of the I<TAG> depends on the namespace, and defines a 222The meaning of the I<TAG> depends on the namespace, and defines a
223(partial) interpretation of the data value. For example, right now, SNMP 223(partial) interpretation of the data value. For example, SNMP defines
224application namespace knowledge ix hardcoded into this module, so it 224extra tags in the C<ASN_APPLICATION> namespace, and to take full advantage
225knows that SNMP C<Unsigned32> values need to be decoded into actual perl 225of these, you need to tell this module how to handle those via profiles.
226integers.
227 226
228The most common tags in the C<ASN_UNIVERSAL> namespace are 227The most common tags in the C<ASN_UNIVERSAL> namespace are
229C<ASN_INTEGER32>, C<ASN_BIT_STRING>, C<ASN_NULL>, C<ASN_OCTET_STRING>, 228C<ASN_INTEGER>, C<ASN_BIT_STRING>, C<ASN_NULL>, C<ASN_OCTET_STRING>,
230C<ASN_OBJECT_IDENTIFIER>, C<ASN_SEQUENCE>, C<ASN_SET> and 229C<ASN_OBJECT_IDENTIFIER>, C<ASN_SEQUENCE>, C<ASN_SET> and
231C<ASN_IA5_STRING>. 230C<ASN_IA5_STRING>.
232 231
233The most common tags in SNMP's C<ASN_APPLICATION> namespace 232The most common tags in SNMP's C<ASN_APPLICATION> namespace are
234are C<SNMP_IPADDRESS>, C<SNMP_COUNTER32>, C<SNMP_UNSIGNED32>, 233C<SNMP_COUNTER32>, C<SNMP_UNSIGNED32>, C<SNMP_TIMETICKS> and
235C<SNMP_TIMETICKS>, C<SNMP_OPAQUE> and C<SNMP_COUNTER64>. 234C<SNMP_COUNTER64>.
236 235
237The I<CONSTRUCTED> flag is really just a boolean - if it is false, the 236The I<FLAGS> value is really just a boolean at this time (but might
238the value is "primitive" and contains no subvalues, kind of like a 237get extended) - if it is C<0>, the value is "primitive" and contains
239non-reference perl scalar. IF it is true, then the value is "constructed" 238no subvalues, kind of like a non-reference perl scalar. If it is C<1>,
240which just means it contains a list of subvalues which this module will 239then the value is "constructed" which just means it contains a list of
241en-/decode as BER tuples themselves. 240subvalues which this module will en-/decode as BER tuples themselves.
242 241
243The I<DATA> value is either a reference to an array of further tuples (if 242The I<DATA> value is either a reference to an array of further tuples
244the value is I<CONSTRUCTED>), some decoded representation of the value, 243(if the value is I<FLAGS>), some decoded representation of the value, if
245if this module knows how to decode it (e.g. for the integer types above) 244this module knows how to decode it (e.g. for the integer types above) or
246or a binary string with the raw octets if this module doesn't know how to 245a binary string with the raw octets if this module doesn't know how to
247interpret the namespace/tag. 246interpret the namespace/tag.
248 247
249Thus, you can always decode a BER data structure and at worst you get a 248Thus, you can always decode a BER data structure and at worst you get a
250string in place of some nice decoded value. 249string in place of some nice decoded value.
251 250
… …
253 252
254=head2 DECODING AND ENCODING 253=head2 DECODING AND ENCODING
255 254
256=over 255=over
257 256
258=item $tuple = ber_decoded $bindata 257=item $tuple = ber_decoded $bindata[, $profile]
259 258
260Decodes binary BER data in C<$bindata> and returns the resulting BER 259Decodes binary BER data in C<$bindata> and returns the resulting BER
261tuple. Croaks on any decoding error, so the returned C<$tuple> is always 260tuple. Croaks on any decoding error, so the returned C<$tuple> is always
262valid. 261valid.
263 262
263How tags are interpreted is defined by the second argument, which must
264be a C<Convert::BER::XS::Profile> object. If it is missing, the default
265profile will be used (C<$Convert::BER::XS::DEFAULT_PROFILE>).
266
267In addition to rolling your own, this module provides a
268C<$Convert::BER::XS::SNMP_PROFILE> that knows about the additional SNMP
269types.
270
271Example: decode a BER blob using the default profile - SNMP values will be
272decided as raw strings.
273
274 $tuple = ber_decode $data;
275
276Example: as above, but use the provided SNMP profile.
277
278 $tuple = ber_encode $data, $Convert::BER::XS::SNMP_PROFILE;
279
264=item $bindata = ber_encode $tuple 280=item $bindata = ber_encode $tuple[, $profile]
265 281
266Encodes the BER tuple into a BER/DER data structure. 282Encodes the BER tuple into a BER/DER data structure. AS with
283Cyber_decode>, an optional profile can be given.
284
285The encoded data should be both BER and DER ("shortest form") compliant
286unless the input says otherwise (e.g. it uses constructed strings).
267 287
268=back 288=back
269 289
270=head2 HELPER FUNCTIONS 290=head2 HELPER FUNCTIONS
271 291
272Working with a 4-tuple for every value can be annoying. Or, rather, I<is> 292Working with a 4-tuple for every value can be annoying. Or, rather, I<is>
273annoying. To reduce this a bit, this module defines a number of helper 293annoying. To reduce this a bit, this module defines a number of helper
274functions, both to match BER tuples and to conmstruct BER tuples: 294functions, both to match BER tuples and to construct BER tuples:
275 295
276=head3 MATCH HELPERS 296=head3 MATCH HELPERS
277 297
278Thse functions accept a BER tuple as first argument and either paertially 298These functions accept a BER tuple as first argument and either partially
279or fully match it. They often come in two forms, one which exactly matches 299or fully match it. They often come in two forms, one which exactly matches
280a value, and one which only matches the type and returns the value. 300a value, and one which only matches the type and returns the value.
281 301
282They do check whether valid tuples are passed in and croak otherwise. As 302They do check whether valid tuples are passed in and croak otherwise. As
283a ease-of-use exception, they usually also accept C<undef> instead of a 303a ease-of-use exception, they usually also accept C<undef> instead of a
284tuple reference. in which case they silently fail to match. 304tuple reference, in which case they silently fail to match.
285 305
286=over 306=over
287 307
288=item $bool = ber_is $tuple, $class, $tag, $constructed, $data 308=item $bool = ber_is $tuple, $class, $tag, $flags, $data
289 309
290This takes a BER C<$tuple> and matches its elements agains the privded 310This takes a BER C<$tuple> and matches its elements against the provided
291values, all of which are optional - values that are either missing or 311values, all of which are optional - values that are either missing or
292C<undef> will be ignored, the others will be matched exactly (e.g. as if 312C<undef> will be ignored, the others will be matched exactly (e.g. as if
293you used C<==> or C<eq> (for C<$data>)). 313you used C<==> or C<eq> (for C<$data>)).
294 314
295Some examples: 315Some examples:
… …
298 orf die "tuple is not an ASN SEQUENCE"; 318 orf die "tuple is not an ASN SEQUENCE";
299 319
300 ber_is $tuple, ASN_UNIVERSAL, ASN_NULL 320 ber_is $tuple, ASN_UNIVERSAL, ASN_NULL
301 or die "tuple is not an ASN NULL value"; 321 or die "tuple is not an ASN NULL value";
302 322
303 ber_is $tuple, ASN_UNIVERSAL, ASN_INTEGER32, 0, 50 323 ber_is $tuple, ASN_UNIVERSAL, ASN_INTEGER, 0, 50
304 or die "BER integer must be 50"; 324 or die "BER integer must be 50";
305 325
306=item $seq = ber_is_seq $tuple 326=item $seq = ber_is_seq $tuple
307 327
308Returns the sequence members (the array of subvalues) if the C<$tuple> is 328Returns the sequence members (the array of subvalues) if the C<$tuple> is
… …
315 my $snmp = ber_is_seq $ber 335 my $snmp = ber_is_seq $ber
316 or die "SNMP packet invalid: does not start with SEQUENCE"; 336 or die "SNMP packet invalid: does not start with SEQUENCE";
317 337
318 # now we know $snmp is a sequence, so decode the SNMP version 338 # now we know $snmp is a sequence, so decode the SNMP version
319 339
320 my $version = ber_is_i32 $snmp->[0] 340 my $version = ber_is_int $snmp->[0]
321 or die "SNMP packet invalid: does not start with version number"; 341 or die "SNMP packet invalid: does not start with version number";
322 342
323=item $bool = ber_is_i32 $tuple, $i32 343=item $bool = ber_is_int $tuple, $int
324 344
325Returns a true value if the C<$tuple> represents an ASN INTEGER32 with 345Returns a true value if the C<$tuple> represents an ASN INTEGER with
326the value C<$i32>. 346the value C<$int>.
327 347
328=item $i32 = ber_is_i32 $tuple 348=item $int = ber_is_int $tuple
329 349
330Returns true (and extracts the integer value) if the C<$tuple> is an ASN 350Returns true (and extracts the integer value) if the C<$tuple> is an
331INTEGER32. For C<0>, this function returns a special value that is 0 but 351C<ASN_INTEGER>. For C<0>, this function returns a special value that is 0
332true. 352but true.
333 353
334=item $bool = ber_is_oid $tuple, $oid_string 354=item $bool = ber_is_oid $tuple, $oid_string
335 355
336Returns true if the C<$tuple> represents an ASN_OBJECT_IDENTIFIER 356Returns true if the C<$tuple> represents an ASN_OBJECT_IDENTIFIER
337that exactly matches C<$oid_string>. Example: 357that exactly matches C<$oid_string>. Example:
… …
348 368
349=head3 CONSTRUCTION HELPERS 369=head3 CONSTRUCTION HELPERS
350 370
351=over 371=over
352 372
353=item $tuple = ber_i32 $value 373=item $tuple = ber_int $value
354 374
355Constructs a new C<ASN_INTEGER32> tuple. 375Constructs a new C<ASN_INTEGER> tuple.
356 376
357=back 377=back
358 378
359=head2 RELATIONSHIP TO L<Convert::BER> and L<Convert::ASN1> 379=head2 RELATIONSHIP TO L<Convert::BER> and L<Convert::ASN1>
360 380
… …
379 XSLoader::load __PACKAGE__, $VERSION; 399 XSLoader::load __PACKAGE__, $VERSION;
380} 400}
381 401
382our %EXPORT_TAGS = ( 402our %EXPORT_TAGS = (
383 const_index => [qw( 403 const_index => [qw(
384 BER_CLASS BER_TAG BER_CONSTRUCTED BER_DATA 404 BER_CLASS BER_TAG BER_FLAGS BER_DATA
385 )], 405 )],
386 const_asn => [qw( 406 const_asn => [qw(
387 ASN_BOOLEAN ASN_INTEGER32 ASN_BIT_STRING ASN_OCTET_STRING ASN_NULL ASN_OBJECT_IDENTIFIER 407 ASN_BOOLEAN ASN_INTEGER ASN_BIT_STRING ASN_OCTET_STRING ASN_NULL ASN_OBJECT_IDENTIFIER
388 ASN_OBJECT_DESCRIPTOR ASN_OID ASN_EXTERNAL ASN_REAL ASN_SEQUENCE ASN_ENUMERATED 408 ASN_OBJECT_DESCRIPTOR ASN_OID ASN_EXTERNAL ASN_REAL ASN_SEQUENCE ASN_ENUMERATED
389 ASN_EMBEDDED_PDV ASN_UTF8_STRING ASN_RELATIVE_OID ASN_SET ASN_NUMERIC_STRING 409 ASN_EMBEDDED_PDV ASN_UTF8_STRING ASN_RELATIVE_OID ASN_SET ASN_NUMERIC_STRING
390 ASN_PRINTABLE_STRING ASN_TELETEX_STRING ASN_T61_STRING ASN_VIDEOTEX_STRING ASN_IA5_STRING 410 ASN_PRINTABLE_STRING ASN_TELETEX_STRING ASN_T61_STRING ASN_VIDEOTEX_STRING ASN_IA5_STRING
391 ASN_ASCII_STRING ASN_UTC_TIME ASN_GENERALIZED_TIME ASN_GRAPHIC_STRING ASN_VISIBLE_STRING 411 ASN_ASCII_STRING ASN_UTC_TIME ASN_GENERALIZED_TIME ASN_GRAPHIC_STRING ASN_VISIBLE_STRING
392 ASN_ISO646_STRING ASN_GENERAL_STRING ASN_UNIVERSAL_STRING ASN_CHARACTER_STRING ASN_BMP_STRING 412 ASN_ISO646_STRING ASN_GENERAL_STRING ASN_UNIVERSAL_STRING ASN_CHARACTER_STRING ASN_BMP_STRING
… …
401 const_snmp => [qw( 421 const_snmp => [qw(
402 SNMP_IPADDRESS SNMP_COUNTER32 SNMP_UNSIGNED32 SNMP_TIMETICKS SNMP_OPAQUE SNMP_COUNTER64 422 SNMP_IPADDRESS SNMP_COUNTER32 SNMP_UNSIGNED32 SNMP_TIMETICKS SNMP_OPAQUE SNMP_COUNTER64
403 )], 423 )],
404 decode => [qw( 424 decode => [qw(
405 ber_decode 425 ber_decode
406 ber_is ber_is_seq ber_is_i32 ber_is_oid 426 ber_is ber_is_seq ber_is_int ber_is_oid
407 )], 427 )],
408 encode => [qw( 428 encode => [qw(
409 ber_encode 429 ber_encode
410 ber_i32 430 ber_int
411 )], 431 )],
412); 432);
413 433
414our @EXPORT_OK = map @$_, values %EXPORT_TAGS; 434our @EXPORT_OK = map @$_, values %EXPORT_TAGS;
415 435
416$EXPORT_TAGS{all} = \@EXPORT_OK; 436$EXPORT_TAGS{all} = \@EXPORT_OK;
417$EXPORT_TAGS{const} = [map @{ $EXPORT_TAGS{$_} }, qw(const_index const_asn)]; 437$EXPORT_TAGS{const} = [map @{ $EXPORT_TAGS{$_} }, qw(const_index const_asn)];
418use Data::Dump; ddx \%EXPORT_TAGS;
419 438
420=head1 PROFILES 439=head1 PROFILES
421 440
422While any BER data can be correctly encoded and decoded out of the box, it 441While any BER data can be correctly encoded and decoded out of the box, it
423can be inconvenient to have to manually decode some values into a "better" 442can be inconvenient to have to manually decode some values into a "better"
… …
563C<BER_TYPE_BYTES>. When you don't want that but instead prefer a hard 582C<BER_TYPE_BYTES>. When you don't want that but instead prefer a hard
564error for some types, then C<BER_TYPE_CROAK> is for you. 583error for some types, then C<BER_TYPE_CROAK> is for you.
565 584
566=back 585=back
567 586
587=head2 Example Profile
588
589The following creates a profile suitable for SNMP - it's exactly identical
590to the C<$Convert::BER::XS::SNMP_PROFILE> profile.
591
592 our $SNMP_PROFILE = new Convert::BER::XS::Profile;
593
594 $SNMP_PROFILE->set (ASN_APPLICATION, SNMP_IPADDRESS , BER_TYPE_IPADDRESS);
595 $SNMP_PROFILE->set (ASN_APPLICATION, SNMP_COUNTER32 , BER_TYPE_INT);
596 $SNMP_PROFILE->set (ASN_APPLICATION, SNMP_UNSIGNED32, BER_TYPE_INT);
597 $SNMP_PROFILE->set (ASN_APPLICATION, SNMP_TIMETICKS , BER_TYPE_INT);
598 $SNMP_PROFILE->set (ASN_APPLICATION, SNMP_OPAQUE , BER_TYPE_IPADDRESS);
599 $SNMP_PROFILE->set (ASN_APPLICATION, SNMP_COUNTER64 , BER_TYPE_INT);
600
568=cut 601=cut
569 602
570our $DEFAULT_PROFILE = new Convert::BER::XS::Profile; 603our $DEFAULT_PROFILE = new Convert::BER::XS::Profile;
571our $SNMP_PROFILE = new Convert::BER::XS::Profile; 604
605$DEFAULT_PROFILE->_set_default;
572 606
573# additional SNMP application types 607# additional SNMP application types
608our $SNMP_PROFILE = new Convert::BER::XS::Profile;
574$SNMP_PROFILE->set (ASN_APPLICATION, SNMP_IPADDRESS , BER_TYPE_IPADDRESS); 609$SNMP_PROFILE->set (ASN_APPLICATION, SNMP_IPADDRESS , BER_TYPE_IPADDRESS);
575$SNMP_PROFILE->set (ASN_APPLICATION, SNMP_COUNTER32 , BER_TYPE_INT); 610$SNMP_PROFILE->set (ASN_APPLICATION, SNMP_COUNTER32 , BER_TYPE_INT);
576$SNMP_PROFILE->set (ASN_APPLICATION, SNMP_UNSIGNED32, BER_TYPE_INT); 611$SNMP_PROFILE->set (ASN_APPLICATION, SNMP_UNSIGNED32, BER_TYPE_INT);
577$SNMP_PROFILE->set (ASN_APPLICATION, SNMP_TIMETICKS , BER_TYPE_INT); 612$SNMP_PROFILE->set (ASN_APPLICATION, SNMP_TIMETICKS , BER_TYPE_INT);
578$SNMP_PROFILE->set (ASN_APPLICATION, SNMP_OPAQUE , BER_TYPE_IPADDRESS); 613$SNMP_PROFILE->set (ASN_APPLICATION, SNMP_OPAQUE , BER_TYPE_IPADDRESS);
579$SNMP_PROFILE->set (ASN_APPLICATION, SNMP_COUNTER64 , BER_TYPE_INT); 614$SNMP_PROFILE->set (ASN_APPLICATION, SNMP_COUNTER64 , BER_TYPE_INT);
580 615
581$DEFAULT_PROFILE->_set_default;
582
5831; 6161;
584 617
585=head2 LIMITATIONS/NOTES 618=head2 LIMITATIONS/NOTES
586 619
587This module can only en-/decode 64 bit signed and unsigned integers, and 620This module can only en-/decode 64 bit signed and unsigned integers, and
588only when your perl supports those. 621only when your perl supports those.
589 622
590This module does not generally care about ranges, i.e. it will happily 623This module does not generally care about ranges, i.e. it will happily
591de-/encode 64 bit integers into an C<ASN_INTEGER32> value, or a negative 624de-/encode 64 bit integers into an C<ASN_INTEGER> value, or a negative
592number into an C<SNMP_COUNTER64>. 625number into an C<SNMP_COUNTER64>.
593 626
594OBJECT IDENTIFIEERs cannot have unlimited length, although the limit is 627OBJECT IDENTIFIEERs cannot have unlimited length, although the limit is
595much larger than e.g. the one imposed by SNMP or other protocols,a nd is 628much larger than e.g. the one imposed by SNMP or other protocols,a nd is
596about 4kB. 629about 4kB.
597 630
631Indefinite length encoding is not supported.
632
633Constructed strings are decoded just fine, but there should be a way to
634join them for convenience.
635
598REAL values are not supported and will currently croak. 636REAL values are not supported and will currently croak.
599 637
600This module has undergone little to no testing so far. 638This module has undergone little to no testing so far.
601 639
602=head2 ITHREADS SUPPORT 640=head2 ITHREADS SUPPORT

Diff Legend

– Removed lines
+ Added lines
< Changed lines
> Changed lines