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.19 by root, Sat Apr 20 14:45:03 2019 UTC vs.
Revision 1.24 by root, Sat Apr 20 14:59:26 2019 UTC

… …
4 4
5=head1 SYNOPSIS 5=head1 SYNOPSIS
6 6
7 use Convert::BER::XS ':all'; 7 use Convert::BER::XS ':all';
8 8
9 my $ber = ber_decode $buf 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, # constructed, 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_INTEGER32, 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, 0, 0, "\x0a\x00\x00\x01" ], # SNMP IpAddress, 10.0.0.1 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_INTEGER32, 0, 6 ], # generic trap
29 [ ASN_UNIVERSAL, ASN_INTEGER32, 0, 1 ], # specific trap 29 [ ASN_UNIVERSAL, ASN_INTEGER32, 0, 1 ], # specific trap
30 [ ASN_APPLICATION, ASN_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 [
35 [ ASN_UNIVERSAL, ASN_OBJECT_IDENTIFIER, 0, "1.3.6.1.4.1.9.9.215.1.1.8.1.2.1" ], 35 [ ASN_UNIVERSAL, ASN_OBJECT_IDENTIFIER, 0, "1.3.6.1.4.1.9.9.215.1.1.8.1.2.1" ],
… …
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
67 my $buf = ber_encode $ber; 67 my $buf = ber_encode $ber, $Convert::BER::XS::SNMP_PROFILE;
68 68
69=head1 DESCRIPTION 69=head1 DESCRIPTION
70 70
71WARNING: Before release 1.0, the API is not considered stable in any way. 71WARNING: Before release 1.0, the API is not considered stable in any way.
72 72
73This module implements a I<very> low level BER/DER en-/decoder. 73This module implements a I<very> low level BER/DER en-/decoder.
74 74
75If is tuned for low memory and high speed, while still maintaining some 75It is tuned for low memory and high speed, while still maintaining some
76level of user-friendlyness. 76level of user-friendlyness.
77 77
78=head2 EXPORT TAGS AND CONSTANTS 78=head2 EXPORT TAGS AND CONSTANTS
79 79
80By default this module doesn't export any symbols, but if you don't want 80By default this module doesn't export any symbols, but if you don't want
81to break your keyboard, editor or eyesigh with extreemly long names, I 81to break your keyboard, editor or eyesight with extremely long names, I
82recommend importing the C<:all> tag. Still, you can selectively import 82recommend importing the C<:all> tag. Still, you can selectively import
83things: 83things.
84 84
85=over 85=over
86 86
87=item :all 87=item C<:all>
88 88
89All of the below. Really. Rcommended for at least first steps, or if you 89All of the below. Really. Recommended for at least first steps, or if you
90don't care about a few kilobytes of wasted memory (and namespace). 90don't care about a few kilobytes of wasted memory (and namespace).
91 91
92=item :const 92=item C<:const>
93 93
94All of the stricly ASN.1-related constants defined by this module, the 94All of the strictly ASN.1-related constants defined by this module, the
95same as C<:const_asn :const_index>. Notably, this does not contain 95same as C<:const_asn :const_index>. Notably, this does not contain
96C<:const_ber_type> and C<:const_snmp>. 96C<:const_ber_type> and C<:const_snmp>.
97 97
98A good set to get everything you need to decode and match BER data would be 98A good set to get everything you need to decode and match BER data would be
99C<:decode :const>. 99C<:decode :const>.
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_CONSTRUCTED 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>, reespectively - 109ASN class values (these are C<0>, C<1>, C<2> and C<3>, respectively -
110exactly thw two topmost bits from the identifdier octet shifted 6 bits to 110exactly thw two topmost bits from the identifier octet shifted 6 bits to
111the right): 111the right):
112 112
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
… …
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 of
173those - for example, you have 32 bit signed integers and 16(!) different 173those - for example, you have 32 bit signed 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.
179 179
… …
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, CONSTRUCTED, DATA]
188
189For example:
190
191 [ASN_UNIVERSAL, ASN_INTEGER32, 0, 177] # the integer 177
192 [ASN_UNIVERSAL, ASN_OCTET_STRING, 0, "john"] # the string "john"
193 [ASN_UNIVERSAL, ASN_OID, 0, "1.3.6.133"] # some OID
194 [ASN_UNIVERSAL, ASN_SEQUENCE, 1, [ [ASN_UNIVERSAL... # a sequence
188 195
189To avoid non-descriptive hardcoded array index numbers, this module 196To avoid non-descriptive hardcoded array index numbers, this module
190defines symbolic constants to access these members: C<BER_CLASS>, 197defines symbolic constants to access these members: C<BER_CLASS>,
191C<BER_TAG>, C<BER_CONSTRUCTED> and C<BER_DATA>. 198C<BER_TAG>, C<BER_CONSTRUCTED> and C<BER_DATA>.
192 199
… …
211specific applications (for example, the SNMP C<Unsigned32> type is in this 218specific applications (for example, the SNMP C<Unsigned32> type is in this
212namespace), a special-purpose context namespace (C<ASN_CONTEXT>, used e.g. 219namespace), a special-purpose context namespace (C<ASN_CONTEXT>, used e.g.
213for C<CHOICE>) and a private namespace (C<ASN_PRIVATE>). 220for C<CHOICE>) and a private namespace (C<ASN_PRIVATE>).
214 221
215The 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
216(partial) interpretation of the data value. For example, right now, SNMP 223(partial) interpretation of the data value. For example, SNMP defines
217application namespace knowledge ix hardcoded into this module, so it 224extra tags in the C<ASN_APPLICATION> namespace, and to take full advantage
218knows 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.
219integers.
220 226
221The most common tags in the C<ASN_UNIVERSAL> namespace are 227The most common tags in the C<ASN_UNIVERSAL> namespace are
222C<ASN_INTEGER32>, C<ASN_BIT_STRING>, C<ASN_NULL>, C<ASN_OCTET_STRING>, 228C<ASN_INTEGER32>, C<ASN_BIT_STRING>, C<ASN_NULL>, C<ASN_OCTET_STRING>,
223C<ASN_OBJECT_IDENTIFIER>, C<ASN_SEQUENCE>, C<ASN_SET> and 229C<ASN_OBJECT_IDENTIFIER>, C<ASN_SEQUENCE>, C<ASN_SET> and
224C<ASN_IA5_STRING>. 230C<ASN_IA5_STRING>.
225 231
226The most common tags in SNMP's C<ASN_APPLICATION> namespace 232The most common tags in SNMP's C<ASN_APPLICATION> namespace are
227are C<SNMP_IPADDRESS>, C<SNMP_COUNTER32>, C<SNMP_UNSIGNED32>, 233C<SNMP_COUNTER32>, C<SNMP_UNSIGNED32>, C<SNMP_TIMETICKS> and
228C<SNMP_TIMETICKS>, C<SNMP_OPAQUE> and C<SNMP_COUNTER64>. 234C<SNMP_COUNTER64>.
229 235
230The I<CONSTRUCTED> flag is really just a boolean - if it is false, the 236The I<CONSTRUCTED> flag is really just a boolean - if it is false,
231the value is "primitive" and contains no subvalues, kind of like a 237the value is "primitive" and contains no subvalues, kind of like a
232non-reference perl scalar. IF it is true, then the value is "constructed" 238non-reference perl scalar. If it is true, then the value is "constructed"
233which just means it contains a list of subvalues which this module will 239which just means it contains a list of subvalues which this module will
234en-/decode as BER tuples themselves. 240en-/decode as BER tuples themselves.
235 241
236The 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 (if
237the value is I<CONSTRUCTED>), some decoded representation of the value, 243the value is I<CONSTRUCTED>), some decoded representation of the value,
… …
246 252
247=head2 DECODING AND ENCODING 253=head2 DECODING AND ENCODING
248 254
249=over 255=over
250 256
251=item $tuple = ber_decoded $bindata 257=item $tuple = ber_decoded $bindata[, $profile]
252 258
253Decodes binary BER data in C<$bindata> and returns the resulting BER 259Decodes binary BER data in C<$bindata> and returns the resulting BER
254tuple. 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
255valid. 261valid.
256 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
257=item $bindata = ber_encode $tuple 271=item $bindata = ber_encode $tuple[, $profile]
258 272
259Encodes the BER tuple into a BER/DER data structure. 273Encodes the BER tuple into a BER/DER data structure. AS with
274Cyber_decode>, an optional profile can be given.
260 275
261=back 276=back
262 277
263=head2 HELPER FUNCTIONS 278=head2 HELPER FUNCTIONS
264 279
265Working with a 4-tuple for every value can be annoying. Or, rather, I<is> 280Working with a 4-tuple for every value can be annoying. Or, rather, I<is>
266annoying. To reduce this a bit, this module defines a number of helper 281annoying. To reduce this a bit, this module defines a number of helper
267functions, both to match BER tuples and to conmstruct BER tuples: 282functions, both to match BER tuples and to construct BER tuples:
268 283
269=head3 MATCH HELPERS 284=head3 MATCH HELPERS
270 285
271Thse functions accept a BER tuple as first argument and either paertially 286These functions accept a BER tuple as first argument and either partially
272or fully match it. They often come in two forms, one which exactly matches 287or fully match it. They often come in two forms, one which exactly matches
273a value, and one which only matches the type and returns the value. 288a value, and one which only matches the type and returns the value.
274 289
275They do check whether valid tuples are passed in and croak otherwise. As 290They do check whether valid tuples are passed in and croak otherwise. As
276a ease-of-use exception, they usually also accept C<undef> instead of a 291a ease-of-use exception, they usually also accept C<undef> instead of a
277tuple reference. in which case they silently fail to match. 292tuple reference, in which case they silently fail to match.
278 293
279=over 294=over
280 295
281=item $bool = ber_is $tuple, $class, $tag, $constructed, $data 296=item $bool = ber_is $tuple, $class, $tag, $constructed, $data
282 297
283This takes a BER C<$tuple> and matches its elements agains the privded 298This takes a BER C<$tuple> and matches its elements against the provided
284values, all of which are optional - values that are either missing or 299values, all of which are optional - values that are either missing or
285C<undef> will be ignored, the others will be matched exactly (e.g. as if 300C<undef> will be ignored, the others will be matched exactly (e.g. as if
286you used C<==> or C<eq> (for C<$data>)). 301you used C<==> or C<eq> (for C<$data>)).
287 302
288Some examples: 303Some examples:

Diff Legend

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