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.24 by root, Sat Apr 20 14:59:26 2019 UTC

… …
189For example: 189For example:
190 190
191 [ASN_UNIVERSAL, ASN_INTEGER32, 0, 177] # the integer 177 191 [ASN_UNIVERSAL, ASN_INTEGER32, 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_CONSTRUCTED> and C<BER_DATA>.
199 199
… …
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_INTEGER32>, 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<CONSTRUCTED> flag is really just a boolean - if it is false,
238the value is "primitive" and contains no subvalues, kind of like a 237the value is "primitive" and contains no subvalues, kind of like a
239non-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"
240which 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
241en-/decode as BER tuples themselves. 240en-/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 (if
244the value is I<CONSTRUCTED>), some decoded representation of the value, 243the value is I<CONSTRUCTED>), some decoded representation of the value,
… …
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
264=item $bindata = ber_encode $tuple 271=item $bindata = ber_encode $tuple[, $profile]
265 272
266Encodes 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.
267 275
268=back 276=back
269 277
270=head2 HELPER FUNCTIONS 278=head2 HELPER FUNCTIONS
271 279
272Working 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>
273annoying. 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
274functions, both to match BER tuples and to conmstruct BER tuples: 282functions, both to match BER tuples and to construct BER tuples:
275 283
276=head3 MATCH HELPERS 284=head3 MATCH HELPERS
277 285
278Thse functions accept a BER tuple as first argument and either paertially 286These 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 287or 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. 288a value, and one which only matches the type and returns the value.
281 289
282They 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
283a 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
284tuple reference. in which case they silently fail to match. 292tuple reference, in which case they silently fail to match.
285 293
286=over 294=over
287 295
288=item $bool = ber_is $tuple, $class, $tag, $constructed, $data 296=item $bool = ber_is $tuple, $class, $tag, $constructed, $data
289 297
290This 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
291values, all of which are optional - values that are either missing or 299values, 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 300C<undef> will be ignored, the others will be matched exactly (e.g. as if
293you used C<==> or C<eq> (for C<$data>)). 301you used C<==> or C<eq> (for C<$data>)).
294 302
295Some examples: 303Some examples:

Diff Legend

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