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.27 by root, Sat Apr 20 15:27:28 2019 UTC vs.
Revision 1.28 by root, Sat Apr 20 15:37:27 2019 UTC

… …
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
… …
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_INTEGER, 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_INTEGER, 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);
… …
231 231
232The most common tags in SNMP's C<ASN_APPLICATION> namespace are 232The most common tags in SNMP's C<ASN_APPLICATION> namespace are
233C<SNMP_COUNTER32>, C<SNMP_UNSIGNED32>, C<SNMP_TIMETICKS> and 233C<SNMP_COUNTER32>, C<SNMP_UNSIGNED32>, C<SNMP_TIMETICKS> and
234C<SNMP_COUNTER64>. 234C<SNMP_COUNTER64>.
235 235
236The I<CONSTRUCTED> flag is really just a boolean - if it is false, 236The I<FLAGS> value is really just a boolean at this time (but might
237the value is "primitive" and contains no subvalues, kind of like a 237get extended) - if it is C<0>, the value is "primitive" and contains
238non-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>,
239which 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
240en-/decode as BER tuples themselves. 240subvalues which this module will en-/decode as BER tuples themselves.
241 241
242The 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
243the value is I<CONSTRUCTED>), some decoded representation of the value, 243(if the value is I<FLAGS>), some decoded representation of the value, if
244if 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
245or 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
246interpret the namespace/tag. 246interpret the namespace/tag.
247 247
248Thus, 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
249string in place of some nice decoded value. 249string in place of some nice decoded value.
250 250
… …
279 279
280=item $bindata = ber_encode $tuple[, $profile] 280=item $bindata = ber_encode $tuple[, $profile]
281 281
282Encodes the BER tuple into a BER/DER data structure. AS with 282Encodes the BER tuple into a BER/DER data structure. AS with
283Cyber_decode>, an optional profile can be given. 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).
284 287
285=back 288=back
286 289
287=head2 HELPER FUNCTIONS 290=head2 HELPER FUNCTIONS
288 291
… …
396 XSLoader::load __PACKAGE__, $VERSION; 399 XSLoader::load __PACKAGE__, $VERSION;
397} 400}
398 401
399our %EXPORT_TAGS = ( 402our %EXPORT_TAGS = (
400 const_index => [qw( 403 const_index => [qw(
401 BER_CLASS BER_TAG BER_CONSTRUCTED BER_DATA 404 BER_CLASS BER_TAG BER_FLAGS BER_DATA
402 )], 405 )],
403 const_asn => [qw( 406 const_asn => [qw(
404 ASN_BOOLEAN ASN_INTEGER 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
405 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
406 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
… …
609 612
610OBJECT IDENTIFIEERs cannot have unlimited length, although the limit is 613OBJECT IDENTIFIEERs cannot have unlimited length, although the limit is
611much larger than e.g. the one imposed by SNMP or other protocols,a nd is 614much larger than e.g. the one imposed by SNMP or other protocols,a nd is
612about 4kB. 615about 4kB.
613 616
617Indefinite length encoding is not supported.
618
619Constructed strings are decoded just fine, but there should be a way to
620join them for convenience.
621
614REAL values are not supported and will currently croak. 622REAL values are not supported and will currently croak.
615 623
616This module has undergone little to no testing so far. 624This module has undergone little to no testing so far.
617 625
618=head2 ITHREADS SUPPORT 626=head2 ITHREADS SUPPORT

Diff Legend

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