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.6 by root, Fri Apr 19 20:38:38 2019 UTC vs.
Revision 1.12 by root, Fri Apr 19 21:24:31 2019 UTC

… …
28 [ ASN_APPLICATION, ASN_TIMETICKS, 0, 1817903850 ], # SNMP TimeTicks 28 [ ASN_APPLICATION, ASN_TIMETICKS, 0, 1817903850 ], # SNMP TimeTicks
29 [ ASN_UNIVERSAL, ASN_SEQUENCE, 1, # the varbindlist 29 [ ASN_UNIVERSAL, ASN_SEQUENCE, 1, # the varbindlist
30 [ 30 [
31 [ ASN_UNIVERSAL, ASN_SEQUENCE, 1, # a single varbind, "key value" pair 31 [ ASN_UNIVERSAL, ASN_SEQUENCE, 1, # a single varbind, "key value" pair
32 [ 32 [
33 [ ASN_UNIVERSAL, ASN_OBJECT_IDENTIFIER, 0, "1.3.6.1.4.1.9.9.215.1.1.8.1.2.1" ], # the oid 33 [ ASN_UNIVERSAL, ASN_OBJECT_IDENTIFIER, 0, "1.3.6.1.4.1.9.9.215.1.1.8.1.2.1" ],
34 [ ASN_UNIVERSAL, ASN_OCTET_STRING, 0, "...data..." # the value 34 [ ASN_UNIVERSAL, ASN_OCTET_STRING, 0, "...data..." # the value
35 ] 35 ]
36 ] 36 ]
37 ], 37 ],
38 ... 38 ...
… …
64 64
65 my $buf = ber_encode $ber; 65 my $buf = ber_encode $ber;
66 66
67=head1 DESCRIPTION 67=head1 DESCRIPTION
68 68
69WARNING: Before release 1.0, the API is not considered stable in any way.
70
69This module implements a I<very> low level BER/DER en-/decoder. 71This module implements a I<very> low level BER/DER en-/decoder.
70 72
71If is tuned for low memory and high speed, while still maintaining some 73If is tuned for low memory and high speed, while still maintaining some
72level of user-friendlyness. 74level of user-friendlyness.
73 75
… …
80data structures. It supports various mappings to JSON, XML, but most 82data structures. It supports various mappings to JSON, XML, but most
81importantly, to a various binary encodings such as BER, that is the topic 83importantly, to a various binary encodings such as BER, that is the topic
82of this module, and is used in SNMP or LDAP for example. 84of this module, and is used in SNMP or LDAP for example.
83 85
84While ASN.1 defines a schema that is useful to interpret encoded data, 86While ASN.1 defines a schema that is useful to interpret encoded data,
85the BER encoding is actually somehat self-describing: you might not know 87the BER encoding is actually somewhat self-describing: you might not know
86whether something is a string or a number or a sequence or something else, 88whether something is a string or a number or a sequence or something else,
87but you can nevertheless decode the overall structure, even if you end up 89but you can nevertheless decode the overall structure, even if you end up
88with just a binary blob for the actual value. 90with just a binary blob for the actual value.
89 91
90This works because BER values are tagged with a type and a namespace, 92This works because BER values are tagged with a type and a namespace,
… …
118I<DATA> member, and you may re-assign the array itself, e.g.: 120I<DATA> member, and you may re-assign the array itself, e.g.:
119 121
120 $ber = ber_decode $binbuf; 122 $ber = ber_decode $binbuf;
121 123
122 # the following is NOT legal: 124 # the following is NOT legal:
123 $ber->[BER_CLASS] = ASN_PRIVATE; # ERROR, readonly(!) 125 $ber->[BER_CLASS] = ASN_PRIVATE; # ERROR, CLASS/TAG/CONSTRUCTED are READ ONLY(!)
124 126
125 # but all of the following are fine: 127 # but all of the following are fine:
126 $ber->[BER_DATA] = "string"; 128 $ber->[BER_DATA] = "string";
127 $ber->[BER_DATA] = [ASN_UNIVERSAL, ASN_INTEGER32, 0, 123]; 129 $ber->[BER_DATA] = [ASN_UNIVERSAL, ASN_INTEGER32, 0, 123];
128 @$ber = (ASN_APPLICATION, SNMP_TIMETICKS, 1000); 130 @$ber = (ASN_APPLICATION, SNMP_TIMETICKS, 0, 1000);
129 131
130I<CLASS> is something like a namespace for I<TAG>s - there is the 132I<CLASS> is something like a namespace for I<TAG>s - there is the
131C<ASN_UNIVERSAL> namespace which defines tags common to all ASN.1 133C<ASN_UNIVERSAL> namespace which defines tags common to all ASN.1
132implementations, the C<ASN_APPLICATION> namespace which defines tags for 134implementations, the C<ASN_APPLICATION> namespace which defines tags for
133specific applications (for example, the SNMP C<Unsigned32> type is in this 135specific applications (for example, the SNMP C<Unsigned32> type is in this
… …
164Thus, you can always decode a BER data structure and at worst you get a 166Thus, you can always decode a BER data structure and at worst you get a
165string in place of some nice decoded value. 167string in place of some nice decoded value.
166 168
167See the SYNOPSIS for an example of such an encoded tuple representation. 169See the SYNOPSIS for an example of such an encoded tuple representation.
168 170
171=head2 DECODING AND ENCODING
172
173=over
174
175=item $tuple = ber_decoded $bindata
176
177Decodes binary BER data in C<$bindata> and returns the resulting BER
178tuple. Croaks on any decoding error, so the returned C<$tuple> is always
179valid.
180
181=item $bindata = ber_encode $tuple
182
183Encodes the BER tuple into a BER/DER data structure.
184
185=back
186
169=head2 HELPER FUNCTIONS 187=head2 HELPER FUNCTIONS
170 188
171Working with a 4-tuple for every value can be annoying. Or, rather, I<is> 189Working 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 190annoying. To reduce this a bit, this module defines a number of helper
173functions, both to match BER tuples and to conmstruct BER tuples: 191functions, both to match BER tuples and to conmstruct BER tuples:
… …
231true. 249true.
232 250
233=item $bool = ber_is_oid $tuple, $oid_string 251=item $bool = ber_is_oid $tuple, $oid_string
234 252
235Returns true if the C<$tuple> represents an ASN_OBJECT_IDENTIFIER 253Returns true if the C<$tuple> represents an ASN_OBJECT_IDENTIFIER
236that exactly matches C$oid_string>. Exmaple: 254that exactly matches C<$oid_string>. Example:
237 255
238 ber_is_oid $tuple, "1.3.6.1.4" 256 ber_is_oid $tuple, "1.3.6.1.4"
239 or die "oid must be 1.3.6.1.4"; 257 or die "oid must be 1.3.6.1.4";
240 258
241=item $oid = ber_is_oid $tuple 259=item $oid = ber_is_oid $tuple
… …
269use common::sense; 287use common::sense;
270 288
271use XSLoader (); 289use XSLoader ();
272use Exporter qw(import); 290use Exporter qw(import);
273 291
274our $VERSION = 0.1; 292our $VERSION = 0.2;
275 293
276XSLoader::load __PACKAGE__, $VERSION; 294XSLoader::load __PACKAGE__, $VERSION;
277 295
278our %EXPORT_TAGS = ( 296our %EXPORT_TAGS = (
279 const => [qw( 297 const => [qw(

Diff Legend

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