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.5 by root, Fri Apr 19 19:46:41 2019 UTC vs.
Revision 1.6 by root, Fri Apr 19 20:38:38 2019 UTC

… …
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
10 or die "unable to decode SNMP v1/v2c Message"; 10 or die "unable to decode SNMP message";
11 11
12 # the above results in a data structure consisting of (class, tag, 12 # The above results in a data structure consisting of (class, tag,
13 # constructed, data) tuples. here is such a message, SNMPv1 trap 13 # constructed, data) tuples. Below is such a message, SNMPv1 trap
14 # with a cisoc mac change notification 14 # with a Cisco mac change notification.
15 # Did you know that Cisco is in the news almost every week because
16 # of some backdoor password or other extremely stupid security bug?
15 17
16 [ ASN_UNIVERSAL, ASN_SEQUENCE, 1, 18 [ ASN_UNIVERSAL, ASN_SEQUENCE, 1,
17 [ 19 [
18 [ ASN_UNIVERSAL, ASN_INTEGER32, 0, 0 ], # snmp version 1 20 [ ASN_UNIVERSAL, ASN_INTEGER32, 0, 0 ], # snmp version 1
19 [ ASN_UNIVERSAL, 4, 0, "public" ], # community 21 [ ASN_UNIVERSAL, 4, 0, "public" ], # community
20 [ ASN_CONTEXT, 4, 1, # CHOICE, constructed 22 [ ASN_CONTEXT, 4, 1, # CHOICE, constructed - trap PDU
21 [ 23 [
22 [ ASN_UNIVERSAL, ASN_OBJECT_IDENTIFIER, 0, "1.3.6.1.4.1.9.9.215.2" ], # enterprise oid 24 [ ASN_UNIVERSAL, ASN_OBJECT_IDENTIFIER, 0, "1.3.6.1.4.1.9.9.215.2" ], # enterprise oid
23 [ ASN_APPLICATION, 0, 0, "\x0a\x00\x00\x01" ], # SNMP IpAddress, 10.0.0.1 25 [ ASN_APPLICATION, 0, 0, "\x0a\x00\x00\x01" ], # SNMP IpAddress, 10.0.0.1
24 [ ASN_UNIVERSAL, ASN_INTEGER32, 0, 6 ], # generic trap 26 [ ASN_UNIVERSAL, ASN_INTEGER32, 0, 6 ], # generic trap
25 [ ASN_UNIVERSAL, ASN_INTEGER32, 0, 1 ], # specific trap 27 [ ASN_UNIVERSAL, ASN_INTEGER32, 0, 1 ], # specific trap
… …
104This module represents every BER value as a 4-element tuple (actually an 106This module represents every BER value as a 4-element tuple (actually an
105array-reference): 107array-reference):
106 108
107 [CLASS, TAG, CONSTRUCTED, DATA] 109 [CLASS, TAG, CONSTRUCTED, DATA]
108 110
111To avoid non-descriptive hardcoded array index numbers, this module
112defines symbolic constants to access these members: C<BER_CLASS>,
113C<BER_TAG>, C<BER_CONSTRUCTED> and C<BER_DATA>.
114
115Also, the first three members are integers with a little caveat: for
116performance reasons, these are readonly and shared, so you must not modify
117them (increment, assign to them etc.) in any way. You may modify the
118I<DATA> member, and you may re-assign the array itself, e.g.:
119
120 $ber = ber_decode $binbuf;
121
122 # the following is NOT legal:
123 $ber->[BER_CLASS] = ASN_PRIVATE; # ERROR, readonly(!)
124
125 # but all of the following are fine:
126 $ber->[BER_DATA] = "string";
127 $ber->[BER_DATA] = [ASN_UNIVERSAL, ASN_INTEGER32, 0, 123];
128 @$ber = (ASN_APPLICATION, SNMP_TIMETICKS, 1000);
129
109I<CLASS> is something like a namespace for I<TAG>s - there is the 130I<CLASS> is something like a namespace for I<TAG>s - there is the
110C<ASN_UNIVERSAL> namespace which defines tags common to all ASN.1 131C<ASN_UNIVERSAL> namespace which defines tags common to all ASN.1
111implementations, the C<ASN_APPLICATION> namespace which defines tags for 132implementations, the C<ASN_APPLICATION> namespace which defines tags for
112specific applications (for example, the SNMP C<Unsigned32> type is in this 133specific applications (for example, the SNMP C<Unsigned32> type is in this
113namespace), a special-purpose context namespace (C<ASN_CONTEXT>, used e.g. 134namespace), a special-purpose context namespace (C<ASN_CONTEXT>, used e.g.
… …
142 163
143Thus, you can always decode a BER data structure and at worst you get a 164Thus, you can always decode a BER data structure and at worst you get a
144string in place of some nice decoded value. 165string in place of some nice decoded value.
145 166
146See the SYNOPSIS for an example of such an encoded tuple representation. 167See the SYNOPSIS for an example of such an encoded tuple representation.
168
169=head2 HELPER FUNCTIONS
170
171Working with a 4-tuple for every value can be annoying. Or, rather, I<is>
172annoying. To reduce this a bit, this module defines a number of helper
173functions, both to match BER tuples and to conmstruct BER tuples:
174
175=head3 MATCH HELPERS
176
177Thse functions accept a BER tuple as first argument and either paertially
178or fully match it. They often come in two forms, one which exactly matches
179a value, and one which only matches the type and returns the value.
180
181They do check whether valid tuples are passed in and croak otherwise. As
182a ease-of-use exception, they usually also accept C<undef> instead of a
183tuple reference. in which case they silently fail to match.
184
185=over
186
187=item $bool = ber_is $tuple, $class, $tag, $constructed, $data
188
189This takes a BER C<$tuple> and matches its elements agains the privded
190values, all of which are optional - values that are either missing or
191C<undef> will be ignored, the others will be matched exactly (e.g. as if
192you used C<==> or C<eq> (for C<$data>)).
193
194Some examples:
195
196 ber_is $tuple, ASN_UNIVERSAL, ASN_SEQUENCE, 1
197 orf die "tuple is not an ASN SEQUENCE";
198
199 ber_is $tuple, ASN_UNIVERSAL, ASN_NULL
200 or die "tuple is not an ASN NULL value";
201
202 ber_is $tuple, ASN_UNIVERSAL, ASN_INTEGER32, 0, 50
203 or die "BER integer must be 50";
204
205=item $seq = ber_is_seq $tuple
206
207Returns the sequence members (the array of subvalues) if the C<$tuple> is
208an ASN SEQUENCE, i.e. the C<BER_DATA> member. If the C<$tuple> is not a
209sequence it returns C<undef>. For example, SNMP version 1/2c/3 packets all
210consist of an outer SEQUENCE value:
211
212 my $ber = ber_decode $snmp_data;
213
214 my $snmp = ber_is_seq $ber
215 or die "SNMP packet invalid: does not start with SEQUENCE";
216
217 # now we know $snmp is a sequence, so decode the SNMP version
218
219 my $version = ber_is_i32 $snmp->[0]
220 or die "SNMP packet invalid: does not start with version number";
221
222=item $bool = ber_is_i32 $tuple, $i32
223
224Returns a true value if the C<$tuple> represents an ASN INTEGER32 with
225the value C<$i32>.
226
227=item $i32 = ber_is_i32 $tuple
228
229Returns true (and extracts the integer value) if the C<$tuple> is an ASN
230INTEGER32. For C<0>, this function returns a special value that is 0 but
231true.
232
233=item $bool = ber_is_oid $tuple, $oid_string
234
235Returns true if the C<$tuple> represents an ASN_OBJECT_IDENTIFIER
236that exactly matches C$oid_string>. Exmaple:
237
238 ber_is_oid $tuple, "1.3.6.1.4"
239 or die "oid must be 1.3.6.1.4";
240
241=item $oid = ber_is_oid $tuple
242
243Returns true (and extracts the OID string) if the C<$tuple> is an ASN
244OBJECT IDENTIFIER. Otherwise, it returns C<undef>.
245
246=back
247
248=head3 CONSTRUCTION HELPERS
249
250=over
251
252=item $tuple = ber_i32 $value
253
254Constructs a new C<ASN_INTEGER32> tuple.
255
256=back
147 257
148=head2 RELATIONSHIP TO L<Convert::BER> and L<Convert::ASN1> 258=head2 RELATIONSHIP TO L<Convert::BER> and L<Convert::ASN1>
149 259
150This module is I<not> the XS version of L<Convert::BER>, but a different 260This module is I<not> the XS version of L<Convert::BER>, but a different
151take at doing the same thing. I imagine this module would be a good base 261take at doing the same thing. I imagine this module would be a good base

Diff Legend

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