Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Encoding::BER(3)      User Contributed Perl Documentation     Encoding::BER(3)

NAME
       Encoding::BER - Perl module for encoding/decoding data using ASN.1
       Basic Encoding Rules (BER)

SYNOPSIS
	 use Encoding::BER;
	 my $enc = Encoding::BER->new();
	 my $ber = $enc->encode( $data );
	 my $xyz = $enc->decode( $ber );

DESCRIPTION
       Unlike many other BER encoder/decoders, this module uses	tree
       structured data as the interface	to/from	the encoder/decoder.

       The decoder does	not require any	form of	template or description	of the
       data to be decoded. Given arbitrary BER encoded data, the decoder
       produces	a tree shaped perl data	structure from it.

       The encoder takes a perl	data structure and produces a BER encoding
       from it.

METHODS
       new(option => value, ...)
	   constructor.

	       example:
	       my $enc = Encoding::BER->new( error => sub{ die "$_[1]\n" } );

	   the following options are available:

	   error
	       coderef called if there is an error. will be called with	2
	       parameters, the Encoding::BER object, and the error message.

		   # example: die on error
		   error => sub{ die "oops! $_[1]\n" }

	   warn
	       coderef called if there is something to warn about. will	be
	       called with 2 parameters, the Encoding::BER object, and the
	       error message.

		   # example: warn for warnings
		   warn	=> sub{	warn "how odd! $_[1]\n"	}

	   decoded_callback
	       coderef called for every	element	decoded. will be called	with 2
	       parameters, the Encoding::BER object, and the decoded data.
	       [see DECODED DATA]

		   # example: bless decoded results into a useful class
		   decoded_callback => sub{ bless $_[1], MyBER::Result }

	   debug
	       boolean.	if true, large amounts of useless gibberish will be
	       sent to stderr regarding	the encoding or	decoding process.

		   # example: enable gibberish output
		   debug => 1

       add_implicit_tag(class, type, tag-name, tag-number, base-tag)
	   add a new tag similar to another tag. class should be one of
	   "universal",	"application", "context", or "private".	type should be
	   either "primitive" or "contructed". tag-name	should specify the
	   name	of the new tag.	 tag-number should be the numeric tag number.
	   base-tag should specify the name of the tag this is equivalent to.

	       example:	add a tagged integer
	       in ASN.1: width-index ::= [context 42] implicit integer

	       $ber->add_implicit_tag('context', 'primitive', 'width-index', 42, 'integer');

       encode( data )
	   BER encode the provided data. [see: ENCODING	DATA]

	     example:
	     my	$ber = $enc->encode( [0, 'public', [7.3, 0, 0, ['foo', 'bar']]]	);

       decode( ber )
	   Decode the provided BER encoded data. returns a perl	data
	   structure.  [see: DECODED DATA]

	     example:
	     my	$data =	$enc->decode( $ber );

ENCODING DATA
       You can give data to the	encoder	in either of two ways (or mix and
       match).

       You can specify simple values directly, and the module will guess the
       correct tags to use. Things that	look like integers will	be encoded as
       "integer", things that look like	floating-point numbers will be encoded
       as "real", things that look like	strings, will be encoded as
       "octet_string".	Arrayrefs will be encoded as "sequence".

	 example:
	 $enc->encode( [0, 1.2,	"foobar", [ "baz", 37.94 ]] );

       Alternatively, you can explicity	specify	the type using a hashref
       containing "type" and "value" keys.

	 example:
	 $enc->encode( { type  => 'sequence',
			 value => [
				    { type  => 'integer',
				      value => 37 } ] }	);

       The type	may be specfied	as either a string containg the	tag-name, or
       as an arryref containing	the class, type, and tag-name.

	 example:
	 type => 'octet_string'
	 type => ['universal', 'primitive', 'octet_string']

       Note: using the second form above, you can create wacky encodings that
       no one will be able to decode.

       The value should	be a scalar value for primitive	types, and an arrayref
       for constructed types.

	 example:
	 { type	=> 'octet_string', value => 'foobar' }
	 { type	=> 'set', value	=> [ 1,	2, 3 ] }

	 { type	 => ['universal', 'constructed', 'octet_string'],
	   value => [ 'foo', 'bar' ] }

DECODED	DATA
       The values returned from	decoding will be similar to the	way data to be
       encoded is specified, in	the full long form. Additionally, the hashref
       will contain: "identval"	the numeric value representing the
       class+type+tag and "tagnum" the numeric tag number.

	 example:
	 a string might	be returned as:
	 { type	    => ['universal', 'primitive', 'octet_string'],
	   identval => 4,
	   tagnum   => 4,
	   value    => 'foobar',
	 }

TAG NAMES
       The following are recognized as valid names of tags:

	   bit_string bmp_string bool boolean character_string embedded_pdv
	   enum	enumerated external float general_string generalized_time
	   graphic_string ia5_string int int32 integer integer32 iso646_string
	   null	numeric_string object_descriptor object_identifier octet_string
	   oid printable_string	real relative_object_identifier	relative_oid
	   roid	sequence sequence_of set set_of	string t61_string teletex_string
	   uint	uint32 universal_string	universal_time unsigned_int unsigned_int32
	   unsigned_integer utf8_string	videotex_string	visible_string

Math::BigInt
       If you have Math::BigInt, it can	be used	for large integers. If you
       want it used, you must load it yourself:

	   use Math::BigInt;
	   use Encoding::BER;

       It can be used for both encoding	and decoding. The encoder can be
       handed either a Math::BigInt object, or a "big string of	digits"	marked
       as an integer:

	   use math::BigInt;

	   my $x = Math::BigInt->new( '12345678901234567890' );
	   $enc->encode( $x )

	   $enc->encode( { type	=> 'integer', '12345678901234567890' } );

       During decoding,	a Math::BigInt object will be created if the value
       "looks big".

EXPORTS
       By default, this	module exports nothing.	This can be overridden by
       specifying something else:

	   use Encoding::BER ('import',	'hexdump');

LIMITATIONS
       If your application uses	the same tag-number for	more than one type of
       implicitly tagged primitive, the	decoder	will not be able to
       distinguish between them, and will not be able to decode	them both
       correctly. eg:

	   width ::= [context 12] implicit integer
	   girth ::= [context 12] implicit real

       If you specify data to be encoded using the "short form", the module
       may guess the type differently than you expect. If it matters, be
       explicit.

       This module does	not do data validation.	It will	happily	let you	encode
       a non-ascii string as a "ia5_string", etc.

PREREQUISITES
       If you wish to use "real"s, the POSIX module is required. It will be
       loaded automatically, if	needed.

       Familiarity with	ASN.1 and BER encoding is probably required to take
       advantage of this module.

SEE ALSO
	   Yellowstone National	Park
	   Encoding::BER::CER, Encoding::BER::DER
	   Encoding::BER::SNMP,	Encoding::BER::Dumper
	   ITU-T x.690

AUTHOR
	   Jeff	Weisberg - http://www.tcp4me.com

perl v5.32.1			  2015-12-15		      Encoding::BER(3)

NAME | SYNOPSIS | DESCRIPTION | METHODS | ENCODING DATA | DECODED DATA | TAG NAMES | Math::BigInt | EXPORTS | LIMITATIONS | PREREQUISITES | SEE ALSO | AUTHOR

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Encoding::BER&sektion=3&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help