asn man page on Darwin

Man page or keyword search:  
man Server   23457 pages
apropos Keyword Search (all sections)
Output format
Darwin logo
[printable version]

asn(n)			       ASN.1 processing				asn(n)

______________________________________________________________________________

NAME
       asn - ASN.1 BER encoder/decoder

SYNOPSIS
       package require Tcl  8.4

       package require asn  ?0.8.3?

       ::asn::asnSequence evalue...

       ::asn::asnSequenceFromList elist

       ::asn::asnSet evalue...

       ::asn::asnSetFromList elist

       ::asn::asnApplicationConstr appNumber evalue...

       ::asn::asnApplication appNumber data

       ::asn::asnChoice appNumber evalue...

       ::asn::asnChoiceConstr appNumber evalue...

       ::asn::asnInteger number

       ::asn::asnEnumeration number

       ::asn::asnBoolean bool

       ::asn::asnContext context data

       ::asn::asnContextConstr context evalue...

       ::asn::asnObjectIdentifier idlist

       ::asn::asnUTCTime utcstring

       ::asn::asnNull

       ::asn::asnBitString string

       ::asn::asnOctetString string

       ::asn::asnNumericString string

       ::asn::asnPrintableString string

       ::asn::asnIA5String string

       ::asn::asnBMPString string

       ::asn::asnUTF8String string

       ::asn::asnString string

       ::asn::defaultStringType ?type?

       ::asn::asnPeekByte data_var byte_var

       ::asn::asnGetLength data_var length_var

       ::asn::asnGetResponse chan data_var

       ::asn::asnGetInteger data_var int_var

       ::asn::asnGetEnumeration data_var enum_var

       ::asn::asnGetOctetString data_var string_var

       ::asn::asnGetString data_var string_var ?type_var?

       ::asn::asnGetNumericString data_var string_var

       ::asn::asnGetPrintableString data_var string_var

       ::asn::asnGetIA5String data_var string_var

       ::asn::asnGetBMPString data_var string_var

       ::asn::asnGetUTF8String data_var string_var

       ::asn::asnGetUTCTime data_var utc_var

       ::asn::asnGetBitString data_var bits_var

       ::asn::asnGetObjectIdentifier data_var oid_var

       ::asn::asnGetBoolean data_var bool_var

       ::asn::asnGetNull data_var

       ::asn::asnGetSequence data_var sequence_var

       ::asn::asnGetSet data_var set_var

       ::asn::asnGetApplication	 data_var  appNumber_var ?content_var? ?encod‐
       ingType_var?

       ::asn::asnGetContext data_var contextNumber_var	?content_var?  ?encod‐
       ingType_var?

       ::asn::asnPeekTag data_var tag_var tagtype_var constr_var

       ::asn::asnTag tagnumber ?class? ?tagstyle?

       ::asn::asnRetag data_var newTag

_________________________________________________________________

DESCRIPTION
       The  asn	 package  provides  partial  de-  and encoder commands for BER
       encoded ASN.1 data. It can also be used for decoding DER,  which	 is  a
       restricted subset of BER.

       ASN.1  is  a  standard  Abstract Syntax Notation, and BER are its Basic
       Encoding Rules.

       See http://asn1.elibel.tm.fr/en/standards/index.htm for	more  informa‐
       tion about the standard.

       Also see http://luca.ntop.org/Teaching/Appunti/asn1.html for A Layman's
       Guide to a Subset of ASN.1, BER, and DER, an RSA Laboratories Technical
       Note  by	 Burton S. Kaliski Jr. (Revised November 1, 1993). A text ver‐
       sion of this note is part of the module sources and should be  read  by
       any implementor.

PUBLIC API
   ENCODER
       ::asn::asnSequence evalue...
	      Takes  zero  or  more  encoded  values,  packs  them into an ASN
	      sequence and returns its encoded binary form.

       ::asn::asnSequenceFromList elist
	      Takes a list of encoded values, packs them into an ASN  sequence
	      and returns its encoded binary form.

       ::asn::asnSet evalue...
	      Takes  zero  or  more encoded values, packs them into an ASN set
	      and returns its encoded binary form.

       ::asn::asnSetFromList elist
	      Takes a list of encoded values, packs them into an ASN  set  and
	      returns its encoded binary form.

       ::asn::asnApplicationConstr appNumber evalue...
	      Takes zero or more encoded values, packs them into an ASN appli‐
	      cation construct and returns its encoded binary form.

       ::asn::asnApplication appNumber data
	      Takes a single encoded value data, packs it into an ASN applica‐
	      tion construct and returns its encoded binary form.

       ::asn::asnChoice appNumber evalue...
	      Takes zero or more encoded values, packs them into an ASN choice
	      construct and returns its encoded binary form.

       ::asn::asnChoiceConstr appNumber evalue...
	      Takes zero or more encoded values, packs them into an ASN choice
	      construct and returns its encoded binary form.

       ::asn::asnInteger number
	      Returns the encoded form of the specified integer number.

       ::asn::asnEnumeration number
	      Returns the encoded form of the specified enumeration id number.

       ::asn::asnBoolean bool
	      Returns the encoded form of the specified boolean value bool.

       ::asn::asnContext context data
	      Takes  an	 encoded  value	 and packs it into a constructed value
	      with application tag, the context number.

       ::asn::asnContextConstr context evalue...
	      Takes zero or more encoded values and packs  them	 into  a  con‐
	      structed value with application tag, the context number.

       ::asn::asnObjectIdentifier idlist
	      Takes a list of at least 2 integers describing an object identi‐
	      fier (OID) value, and returns the encoded value.

       ::asn::asnUTCTime utcstring
	      Returns the encoded form of the specified UTC time string.

       ::asn::asnNull
	      Returns the NULL encoding.

       ::asn::asnBitString string
	      Returns the encoded form of the specified string.

       ::asn::asnOctetString string
	      Returns the encoded form of the specified string.

       ::asn::asnNumericString string
	      Returns the string encoded as  ASN.1  NumericString.  Raises  an
	      error  if the string contains characters other than decimal num‐
	      bers and space.

       ::asn::asnPrintableString string
	      Returns the string encoding as ASN.1 PrintableString. Raises  an
	      error if the string contains characters which are not allowed by
	      the Printable String datatype. The allowed characters  are  A-Z,
	      a-z,  0-9,  space,  apostrophe, colon, parentheses, plus, minus,
	      comma, period, forward slash,  question  mark,  and  the	equals
	      sign.

       ::asn::asnIA5String string
	      Returns  the  string encoded as ASN.1 IA5String. Raises an error
	      if the string contains any characters outside  of	 the  US-ASCII
	      range.

       ::asn::asnBMPString string
	      Returns  the  string  encoded  as ASN.1 Basic Multilingual Plane
	      string (Which is essentialy big-endian UCS2).

       ::asn::asnUTF8String string
	      Returns the string encoded as UTF8 String. Note that some legacy
	      applications such as Windows CryptoAPI do not like UTF8 strings.
	      Use BMPStrings if you are not sure.

       ::asn::asnString string
	      Returns an encoded form of string, choosing the most  restricted
	      ASN.1  string  type  possible.  If the string contains non-ASCII
	      characters, then there is more than one string type which can be
	      used. See ::asn::defaultStringType.

       ::asn::defaultStringType ?type?
	      Selects  the  string  type  to use for the encoding of non-ASCII
	      strings. Returns current default when called  without  argument.
	      If  the  argument	 type is supplied, it should be either UTF8 or
	      BMP to choose UTF8String or BMPString respectively.

   DECODER
       General notes:

       [1]    Nearly all decoder commands take two arguments. These  arguments
	      are  variable names, except for ::asn::asnGetResponse. The first
	      variable contains the encoded ASN value to decode at the	begin‐
	      ning,  and  more,	 and the second variable is where the value is
	      stored to. The remainder of the input after the decoded value is
	      stored back into the datavariable.

       [2]    After  extraction	 the  data  variable is always modified first,
	      before by writing the extracted  value  to  its  variable.  This
	      means that if both arguments refer to the same variable, it will
	      always contain the extracted value after the call, and  not  the
	      remainder of the input.

       ::asn::asnPeekByte data_var byte_var
	      Retrieve	the first byte of the data, without modifing data_var.
	      This can be used to check for implicit tags.

       ::asn::asnGetLength data_var length_var
	      Decode the length information for a block of BER data.  The  tag
	      has already to be removed from the data.

       ::asn::asnGetResponse chan data_var
	      Reads  an	 encoded ASN sequence from the channel chan and stores
	      it into the variable named by data_var.

       ::asn::asnGetInteger data_var int_var
	      Assumes that an encoded integer value is at  the	front  of  the
	      data  stored in the variable named data_var, extracts and stores
	      it into the variable named by int_var. Additionally removes  all
	      bytes  associated	 with the value from the data for further pro‐
	      cessing by the following decoder commands.

       ::asn::asnGetEnumeration data_var enum_var
	      Assumes that an enumeration id is	 at  the  front	 of  the  data
	      stored  in  the  variable named data_var, and stores it into the
	      variable named by enum_var. Additionally removes all bytes asso‐
	      ciated  with  the	 value from the data for further processing by
	      the following decoder commands.

       ::asn::asnGetOctetString data_var string_var
	      Assumes that a string is at the front of the data stored in  the
	      variable	named  data_var, and stores it into the variable named
	      by string_var. Additionally removes all  bytes  associated  with
	      the  value from the data for further processing by the following
	      decoder commands.

       ::asn::asnGetString data_var string_var ?type_var?
	      Decodes a user-readable string. This is a	 convenience  function
	      which  is	 able to automatically distinguish all supported ASN.1
	      string types and convert the  input  value  appropriately.   See
	      ::asn::asnGetPrintableString, ::asnGetIA5String, etc.  below for
	      the type-specific conversion commands.

	      If the optional third argument type_var is  supplied,  then  the
	      type  of	the incoming string is stored in the variable named by
	      it.

	      The function throws the error "Invalid command name  asnGetSome‐
	      UnsupportedString" if the unsupported string type Unsupported is
	      encountered.   You   can	 create	  the	appropriate   function
	      "asn::asnGetSomeUnsupportedString"  in  your application if nec‐
	      cessary.

       ::asn::asnGetNumericString data_var string_var
	      Assumes that a numeric string value is at the front of the  data
	      stored  in  the  variable named data_var, and stores it into the
	      variable named by string_var.  Additionally  removes  all	 bytes
	      associated  with	the value from the data for further processing
	      by the following decoder commands.

       ::asn::asnGetPrintableString data_var string_var
	      Assumes that a printable string value is at  the	front  of  the
	      data  stored  in the variable named data_var, and stores it into
	      the variable named by string_var. Additionally removes all bytes
	      associated  with	the value from the data for further processing
	      by the following decoder commands.

       ::asn::asnGetIA5String data_var string_var
	      Assumes that a IA5 (ASCII) string value is at the front  of  the
	      data  stored  in the variable named data_var, and stores it into
	      the variable named by string_var. Additionally removes all bytes
	      associated  with	the value from the data for further processing
	      by the following decoder commands.

       ::asn::asnGetBMPString data_var string_var
	      Assumes that a BMP (two-byte unicode) string  value  is  at  the
	      front  of	 the  data  stored in the variable named data_var, and
	      stores it into the variable named by string_var,	converting  it
	      into a proper Tcl string. Additionally removes all bytes associ‐
	      ated with the value from the data for further processing by  the
	      following decoder commands.

       ::asn::asnGetUTF8String data_var string_var
	      Assumes  that  a	UTF8  string value is at the front of the data
	      stored in the variable named data_var, and stores	 it  into  the
	      variable	named  by  string_var, converting it into a proper Tcl
	      string.  Additionally removes  all  bytes	 associated  with  the
	      value  from  the	data  for  further processing by the following
	      decoder commands.

       ::asn::asnGetUTCTime data_var utc_var
	      Assumes that a UTC time value is at the front of the data stored
	      in  the variable named data_var, and stores it into the variable
	      named by utc_var. The UTC time value  is	stored	as  a  string,
	      which  has  to  be  decoded  with the usual clock scan commands.
	      Additionally removes all bytes associated with  the  value  from
	      the  data	 for  further processing by the following decoder com‐
	      mands.

       ::asn::asnGetBitString data_var bits_var
	      Assumes that a bit string value is at  the  front	 of  the  data
	      stored  in  the  variable named data_var, and stores it into the
	      variable named by bits_var as a string containing only 0 and  1.
	      Additionally  removes  all  bytes associated with the value from
	      the data for further processing by the  following	 decoder  com‐
	      mands.

       ::asn::asnGetObjectIdentifier data_var oid_var
	      Assumes  that a object identifier (OID) value is at the front of
	      the data stored in the variable named data_var,  and  stores  it
	      into the variable named by oid_var as a list of integers.	 Addi‐
	      tionally removes all bytes associated with the  value  from  the
	      data for further processing by the following decoder commands.

       ::asn::asnGetBoolean data_var bool_var
	      Assumes  that a boolean value is at the front of the data stored
	      in the variable named data_var, and stores it into the  variable
	      named  by	 bool_var.  Additionally  removes all bytes associated
	      with the value from the data for further processing by the  fol‐
	      lowing decoder commands.

       ::asn::asnGetNull data_var
	      Assumes  that a NULL value is at the front of the data stored in
	      the variable named data_var and removes the bytes used to encode
	      it from the data.

       ::asn::asnGetSequence data_var sequence_var
	      Assumes  that an ASN sequence is at the front of the data stored
	      in the variable named data_var, and stores it into the  variable
	      named by sequence_var. Additionally removes all bytes associated
	      with the value from the data for further processing by the  fol‐
	      lowing decoder commands.

	      The data in sequence_var is encoded binary and has to be further
	      decoded according to the definition of the sequence,  using  the
	      decoder commands here.

       ::asn::asnGetSet data_var set_var
	      Assumes  that  an	 ASN set is at the front of the data stored in
	      the variable named data_var, and stores  it  into	 the  variable
	      named by set_var. Additionally removes all bytes associated with
	      the value from the data for further processing by the  following
	      decoder commands.

	      The  data	 in  set_var  is  encoded binary and has to be further
	      decoded according to  the	 definition  of	 the  set,  using  the
	      decoder commands here.

       ::asn::asnGetApplication	 data_var  appNumber_var ?content_var? ?encod‐
       ingType_var?
	      Assumes that an ASN application construct is at the front of the
	      data  stored  in	the variable named data_var, and stores its id
	      into the variable named by appNumber_var.	 Additionally  removes
	      all  bytes  associated  with the value from the data for further
	      processing by the following decoder commands.  If a  content_var
	      is  specified,  then the command places all data associated with
	      it into the named variable, in the binary form which can be pro‐
	      cessed  using the decoder commands of this package.  If a encod‐
	      ingType_var is specified, then that var  is  set	to  1  if  the
	      encoding is constructed and 0 if it is primitive.

	      Otherwise	 it  is the responsibility of the caller to decode the
	      remainder of the application construct based on the id retrieved
	      by this command, using the decoder commands of this package.

       ::asn::asnGetContext  data_var  contextNumber_var ?content_var? ?encod‐
       ingType_var?
	      Assumes that an ASN context tag construct is at the front of the
	      data  stored  in	the variable named data_var, and stores its id
	      into  the	 variable  named  by  contextNumber_var.  Additionally
	      removes  all  bytes  associated with the value from the data for
	      further processing by the following decoder commands.  If a con‐
	      tent_var	is specified, then the command places all data associ‐
	      ated with it into the named variable, in the binary  form	 which
	      can be processed using the decoder commands of this package.  If
	      a encodingType_var is specified, then that var is set  to	 1  if
	      the encoding is constructed and 0 if it is primitive.

	      Otherwise	 it  is the responsibility of the caller to decode the
	      remainder of the construct based on the  id  retrieved  by  this
	      command, using the decoder commands of this package.

   HANDLING TAGS
       Working	with ASN.1 you often need to decode tagged values, which use a
       tag thats different from the universal tag for a type. In  those	 cases
       you  have  to replace the tag with the universal tag used for the type,
       to decode the value.  To decode a tagged value use the  ::asn::asnRetag
       to  change  the	tag to the appropriate type to use one of the decoders
       for primitive values.  To help with  this  the  module  contains	 three
       functions:

       ::asn::asnPeekTag data_var tag_var tagtype_var constr_var
	      The  ::asn::asnPeekTag command can be used to take a peek at the
	      data and decode the tag value,  without  removing	 it  from  the
	      data.  The  tag_var  gets	 set to the tag number, while the tag‐
	      type_var gets set to the class of the  tag.  (Either  UNIVERSAL,
	      CONTEXT,	APPLICATION or PRIVATE). The constr_var is set to 1 if
	      the tag is for a constructed  value,  and	 to  0	for  not  con‐
	      structed. It returns the length of the tag.

       ::asn::asnTag tagnumber ?class? ?tagstyle?
	      The ::asn::asnTag can be used to create a tag value. The tagnum‐
	      ber gives the number of the tag, while the class	gives  one  of
	      the  classes  (UNIVERSAL,CONTEXT,APPLICATION  or	PRIVATE).  The
	      class may be abbreviated to just	the  first  letter  (U,C,A,P),
	      default  is UNIVERSAL.  The tagstyle is either C for Constructed
	      encoding, or P for primitve encoding. It defaults to P. You  can
	      also use 1 instead of C and 0 instead of P for direct use of the
	      values returned by ::asn::asnPeekTag.

       ::asn::asnRetag data_var newTag
	      Replaces the tag in front of the data in data_var	 with  newTag.
	      The new Tag can be created using the ::asn::asnTag command.

EXAMPLES
       Examples	 for the usage of this package can be found in the implementa‐
       tion of package ldap.

BUGS, IDEAS, FEEDBACK
       This document, and the package it describes, will  undoubtedly  contain
       bugs and other problems.	 Please report such in the category asn of the
       Tcllib  SF  Trackers  [http://sourceforge.net/tracker/?group_id=12883].
       Please  also  report any ideas for enhancements you may have for either
       package and/or documentation.

KEYWORDS
       asn, ber, cer, der, internet, protocol, x.208, x.209

CATEGORY
       Networking

COPYRIGHT
       Copyright (c) 2004 Andreas Kupries <andreas_kupries@users.sourceforge.net>
       Copyright (c) 2004 Jochen Loewer <loewerj@web.de>
       Copyright (c) 2004-2008 Michael Schlenker <mic42@users.sourceforge.net>

asn				      0.8				asn(n)
[top]

List of man pages available for Darwin

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net