Rework POW build so that we can use static libraries again.

svn path=/configure; revision=3602

1 files changed, 2294 insertions, 0 deletions

diff --git a/pow/POW/_der.py b/pow/POW/_der.py
new file mode 100644
index 00000000..c7f58411
--- /dev/null
+++ b/pow/POW/_der.py
@@ -0,0 +1,2294 @@
+#*****************************************************************************#
+#*                                                                           *#
+#*  Copyright (c) 2002, Peter Shannon                                        *#
+#*  All rights reserved.                                                     *#
+#*                                                                           *#
+#*  Redistribution and use in source and binary forms, with or without       *#
+#*  modification, are permitted provided that the following conditions       *#
+#*  are met:                                                                 *#
+#*                                                                           *#
+#*      * Redistributions of source code must retain the above               *#
+#*        copyright notice, this list of conditions and the following        *#
+#*        disclaimer.                                                        *#
+#*                                                                           *#
+#*      * Redistributions in binary form must reproduce the above            *#
+#*        copyright notice, this list of conditions and the following        *#
+#*        disclaimer in the documentation and/or other materials             *#
+#*        provided with the distribution.                                    *#
+#*                                                                           *#
+#*      * The name of the contributors may be used to endorse or promote     *#
+#*        products derived from this software without specific prior         *#
+#*        written permission.                                                *#
+#*                                                                           *#
+#*  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS      *#
+#*  "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT        *#
+#*  LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS        *#
+#*  FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS   *#
+#*  OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,          *#
+#*  SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT         *#
+#*  LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,    *#
+#*  DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY    *#
+#*  THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT      *#
+#*  (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE    *#
+#*  OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.     *#
+#*                                                                           *#
+#*****************************************************************************#
+
+import exceptions, types, copy, string, time, base64, traceback, cStringIO
+
+DEBUG = 0
+
+# CLASS
+CLASS_UNIVERSAL   = 0x00
+CLASS_APPLICATION = 0x40
+CLASS_CONTEXT     = 0x80
+CLASS_PRIVATE     = 0xC0
+
+# FORM
+FORM_PRIMITIVE	   = 0x00
+FORM_CONSTRUCTED	= 0x20
+
+# TAG
+TAG_BOOLEAN          = 0x01
+TAG_INTEGER          = 0x02
+TAG_BITSTRING        = 0x03
+TAG_OCTETSTRING      = 0x04
+TAG_NULL             = 0x05
+TAG_OID              = 0x06
+TAG_OBJDESCRIPTOR    = 0x07
+TAG_EXTERNAL         = 0x08
+TAG_REAL             = 0x09
+TAG_ENUMERATED       = 0x0A
+TAG_EMBEDDED_PDV     = 0x0B
+TAG_UTF8STRING       = 0x0C
+TAG_SEQUENCE         = 0x10
+TAG_SET              = 0x11
+TAG_NUMERICSTRING    = 0x12
+TAG_PRINTABLESTRING  = 0x13
+TAG_T61STRING        = 0x14
+TAG_VIDEOTEXSTRING   = 0x15
+TAG_IA5STRING        = 0x16
+TAG_UTCTIME          = 0x17
+TAG_GENERALIZEDTIME  = 0x18
+TAG_GRAPHICSTRING    = 0x19
+TAG_VISIBLESTRING    = 0x1A
+TAG_GENERALSTRING    = 0x1B
+TAG_UNIVERSALSTRING  = 0x1C
+TAG_BMPSTRING        = 0x1E
+
+_fragments = []
+
+def _docset():
+   return _fragments
+
+def _addFragment(frag):
+   global _fragments
+   _fragments.append(frag)
+
+
+_addFragment('''
+<moduleDescription>
+   <header>
+      <name>POW.pkix</name>
+      <author>Peter Shannon</author>
+   </header>
+   <body>
+      <para>
+         This module is a solution to reading and writing X509v3 written
+         purely in Python.  It does use limited facilities from POW for
+         signing and verifying but these could be replaced easily.  It is
+         an abstract module and to use it successfully RFC3280 should be
+         referred to as well as the sourcecode where necessary.  The correct
+         use of many extensions often not clear from the definitions alone.
+         Do refer to the RFC for details.
+      </para>
+      <para>
+         Each constructed objects defined in the RFC is built from primitives
+         defined by the ASN1 recommedations.  Not all ASN1 primitive are available but all those
+         required for X509v3 should be.  The implementation is more or less
+         complete for DER encoding the only caveat, aside from a few
+         missing objects, is the behaviour of <classname>SET</classname> objects
+         and <classname>SET OF</classname> objects.  The order the objects are
+         written in should be determined at runtime by sorting their tags but this
+         library does not do this.  For X509 it isn't really necessary
+         since all the <classname>Set</classname> objects are simple and the
+         order they are written in is defined by the object's constructor.
+      </para>
+      <para>
+         Every documented object in this module supports the functions documented for
+         <classname>_GeneralObject</classname>.  In general the function
+         will only be documented in descendant classes if the class changes
+         the behaviour significantly from its ancestor.  This would
+         normally be <classname>_GeneralObject</classname> or
+         <classname>Sequence</classname>.
+      </para>
+   </body>
+</moduleDescription>
+''')
+
+class DerError(Exception):
+   def __init__(self, msg):
+      if not isinstance(msg, types.StringType):
+         raise Exception, 'argunment should be a string'
+      self.msg = msg
+
+   def __repr__(self):
+         return self.msg
+
+   __str__ = __repr__
+
+class _Tag(object):
+   def __init__(self):
+      self.tagclass = 0
+      self.tagform = 0
+      self.tagnumber = 0
+
+   def __repr__(self):
+      return '(%s, %s, %s)' % (self.tagclass, self.tagform, self.tagnumber)
+
+   def write(self, file):
+      if self.tagnumber < 31:
+         file.write( chr(self.tagclass | self.tagform | self.tagnumber) )
+      else:
+         val = copy.deepcopy(self.tagnumber)
+         bytes = []
+         while val:
+            byte = val & 0x7F
+            bytes.append(byte | 0x80)
+            val = val >> 7
+         bytes[0] = bytes[0] ^ 0x80
+         bytes.append( self.tagclass | self.tagform | 0x1F )
+         bytes.reverse()
+         file.write( string.join(map(chr, bytes), '') )
+
+   def read(self, file):
+      octet1 = ord( file.read(1) )
+      self.tagclass = octet1 & 0xC0
+      self.tagform = octet1 & 0x20
+      value = octet1 & 0x1F
+      if value < 31:
+         self.tagnumber = value
+      else:
+         total = 0
+         byte = 0x80
+         while byte & 0x80:
+            byte = ord( file.read(1) )
+            if byte & 0x80:
+               total = (total << 7) | byte ^ 0x80
+            else:
+               total = (total << 7) | byte
+         self.tagnumber = total
+ 
+class _Length(object):
+   def __init__(self):
+      self.length = 0
+
+   def __repr__(self):
+      return '(%s)' % self.length
+
+   def write(self, file):
+      if self.length < 128:
+         file.write( chr(self.length) )
+      else:
+         val = copy.deepcopy(self.length)
+         bytes = []
+         while val:
+            byte = val & 0xFF
+            bytes.append(byte)
+            val = val >> 8
+         lengthOfLength = len(bytes)
+         if lengthOfLength > 126:
+            raise DerError, 'object is too long!'
+         bytes.append(lengthOfLength)  
+         bytes.reverse()
+         bytes[0] = bytes[0] ^ 0x80
+         file.write( string.join(map(chr, bytes), '') )
+
+   def read(self, file):
+      octet1 = ord( file.read(1) )
+      if octet1 < 128:
+         self.length = octet1
+      else:
+         total = 0
+         byte = 0
+         for i in range(octet1 ^ 0x80):
+            byte = ord( file.read(1) )
+            total = (total << 8) | byte
+         self.length = total
+ 
+class _TlvIo(_Tag, _Length):
+   def __init__(self, file):
+      self.file = file
+      self.offset = None
+      self.valueOffset = None
+
+   def __repr__(self):
+      return '<TAG:%s Length:%s>' % (_Tag.__repr__(self), _Length.__repr__(self))
+
+   def __nonzero__(self):
+      pos = self.file.tell()
+      self.file.seek(0,2)
+      if self.file.tell():
+         self.file.seek(pos)
+         return 1
+      else:
+         return 0
+
+   def read(self):
+      self.offset = self.file.tell()
+      _Tag.read( self, self.file )
+      _Length.read( self, self.file )
+      self.valueOffset = self.file.tell()
+      self.file.seek( self.length, 1 )
+
+   def readValue(self):
+      self.file.seek( self.valueOffset )
+      return self.file.read( self.length )
+
+   def write(self, val):
+      _Tag.write( self, self.file )
+      self.length = len(val)
+      _Length.write( self, self.file )
+      self.file.write(val)
+
+def _decodeBoolean(val):
+   'der encoded value not including tag or length'
+   if not isinstance(val, types.StringType):
+      raise DerError, 'argument should be a string'
+   if ord(val) == 0xFF:
+      return 1
+   elif ord(val) == 0x00:
+      return 0
+   else:
+      raise DerError, 'boolean should be encode as all 1s or all 0s'
+
+def _encodeBoolean(val):
+   'anything we can test for truth'
+   if val:
+      return chr(0xFF)
+   else:
+      return chr(0x00)
+
+def _decodeInteger(val):
+   'der encoded value not including tag or length'
+   if not isinstance(val, types.StringType):
+      raise DerError, 'argument should be a string'
+   total = 0L
+   if ord(val[0]) & 0x80:
+      val = map( lambda x : ord(x) ^ 0xFF, val )
+      for byte in val:
+         total = (total << 8) | byte
+      total = -(total+1) 
+   else:
+      for byte in val:
+         total = (total << 8) | ord(byte)
+   return total
+
+def _encodeInteger(val):
+   'python integer'
+   if not isinstance(val, types.IntType) and not isinstance(val, types.LongType):
+      raise DerError, 'argument should be an integer'
+   if val == 0:
+      return chr(0x00)
+   else:
+      val2 = copy.deepcopy(val)
+      if val2 < 0:
+         val2 = -(val2+1)
+      bytes = []
+      byte = 0
+      while val2:
+         byte = val2 & 0xFF
+         bytes.append(byte)
+         val2 = val2 >> 8
+      # if we have no used up the last byte to represent the value we need
+      # to add one more on to show if this is negative of positive.  Also,
+      # due to adding 1 and inverting -1 would be 0 or if 0 is the encoding
+      # value, so bytes would empty and this would lead to and empty value
+      # and this would not be working properly.  Adding this null byte
+      # fixes this, since it is inverted to -1 and preserved for 0.
+      if byte & 0x80 or not bytes:
+         bytes.append(0x00)
+      if val < 0:
+         bytes = map( lambda x : x ^ 0xFF, bytes )
+      bytes.reverse()
+
+      return string.join(map(chr, bytes), '')
+
+def _decodeBitString(val):
+   'der encoded value not including tag or length'
+   if not isinstance(val, types.StringType):
+      raise DerError, 'argument should be a string'
+   bitmasks = [0x80,0x40,0x20,0x10,0x08,0x04,0x02,0x01]
+   unused = ord( val[0] )
+   bits = []
+   for byte in val[1:]:
+      for j in range(8):
+         if ord(byte) & bitmasks[j]:
+            bits.append(1)
+         else:
+            bits.append(0)
+   if unused == 0:
+      return tuple(bits)
+   else:
+      return tuple(bits[:-unused])
+ 
+def _encodeBitString(val):
+   'list of true/false objects ie [0,1,1,0,1,1]'
+   if not (isinstance(val, types.ListType) or isinstance(val, types.TupleType)):
+      raise DerError, 'argument should be a list or tuple'
+   bitmasks = [0x80,0x40,0x20,0x10,0x08,0x04,0x02,0x01]
+   bytes = []
+   fits, leftover = divmod(len(val), 8)
+   nobytes = fits
+   if leftover > 0:
+      nobytes = nobytes + 1
+   if leftover:
+      unused = 8 - leftover 
+   else:
+      unused = 0
+   bytes.append(unused)
+   for i in range(nobytes):
+      byte = 0
+      for j in range(8):
+         offset = j + i*8
+         if offset < len(val):
+            if val[offset]:
+               byte = byte | bitmasks[j]
+      bytes.append(byte)
+
+   return string.join(map(chr, bytes), '')
+
+def _decodeOid(val):
+   'der encoded value not including tag or length'
+   if not isinstance(val, types.StringType):
+      raise DerError, 'argument should be a string'
+   arc12 = ord( val[0] )
+   arc1, arc2 = divmod(arc12, 40)
+   oids = [arc1,arc2]
+
+   total = 0
+   for byte in val[1:]:
+      val = ord(byte)
+      if val & 0x80:
+         total = (total << 7) | (val ^ 0x80)
+      else:
+         total = (total << 7) | val
+         oids.append(total)
+         total = 0
+      
+   return tuple(oids)
+
+def _encodeOid(val):
+   'list of intgers'
+   if not (isinstance(val, types.ListType) or isinstance(val, types.TupleType)):
+      raise DerError, 'argument should be a list or tuple'
+   oids = []
+   oids.append( chr(40 * val[0] + val[1]) ) 
+   for val in val[2:]:
+      if val == 0:
+         oids.append( chr(0) )
+      else:
+         bytes = []
+         while val:
+            val, rem = divmod(val, 128)
+            bytes.append(rem | 0x80)
+         bytes[0] = bytes[0] ^ 0x80
+         bytes.reverse()
+         oids.append( string.join(map(chr, bytes), '') )
+
+   return string.join(oids, '')
+
+def _decodeSequence(val):
+   'der encoded value not including tag or length'
+   if not isinstance(val, types.StringType):
+      raise DerError, 'argument should be a string'
+   buf = cStringIO.StringIO(val)
+   buflen = len(val)
+   tvls = []
+   while buf.tell() < buflen:
+      t = _TlvIo(buf)
+      t.read()
+      tvls.append(t)
+   return tuple(tvls)
+
+def _encodeSequence(val):
+   'list of GenerlObjects'
+   if not (isinstance(val, types.ListType) or isinstance(val, types.TupleType)):
+      raise DerError, 'argument should be a list or tuple'
+   buf = cStringIO.StringIO()
+   for obj in val:
+      if obj or isinstance(obj, _GeneralObject):
+         obj.write(buf)
+      elif not obj.optional:
+         raise DerError, 'object not set which should be: %s' % obj
+         
+   return buf.getvalue()
+
+_addFragment('''
+<class>
+   <header>
+      <name>_GeneralObject</name>
+   </header>
+   <body>
+      <para>
+         <classname>_GeneralObject</classname> is the basis for all DER objects,
+         primitive or constructed.  It defines the basic behaviour of an
+         object which is serialised using the tag, length and value
+         approach of DER.  It is unlikely you would ever want to
+         instantiate one of these directly but I include a description
+         since many primatives don't override much of
+         <classname>_GeneralObject</classname>'s functions. 
+      </para>
+   </body>
+</class>
+''')
+
+class _GeneralObject(object):
+
+   _addFragment('''
+   <constructor>
+      <header>
+         <memberof>_GeneralObject</memberof>
+         <parameter>normclass</parameter>
+         <parameter>normform</parameter>
+         <parameter>normnumber</parameter>
+         <parameter>encRoutine</parameter>
+         <parameter>decRoutine</parameter>
+         <parameter>optional=0</parameter>
+         <parameter>default=''</parameter>
+      </header>
+      <body>
+         <para>
+            <parameter>normclass</parameter> is the class of the object,
+            ei: universal, application, context or private.
+            <parameter>normform</parameter> is the form of the object, ei
+            primitive or constructed.  <parameter>normnumber</parameter> is
+            the tag number of the object.
+            <parameter>encRoutine</parameter> is a function which takes a
+            value and encodes it according the appropriate DER rules.
+            <parameter>decRoutine</parameter> is a function which reads a
+            string value and returns a value which is more useful in
+            Python.  <parameter>optional</parameter> is a boolean
+            indicating if this object is optional.  The final parameter,
+            <parameter>default</parameter> is the base 64 encoded DER
+            value, which should be used as the default in leu of a value to
+            read or incase it is unset.
+         </para>
+      </body>
+   </constructor>
+   ''')
+
+   def __init__(self, normclass, normform, normnumber, encRoutine, decRoutine, optional=0, default=''):
+      if not isinstance(normclass, types.IntType):
+         raise DerError, 'nomrclass argument should be an integer : %s' % normclass
+      if not isinstance(normform, types.IntType):
+         raise DerError, 'normform argument should be an integer : %s' % normform
+      if not isinstance(normnumber, types.IntType):
+         raise DerError, 'normnumber argument should be an integer : %s' % normnumber
+      if not isinstance(encRoutine, types.FunctionType):
+         raise DerError, 'encRoutine argument should be an function : %s' % encRoutine
+      if not isinstance(decRoutine, types.FunctionType):
+         raise DerError, 'decRoutine argument should be an function : %s' % decRoutine 
+      if not isinstance(optional, types.IntType):
+         raise DerError, 'optional argument should be an integer : %s' % optional
+      if not isinstance(default, types.StringType):
+         raise DerError, 'default argument should be an String : %s' % default
+      self.normclass = normclass
+      self.normform = normform
+      self.normnumber = normnumber
+      self.encRoutine = encRoutine
+      self.decRoutine = decRoutine
+      self.value = None
+      self.optional = optional
+      self.default = default
+      self.reset()
+
+   def _ioSafe(self):
+      'is it safe to write this object'
+      if self.optional or self._isSet():
+         return 1
+      else:
+         return 0
+
+   def _isSet(self):
+      'are the values of this object set or not'
+      if self.value is not None:
+         return 1
+      else:
+         return 0
+
+   _addFragment('''
+   <method>
+      <header>
+         <memberof>_GeneralObject</memberof>
+         <name>reset</name>
+      </header>
+      <body>
+         <para>
+            This function re-initialises the object, clearing the value or
+            setting it to any default.
+         </para>
+      </body>
+   </method>
+   ''')
+   def reset(self):
+      self.value = None
+      if self.default:
+         buf = cStringIO.StringIO( base64.decodestring( self.default ) )
+         io = _TlvIo(buf)
+         io.read()
+         self.read(io)
+
+   _addFragment('''
+   <method>
+      <header>
+         <memberof>_GeneralObject</memberof>
+         <name>set</name>
+         <parameter>value</parameter>
+      </header>
+      <body>
+         <para>
+            This dosn't do much except store <parameter>value</parameter>,
+            presumably prior to writing the object.  The correct values to
+            use would be determined by the encoder or decoder this class is
+            instantiated with.  Be careful, there is some flexibility in
+            setting objects so you might find that once the object has been
+            written and read back in the value isn't identical.  A good
+            example would be anything which contains a sequence(list or
+            tuple), all sequence objects are returned as tuples.
+         </para>
+      </body>
+   </method>
+   ''')
+   def set(self, value):
+      if value is not None:
+         self.value = value
+
+   _addFragment('''
+   <method>
+      <header>
+         <memberof>_GeneralObject</memberof>
+         <name>get</name>
+      </header>
+      <body>
+         <para>
+            Gets the value stored presumably after reading the object.
+         </para>
+      </body>
+   </method>
+   ''')
+   def get(self):
+      return self.value
+
+   _addFragment('''
+   <method>
+      <header>
+         <memberof>_GeneralObject</memberof>
+         <name>implied</name>
+         <parameter>impclass</parameter>
+         <parameter>impform</parameter>
+         <parameter>impnumber</parameter>
+      </header>
+      <body>
+         <para>
+            This function is used to change how the tag is written or read
+            for a particular object and should be called in the constructor
+            for derived objects.  If you have an example of the structure you need to
+            process, Pete Gutmann's excellent
+            <application>dumpasn1</application> can be invaluable for
+            debugging objects.
+         </para>
+      </body>
+   </method>
+   ''')
+   def implied(self, impclass, impform, impnumber):
+      if not isinstance(impclass, types.IntType):
+         raise DerError, 'impclass argument should be an integer'
+      if not isinstance(impform, types.IntType):
+         raise DerError, 'impform argument should be an integer'
+      if not isinstance(impnumber, types.IntType):
+         raise DerError, 'impnumber argument should be an integer'
+      self.normclass = impclass
+      self.normform = impform
+      self.normnumber = impnumber
+
+   _addFragment('''
+   <method>
+      <header>
+         <memberof>_GeneralObject</memberof>
+         <name>read</name>
+         <parameter>io</parameter>
+      </header>
+      <body>
+         <para>
+            <parameter>io</parameter> should be a file like object.  If the
+            object being read matches the expected class, form and tag the
+            value is read and decoded using
+            <function>decRoutine</function>.  Else, if it has a default
+            that is read and stored.  
+         </para>
+         <para>
+            The return value of this function does not indicate success but
+            whether this TLV was processed successfully.  This bahaviour is
+            vital for processing constructed types since the object may be
+            optional or have a default.  Failure to decode would be indicated 
+            by an exception.  
+         </para>
+      </body>
+   </method>
+   ''')
+
+   def read(self, io=None):    
+
+      processDefOpt = 0
+      if io is None:
+         processDefOpt = 1
+      elif isinstance(io, _TlvIo):
+         if not io:
+            processDefOpt = 1
+      else:
+         pos = io.tell()
+         io.seek(0,2)
+         if io.tell():
+            io.seek(pos)
+         else:
+            processDefOpt = 1
+
+      if processDefOpt:
+         if self.optional or self.default:
+            self.reset()
+            return 0
+         else:
+            raise DerError, 'no TLV is available to read in non-optional/non-default object: %s' % repr(self)
+
+      if not isinstance(io, _TlvIo):
+         tmp = _TlvIo(io)
+         tmp.read()
+         io = tmp
+
+      if io.tagclass != self.normclass or io.tagform != self.normform or io.tagnumber != self.normnumber:
+         if self.default or self.optional:
+            self.reset()
+            return 0
+         else:
+            raise DerError, 'error in encoding, missing object:%s' % repr(self)
+      else:
+         derval = io.readValue()
+         self.value = self.decRoutine( derval )
+         return 1
+
+   _addFragment('''
+   <method>
+      <header>
+         <memberof>_GeneralObject</memberof>
+         <name>write</name>
+         <parameter>io</parameter>
+      </header>
+      <body>
+         <para>
+            If this object has not been set and is not optional and dosn't
+            have a default, a <classname>DerError</classname> exception will be raised
+         </para>
+         <para>
+            If no value has been set and this object is optional, nothing
+            is written.  If this object's value is equal to the default,
+            nothing is written as stipulated by DER.  Otherwise the value
+            is encoded and written.  
+         </para>
+      </body>
+   </method>
+   ''')
+
+   def write(self, file):
+      if not self._ioSafe():
+         raise DerError, 'object not set which must be: %s' % repr(self)
+      elif self.optional and self.value is None:
+         pass
+      else:
+         buf = cStringIO.StringIO()
+         io = _TlvIo(buf)
+         io.tagclass = self.normclass
+         io.tagform = self.normform
+         io.tagnumber = self.normnumber
+         derval = self.encRoutine( self.value )
+         io.length = len(derval)
+         io.write(derval)
+         if self.default:
+            if buf.getvalue() != base64.decodestring(self.default):
+               file.write( buf.getvalue() )
+         else:
+            file.write( buf.getvalue() )
+
+   _addFragment('''
+   <method>
+      <header>
+         <memberof>_GeneralObject</memberof>
+         <name>toString</name>
+      </header>
+      <body>
+         <para>
+            Encodes the value in DER and returns it as a string.
+         </para>
+      </body>
+   </method>
+   ''')
+
+   def toString(self):
+      buf = cStringIO.StringIO()
+      self.write(buf)
+      return buf.getvalue()
+
+   _addFragment('''
+   <method>
+      <header>
+         <memberof>_GeneralObject</memberof>
+         <name>fromString</name>
+      </header>
+      <body>
+         <para>
+            Decodes the string and sets the value of this object.
+         </para>
+      </body>
+   </method>
+   ''')
+
+   def fromString(self, value):
+      buf = cStringIO.StringIO(value)
+      self.read(buf)
+
+class Any(_GeneralObject):
+
+   def __init__(self):
+      self.value = None
+      self.normclass = None
+      self.normform = None
+      self.normnumber = None
+
+   def _ioSafe(self):
+      if self.optional or (self._isSet() and self.normclass is not None and self.normform is not None and self.normnumber is not None):
+         return 1
+      else:
+         return 0
+
+   def setTag(self, klass, form, number):
+      self.normclass = klass
+      self.normform = form
+      self.normnumber = number
+
+   def reset(self):
+      self.value = None
+
+   def get(self):
+      return self.value
+
+   def set(self, value):
+      self.value = value
+
+   def write(self,file):
+      if not self._ioSafe():
+         raise DerError, 'object not set which must be: %s' % repr(self)
+      elif self.optional and self.value is None:
+         pass
+      else:
+         buf = cStringIO.StringIO()
+         io = _TlvIo(buf)
+         io.tagclass = self.normclass
+         io.tagform = self.normform
+         io.tagnumber = self.normnumber
+         io.length = len(self.value)
+         io.write(self.value)
+         file.write(buf.getvalue())
+
+   def read(self, io=None):    
+
+      processDefOpt = 0
+      if io is None:
+         processDefOpt = 1
+      elif isinstance(io, _TlvIo):
+         if not io:
+            processDefOpt = 1
+      else:
+         pos = io.tell()
+         io.seek(0,2)
+         if io.tell():
+            io.seek(pos)
+         else:
+            processDefOpt = 1
+      if processDefOpt:
+         if self.optional or self.default:
+            self.reset()
+            return 0
+         else:
+            raise DerError, 'no TLV is available to read in non-optional/non-default object: %s' % repr(self)
+
+      if not isinstance(io, _TlvIo):
+         tmp = _TlvIo(io)
+         tmp.read()
+         io = tmp
+
+      self.value = io.readValue()
+      self.normclass = io.tagclass
+      self.normform = io.tagform
+      self.normnumber = io.tagnumber
+
+_addFragment('''
+<class>
+   <header>
+      <name>Boolean</name>
+      <super>_GeneralObject</super>
+   </header>
+   <body>
+      <para>
+         This object represents the ASN1 BOOLEAN type.  It can be set
+         with any object which can be tested for truth. 
+      </para>
+   </body>
+</class>
+''')
+
+class Boolean(_GeneralObject):                            # 0x01
+
+   _addFragment('''
+   <constructor>
+      <header>
+         <memberof>Boolean</memberof>
+         <parameter>optional=0</parameter>
+         <parameter>default=''</parameter>
+      </header>
+   </constructor>
+   ''')
+   def __init__(self, optional=0, default=''):
+      _GeneralObject.__init__(self, CLASS_UNIVERSAL, FORM_PRIMITIVE, TAG_BOOLEAN, _encodeBoolean, _decodeBoolean, optional, default)
+
+_addFragment('''
+<class>
+   <header>
+      <name>Integer</name>
+      <super>_GeneralObject</super>
+   </header>
+   <body>
+      <para>
+         This object represents the ASN1 INTEGER type.  It should be set
+         with a Python integer.
+      </para>
+   </body>
+</class>
+''')
+
+class Integer(_GeneralObject):                            # 0x02
+
+   _addFragment('''
+   <constructor>
+      <header>
+         <memberof>Integer</memberof>
+         <parameter>optional=0</parameter>
+         <parameter>default=''</parameter>
+      </header>
+   </constructor>
+   ''')
+   def __init__(self, optional=0, default=''):
+      _GeneralObject.__init__(self, CLASS_UNIVERSAL, FORM_PRIMITIVE, TAG_INTEGER, _encodeInteger, _decodeInteger, optional, default)
+
+_addFragment('''
+<class>
+   <header>
+      <name>BitString</name>
+      <super>_GeneralObject</super>
+   </header>
+   <body>
+      <para>
+         This object represents the ASN1 BIT STRING type.  It should be set
+         with a sequence of integers.  A non-zero number will set the bit,
+         zero will leave the bit unset.
+      </para>
+   </body>
+</class>
+''')
+
+class BitString(_GeneralObject):                          # 0x03
+
+   _addFragment('''
+   <constructor>
+      <header>
+         <memberof>BitString</memberof>
+         <parameter>optional=0</parameter>
+         <parameter>default=''</parameter>
+      </header>
+   </constructor>
+   ''')
+   def __init__(self, optional=0, default=''):
+      _GeneralObject.__init__(self, CLASS_UNIVERSAL, FORM_PRIMITIVE, TAG_BITSTRING, _encodeBitString, _decodeBitString, optional, default)
+
+_addFragment('''
+<class>
+   <header>
+      <name>AltBitString</name>
+      <super>_GeneralObject</super>
+   </header>
+   <body>
+      <para>
+         This object represents the ASN1 BIT STRING type.  It differs from
+         the first <classname>BitString</classname> in that it's coding
+         routines treat values as binary data and do not interpret the data
+         in any way.  Some application treat the
+         <classname>BIT STRING</classname> in the same way as
+         <classname>OCTET STRING</classname> type, hence this extra object.
+      </para>
+   </body>
+</class>
+''')
+
+class AltBitString(_GeneralObject):                       # 0x03
+
+   _addFragment('''
+   <constructor>
+      <header>
+         <memberof>AltBitString</memberof>
+         <parameter>optional=0</parameter>
+         <parameter>default=''</parameter>
+      </header>
+   </constructor>
+   ''')
+
+   def __init__(self, optional=0, default=''):
+      _GeneralObject.__init__(self, CLASS_UNIVERSAL, FORM_PRIMITIVE, TAG_BITSTRING, lambda x : chr(0)+x, lambda x : x[1:], optional, default)
+
+_addFragment('''
+<class>
+   <header>
+      <name>OctetString</name>
+      <super>_GeneralObject</super>
+   </header>
+   <body>
+      <para>
+         This object represents the ASN1 OCTET STRING type.  This object
+         can be set with any binary data.
+      </para>
+   </body>
+</class>
+''')
+class OctetString(_GeneralObject):                        # 0x04
+
+   _addFragment('''
+   <constructor>
+      <header>
+         <memberof>OctetString</memberof>
+         <parameter>optional=0</parameter>
+         <parameter>default=''</parameter>
+      </header>
+   </constructor>
+   ''')
+
+   def __init__(self, optional=0, default=''):
+      _GeneralObject.__init__(self, CLASS_UNIVERSAL, FORM_PRIMITIVE, TAG_OCTETSTRING, lambda x : x, lambda x : x, optional, default)
+
+_addFragment('''
+<class>
+   <header>
+      <name>Null</name>
+      <super>_GeneralObject</super>
+   </header>
+   <body>
+      <para>
+         This object represents the ASN1 NULL type.  There is no point in
+         setting this object, the value will always be ignored when it is
+         written out.
+      </para>
+   </body>
+</class>
+''')
+class Null(_GeneralObject):                               # 0x05
+
+   _addFragment('''
+   <constructor>
+      <header>
+         <memberof>Null</memberof>
+         <parameter>optional=0</parameter>
+         <parameter>default=''</parameter>
+      </header>
+   </constructor>
+   ''')
+
+   def __init__(self, optional=0, default=''):
+      _GeneralObject.__init__(self, CLASS_UNIVERSAL, FORM_PRIMITIVE, TAG_NULL, lambda x : '', lambda x : '', optional, default)
+      self.value = '' 
+
+   def _ioSafe(self):
+      return 1
+
+   def reset(self):
+      self.value =  ''
+
+_addFragment('''
+<class>
+   <header>
+      <name>Oid</name>
+      <super>_GeneralObject</super>
+   </header>
+   <body>
+      <para>
+         This object represents the ASN1 OID type.  This object should be
+         set with a list or tuple of integers defining an objects oid.
+         Please note that the first three arcs have a restricted set of
+         values, so encoding (5, 3, 7, 1) will produce bad results.
+      </para>
+   </body>
+</class>
+''')
+class Oid(_GeneralObject):                                # 0x06
+
+   _addFragment('''
+   <constructor>
+      <header>
+         <memberof>Oid</memberof>
+         <parameter>optional=0</parameter>
+         <parameter>default=''</parameter>
+      </header>
+   </constructor>
+   ''')
+
+   def __init__(self, optional=0, default=''):
+      _GeneralObject.__init__(self, CLASS_UNIVERSAL, FORM_PRIMITIVE, TAG_OID, _encodeOid, _decodeOid, optional, default)
+
+_addFragment('''
+<class>
+   <header>
+      <name>Enum</name>
+      <super>_GeneralObject</super>
+   </header>
+   <body>
+      <para>
+         This object represents the ASN1 ENUM type.  This should be set
+         using a Python integer, the meaning should be described in the
+         ASN1 document for the object you are encoding.
+      </para>
+   </body>
+</class>
+''')
+class Enum(_GeneralObject):                               # 0x0A
+
+   _addFragment('''
+   <constructor>
+      <header>
+         <memberof>Enum</memberof>
+         <parameter>optional=0</parameter>
+         <parameter>default=''</parameter>
+      </header>
+   </constructor>
+   ''')
+
+   def __init__(self, optional=0, default=''):
+      _GeneralObject.__init__(self, CLASS_UNIVERSAL, FORM_PRIMITIVE, TAG_ENUMERATED, _encodeInteger, _decodeInteger, optional, default)
+
+_addFragment('''
+<class>
+   <header>
+      <name>Utf8String</name>
+      <super>_GeneralObject</super>
+   </header>
+   <body>
+      <para>
+         This object represents the ASN1 UTF8String type.  This object
+         should be set with a string.  It is up to the application to ensure
+         it only contains valid characters for this type.
+      </para>
+   </body>
+</class>
+''')
+class Utf8String(_GeneralObject):                         # 0x0C
+
+   _addFragment('''
+   <constructor>
+      <header>
+         <memberof>Utf8String</memberof>
+         <parameter>optional=0</parameter>
+         <parameter>default=''</parameter>
+      </header>
+   </constructor>
+   ''')
+
+   def __init__(self, optional=0, default=''):
+      _GeneralObject.__init__(self, CLASS_UNIVERSAL, FORM_PRIMITIVE, TAG_UTF8STRING, lambda x : x, lambda x : x, optional, default)
+
+_addFragment('''
+<class>
+   <header>
+      <name>NumericString</name>
+      <super>_GeneralObject</super>
+   </header>
+   <body>
+      <para>
+         This object represents the ASN1 NumericString type.  This should
+  object should be set with a string.  It is up to the application to ensure
+  it only contains valid characters for this type.
+      </para>
+   </body>
+</class>
+''')
+class NumericString(_GeneralObject):                      # 0x12
+
+   _addFragment('''
+   <constructor>
+      <header>
+         <memberof>NumericString</memberof>
+         <parameter>optional=0</parameter>
+         <parameter>default=''</parameter>
+      </header>
+   </constructor>
+   ''')
+
+   def __init__(self, optional=0, default=''):
+      _GeneralObject.__init__(self, CLASS_UNIVERSAL, FORM_PRIMITIVE, TAG_NUMERICSTRING, lambda x : x, lambda x : x, optional, default)
+_addFragment('''
+<class>
+   <header>
+      <name>PrintableString</name>
+      <super>_GeneralObject</super>
+   </header>
+   <body>
+      <para>
+         This object represents the ASN1 PrintableString type.  This should
+  object should be set with a string.  It is up to the application to ensure
+  it only contains valid characters for this type.
+      </para>
+   </body>
+</class>
+''')
+class PrintableString(_GeneralObject):                    # 0x13
+
+   _addFragment('''
+   <constructor>
+      <header>
+         <memberof>PrintableString</memberof>
+         <parameter>optional=0</parameter>
+         <parameter>default=''</parameter>
+      </header>
+   </constructor>
+   ''')
+
+   def __init__(self, optional=0, default=''):
+      _GeneralObject.__init__(self, CLASS_UNIVERSAL, FORM_PRIMITIVE, TAG_PRINTABLESTRING, lambda x : x, lambda x : x, optional, default)
+
+_addFragment('''
+<class>
+   <header>
+      <name>T61String</name>
+      <super>_GeneralObject</super>
+   </header>
+   <body>
+      <para>
+         This object represents the ASN1 T61String type.  This object
+         should be set with a string.  It is up to the application to ensure
+         it only contains valid characters for this type.
+      </para>
+   </body>
+</class>
+''')
+class T61String(_GeneralObject):                          # 0x14
+
+   _addFragment('''
+   <constructor>
+      <header>
+         <memberof>T61String</memberof>
+         <parameter>optional=0</parameter>
+         <parameter>default=''</parameter>
+      </header>
+   </constructor>
+   ''')
+
+   def __init__(self, optional=0, default=''):
+      _GeneralObject.__init__(self, CLASS_UNIVERSAL, FORM_PRIMITIVE, TAG_T61STRING, lambda x : x, lambda x : x, optional, default)
+
+_addFragment('''
+<class>
+   <header>
+      <name>VideotexString</name>
+      <super>_GeneralObject</super>
+   </header>
+   <body>
+      <para>
+         This object represents the ASN1 VideotexString type.  This should
+  object should be set with a string.  It is up to the application to ensure
+  it only contains valid characters for this type.
+      </para>
+   </body>
+</class>
+''')
+class VideotexString(_GeneralObject):                     # 0x15
+
+   _addFragment('''
+   <constructor>
+      <header>
+         <memberof>VideotexString</memberof>
+         <parameter>optional=0</parameter>
+         <parameter>default=''</parameter>
+      </header>
+   </constructor>
+   ''')
+
+   def __init__(self, optional=0, default=''):
+      _GeneralObject.__init__(self, CLASS_UNIVERSAL, FORM_PRIMITIVE, TAG_VIDEOTEXSTRING, lambda x : x, lambda x : x, optional, default)
+
+_addFragment('''
+<class>
+   <header>
+      <name>IA5String</name>
+      <super>_GeneralObject</super>
+   </header>
+   <body>
+      <para>
+         This object represents the ASN1 IA5String type.  This object
+         should be set with a string.  It is up to the application to ensure
+         it only contains valid characters for this type.
+      </para>
+   </body>
+</class>
+''')
+class IA5String(_GeneralObject):                          # 0x16
+
+   _addFragment('''
+   <constructor>
+      <header>
+         <memberof>IA5String</memberof>
+         <parameter>optional=0</parameter>
+         <parameter>default=''</parameter>
+      </header>
+   </constructor>
+   ''')
+
+   def __init__(self, optional=0, default=''):
+      _GeneralObject.__init__(self, CLASS_UNIVERSAL, FORM_PRIMITIVE, TAG_IA5STRING, lambda x : x, lambda x : x, optional, default)
+
+_addFragment('''
+<class>
+   <header>
+      <name>UtcTime</name>
+      <super>_GeneralObject</super>
+   </header>
+   <body>
+      <para>
+         This object represents the ASN1 UTCTime type.  This object should
+         be set with a string of the general format YYMMDDhhmmssZ.  The
+         helper functions <function>time2utc</function> and
+         <function>utc2time</function> can be used to handle the conversion
+         from an integer to a string and back.
+      </para>
+   </body>
+</class>
+''')
+class UtcTime(_GeneralObject):                            # 0x17
+
+   _addFragment('''
+   <constructor>
+      <header>
+         <memberof>UtcTime</memberof>
+         <parameter>optional=0</parameter>
+         <parameter>default=''</parameter>
+      </header>
+   </constructor>
+   ''')
+
+   def __init__(self, optional=0, default=''):
+      _GeneralObject.__init__(self, CLASS_UNIVERSAL, FORM_PRIMITIVE, TAG_UTCTIME, lambda x : x, lambda x : x, optional, default)
+
+_addFragment('''
+<class>
+   <header>
+      <name>GeneralizedTime</name>
+      <super>_GeneralObject</super>
+   </header>
+   <body>
+      <para>
+         This object represents the ASN1 GeneralizedTime type.  This object should
+         be set with a string of the general format YYYYMMDDhhmmssZ.  The
+         helper functions <function>time2utc</function> and
+         <function>utc2time</function> can be used to handle the conversion
+         from an integer to a string and back.
+      </para>
+   </body>
+</class>
+''')
+class GeneralizedTime(_GeneralObject):                    # 0x18
+
+   _addFragment('''
+   <constructor>
+      <header>
+         <memberof>GeneralizedTime</memberof>
+         <parameter>optional=0</parameter>
+         <parameter>default=''</parameter>
+      </header>
+   </constructor>
+   ''')
+
+
+   def __init__(self, optional=0, default=''):
+      _GeneralObject.__init__(self, CLASS_UNIVERSAL, FORM_PRIMITIVE, TAG_GENERALIZEDTIME, lambda x : x, lambda x : x, optional, default)
+
+_addFragment('''
+<class>
+   <header>
+      <name>GraphicString</name>
+      <super>_GeneralObject</super>
+   </header>
+   <body>
+      <para>
+         This object represents the ASN1 GraphicString type.  This should
+         object should be set with a string.  It is up to the application to
+         ensure it only contains valid characters for this type.
+      </para>
+   </body>
+</class>
+''')
+class GraphicString(_GeneralObject):                      # 0x19
+
+   _addFragment('''
+   <constructor>
+      <header>
+         <memberof>GraphicString</memberof>
+         <parameter>optional=0</parameter>
+         <parameter>default=''</parameter>
+      </header>
+   </constructor>
+   ''')
+
+   def __init__(self, optional=0, default=''):
+      _GeneralObject.__init__(self, CLASS_UNIVERSAL, FORM_PRIMITIVE, TAG_GRAPHICSTRING, lambda x : x, lambda x : x, optional, default)
+
+_addFragment('''
+<class>
+   <header>
+      <name>VisibleString</name>
+      <super>_GeneralObject</super>
+   </header>
+   <body>
+      <para>
+         This object represents the ASN1 VisibleString type.  This should
+         object should be set with a string.  It is up to the application to
+         ensure it only contains valid characters for this type.
+      </para>
+   </body>
+</class>
+''')
+class VisibleString(_GeneralObject):                      # 0xC0
+ 
+   _addFragment('''
+   <constructor>
+      <header>
+         <memberof>VisibleString</memberof>
+         <parameter>optional=0</parameter>
+         <parameter>default=''</parameter>
+      </header>
+   </constructor>
+   ''')
+
+   def __init__(self, optional=0, default=''):
+      _GeneralObject.__init__(self, CLASS_UNIVERSAL, FORM_PRIMITIVE, TAG_VISIBLESTRING, lambda x : x, lambda x : x, optional, default)
+
+_addFragment('''
+<class>
+   <header>
+      <name>GeneralString</name>
+      <super>_GeneralObject</super>
+   </header>
+   <body>
+      <para>
+         This object represents the ASN1 GeneralString type.  This should
+         object should be set with a string.  It is up to the application to
+         ensure it only contains valid characters for this type.
+      </para>
+   </body>
+</class>
+''')
+class GeneralString(_GeneralObject):                      # 0xC0
+
+   _addFragment('''
+   <constructor>
+      <header>
+         <memberof>GeneralString</memberof>
+         <parameter>optional=0</parameter>
+         <parameter>default=''</parameter>
+      </header>
+   </constructor>
+   ''')
+
+   def __init__(self, optional=0, default=''):
+      _GeneralObject.__init__(self, CLASS_UNIVERSAL, FORM_PRIMITIVE, TAG_GENERALSTRING, lambda x : x, lambda x : x, optional, default)
+
+_addFragment('''
+<class>
+   <header>
+      <name>UniversalString</name>
+      <super>_GeneralObject</super>
+   </header>
+   <body>
+      <para>
+         This object represents the ASN1 UniversalString type.  This should
+         object should be set with a string.  It is up to the application to
+         ensure it only contains valid characters for this type.
+      </para>
+   </body>
+</class>
+''')
+class UniversalString(_GeneralObject):                    # 0xC0
+
+   _addFragment('''
+   <constructor>
+      <header>
+         <memberof>UniversalString</memberof>
+         <parameter>optional=0</parameter>
+         <parameter>default=''</parameter>
+      </header>
+   </constructor>
+   ''')
+
+   def __init__(self, optional=0, default=''):
+      _GeneralObject.__init__(self, CLASS_UNIVERSAL, FORM_PRIMITIVE, TAG_UNIVERSALSTRING, lambda x : x, lambda x : x, optional, default)
+
+_addFragment('''
+<class>
+   <header>
+      <name>BmpString</name>
+      <super>_GeneralObject</super>
+   </header>
+   <body>
+      <para>
+         This object represents the ASN1 BMPString type.  This object
+         should be set with a string.  It is up to the application to ensure
+         it only contains valid characters for this type.
+      </para>
+   </body>
+</class>
+''')
+class BmpString(_GeneralObject):                          # 0xC0
+ 
+   _addFragment('''
+   <constructor>
+      <header>
+         <memberof>BmpString</memberof>
+         <parameter>optional=0</parameter>
+         <parameter>default=''</parameter>
+      </header>
+   </constructor>
+   ''')
+
+   def __init__(self, optional=0, default=''):
+      _GeneralObject.__init__(self, CLASS_UNIVERSAL, FORM_PRIMITIVE, TAG_BMPSTRING, lambda x : x, lambda x : x, optional, default)
+
+_addFragment('''
+<class>
+   <header>
+      <name>Sequence</name>
+      <super>_GeneralObject</super>
+   </header>
+   <body>
+      <para>
+         This object represents the ASN1 SEQUENCE type.  
+      </para>
+   </body>
+</class>
+''')
+class Sequence(_GeneralObject):                           # 0x10
+
+   _addFragment('''
+   <constructor>
+      <header>
+         <memberof>Sequence</memberof>
+         <super>_GeneralObject</super>
+         <parameter>contents</parameter>
+         <parameter>optional=0</parameter>
+         <parameter>default=''</parameter>
+      </header>
+      <body>
+         <para>
+            The <parameter>contents</parameter> should be a list or tuple containing
+            the contents of the sequence.
+            Two important members are initialised this this constructor.
+            First <constant>self.next</constant> this is used to keep track
+            of which TLVs in this sequence has been read succesfully.  The second,
+            <constant>self.contents</constant> should be set to the list of
+            objects stored in this sequence.  Note that the order they are
+            specified in is the order in which they are written or read.
+         </para>
+      </body>
+   </constructor>
+   ''')
+
+   def __init__(self, contents, optional=0, default=''):
+      self.contents = contents
+      self.next = 0
+      _GeneralObject.__init__(self, CLASS_UNIVERSAL, FORM_CONSTRUCTED, TAG_SEQUENCE, _encodeSequence, _decodeSequence, optional, default)
+
+   def _childRead(self, obj):
+      if self.next < len(self.value):
+         if obj.read( self.value[self.next] ):
+            self.next += 1
+      else:
+         obj.read()
+
+   _addFragment('''
+   <method>
+      <header>
+         <memberof>Sequence</memberof>
+         <name>readContents</name>
+         <parameter>io</parameter>
+         <parameter>contents</parameter>
+      </header>
+      <body>
+         <para>
+            This function implements basic SEQUENCE like reading behaviour.
+            It will attempt to read each of the objects in
+            <parameter>contents</parameter> in turn from
+            <parameter>io</parameter>.  It exists as a function, separate
+            from <function>read</function> for the benefit of the SEQUENCE
+            OF implementation.
+         </para>
+         <para>
+            The TLV of this SEQUENCE is read and parsed into a list of
+            TLVs, which are store in <constant>self.value</constant>, by
+            <classname>_GeneralObject</classname>.<function>read</function>.
+            Then <function>read</function> is called on each member to
+            process each TLV in turn.  The next TLV is moved onto only when
+            a member returns TRUE from the read call.
+         </para>
+      </body>
+   </method>
+   ''')
+
+   def readContents(self, io, contents):    
+      if _GeneralObject.read( self, io ):
+         for item in contents:
+            Sequence._childRead( self, item )
+         return 1
+      else:
+         return 0
+
+   _addFragment('''
+   <method>
+      <header>
+         <memberof>Sequence</memberof>
+         <name>read</name>
+         <parameter>io</parameter>
+      </header>
+      <body>
+         <para>
+            Most of the logic for reading is implemented in <function>readContents</function>
+            so it can be reused for <classname>SequenceOf</classname>'s
+            <function>read</function> function.
+         </para>
+      </body>
+   </method>
+   ''')
+
+   def read(self, io=None):    
+      self.next = 0
+      return self.readContents(io, self.contents)
+
+   _addFragment('''
+   <method>
+      <header>
+         <memberof>Sequence</memberof>
+         <name>write</name>
+         <parameter>file</parameter>
+      </header>
+      <body>
+         <para>
+            <constant>self.value</constant> is set to the contents of this
+            SEQUENCE and then written by calling
+            <classname>_GeneralObject</classname>.<function>write</function>
+            whos encoder will call <function>write</function> of
+            each element in the list of contents in turn.
+         </para>
+      </body>
+   </method>
+   ''')
+
+   def write(self, file):
+      if self._ioSafe(): 
+         if self._isSet(): 
+            _GeneralObject.set( self, self.contents )
+            _GeneralObject.write( self, file )
+      elif self.optional:
+         pass
+      else:
+         prob = self.findUnset()
+         raise DerError, '%s is not in a state which can be written, %s is unset' % (repr(self), repr(prob) )
+
+   _addFragment('''
+   <method>
+      <header>
+         <memberof>Sequence</memberof>
+         <name>set</name>
+         <parameter>values</parameter>
+      </header>
+      <body>
+         <para>
+            Accessing and setting values for ASN1 objects is a bit of a
+            thorny issue.  The problem stems from the arbitrary complexity
+            of the data and the possible levels of nesting, which in
+            practice are used and are quite massive.  Designing a good general
+            approach is a bit tricky, perhaps nearly
+            impossible.  I choose to use a most compact
+            form which is excellent for simple objects and is very concise.
+         </para>
+         <para>
+            <parameter>value</parameter> should be a list or tuple of
+            values.  Each element of the list (or tuple) will be used in
+            turn to set a member.  Defaults can be specified by using the
+            default value itself or <constant>None</constant>.  Hence, for
+            SEQUENCES of SEQUENCES, SEQUENCES OF, SET and so on
+            <parameter>values</parameter> should consist of nested lists or
+            tuples.  Look at the ASN1 specs for that object to figure out
+            exactly what these should look like.
+         </para>
+      </body>
+   </method>
+   ''')
+
+   def set(self, values):
+      if self.contents is None:
+         raise DerError, 'the contents attribute should be set before using this object'
+      if not( isinstance(values, types.ListType) or isinstance(values, types.TupleType) ):
+         raise DerError, 'a sequence should be set with a list or tuple of values' 
+      if len(values) != len(self.contents):
+         raise DerError, 'wrong number of values have been supplied to set %s. Expecting %i, got %i' % \
+                  (self.__class__.__name__, len(self.contents), len(values) )
+
+      i = 0
+      for val in values:
+         self.contents[i].set(val) 
+         i = i + 1
+
+   _addFragment('''
+   <method>
+      <header>
+         <memberof>Sequence</memberof>
+         <name>get</name>
+      </header>
+      <body>
+         <para>
+            A tuple of the values of the contents of this sequence will be
+            returned.  Hence, for SEQUENCES of SEQUENCES, SEQUENCES OF, SET
+            and so on nested tuples will be returned.
+            <function>get</function> always returns tuples even if a list
+            was used to set and object.
+         </para>
+      </body>
+   </method>
+   ''')
+
+   def get(self):
+      if self.contents is None:
+         return _GeneralObject.get(self)   
+      else:
+         results = []
+         for obj in self.contents:
+            results.append( obj.get() )
+         return tuple(results)
+
+   def reset(self):
+      if self.contents is None:
+         raise DerError, 'this object has no members to set'
+      self.next = 0
+      for obj in self.contents:
+         obj.reset() # clear all child objects prior to possible setting
+                     # via default
+      _GeneralObject.reset(self)
+
+   def _isSet(self):
+      if self.contents is None:
+         raise DerError, 'this object has no members to set'
+      for obj in self.contents:
+         if not obj._ioSafe():
+            return 0
+      return 1
+
+   def findUnset(self):
+      if self.contents is None:
+         raise DerError, 'this object has no members to check'
+      for obj in self.contents:
+         if not obj._ioSafe():
+            return obj
+
+   def _ioSafe(self):
+      if self.optional or self._isSet():
+         return 1
+      else:
+         for obj in self.contents:
+            if not obj._ioSafe():
+               return 0
+         return 1
+
+_addFragment('''
+<class>
+   <header>
+      <name>SequenceOf</name>
+      <super>Sequence</super>
+   </header>
+   <body>
+      <para>
+         This object represents the ASN1 SEQUENCE OF construct.  
+      </para>
+   </body>
+</class>
+''')           
+class SequenceOf(Sequence):
+
+   _addFragment('''
+   <constructor>
+      <header>
+         <memberof>SequenceOf</memberof>
+         <super>Sequence</super>
+         <parameter>contains</parameter>
+         <parameter>optional=0</parameter>
+         <parameter>default=''</parameter>
+      </header>
+      <body>
+         <para>
+            The <parameter>contains</parameter> should be the constructor
+            for the objects which this SEQUENCE OF contains.
+         </para>
+      </body>
+   </constructor>
+   ''')
+
+   def __init__(self, contains, optional=0, default=''):
+      self.contains = contains
+      self.sequenceOf = []
+      Sequence.__init__(self, [], optional, default)
+
+   def _ioSafe(self):
+      return 1
+
+   def reset(self):
+      if self.contents is None:
+         raise DerError, 'this object has no members to set'
+      self.next = 0
+      self.sequenceOf = []
+      _GeneralObject.reset(self)
+
+   def _isSet(self):
+      if self.sequenceOf:
+         for obj in self.contents:
+            if not obj._ioSafe():
+               return 0
+         return 1
+      else:
+         return 0
+
+   def set(self, values):
+      if isinstance(values, types.NoneType):
+         return
+      objects = []
+      for val in values:
+         obj = self.contains()
+         obj.set(val)
+         objects.append(obj)
+      self.sequenceOf = objects
+
+   def get(self):
+      results = []
+      for obj in self.sequenceOf:
+         results.append( obj.get() )
+      return tuple(results)
+
+   def read(self, io=None):    
+      self.sequenceOf = []
+      self.next = 0
+      if _GeneralObject.read( self, io ):
+         for tagio in _GeneralObject.get(self):
+            value = self.contains()
+            value.read(tagio)
+            self.sequenceOf.append(value)
+         return 1
+      else:
+         return 0
+
+   def write(self, file):
+      if not self._isSet() and self.optional: 
+         pass
+      else:
+         _GeneralObject.set( self, self.sequenceOf )
+         _GeneralObject.write( self, file )
+
+   def __len__(self):
+      return len(self.sequenceOf)
+
+   def __getitem__(self, key):
+      return self.sequenceOf[key]
+
+   def __iter__(self):
+      for i in self.sequenceOf:
+         yield(i)
+
+   def __contains__(self, item):
+      return item in self.sequenceOf
+
+_addFragment('''
+<class>
+   <header>
+      <name>Set</name>
+      <super>Sequence</super>
+   </header>
+   <body>
+      <para>
+         This object represents the ASN1 Set type.  
+      </para>
+   </body>
+</class>
+''')
+class Set(Sequence):                                     # 0x11
+ 
+   _addFragment('''
+   <constructor>
+      <header>
+         <memberof>Set</memberof>
+         <super>Sequence</super>
+         <parameter>contents</parameter>
+         <parameter>optional=0</parameter>
+         <parameter>default=''</parameter>
+      </header>
+      <body>
+         <para>
+            The <parameter>contents</parameter> should be a list containing
+            the contents of the sequence.
+         </para>
+      </body>
+   </constructor>
+   ''')
+
+   def __init__(self, contents, optional=0, default=''):
+      Sequence.__init__(self, contents, optional, default)
+      self.normnumber = TAG_SET
+
+_addFragment('''
+<class>
+   <header>
+      <name>SetOf</name>
+      <super>SequenceOf</super>
+   </header>
+   <body>
+      <para>
+         This object represents the ASN1 SET OF construct.  
+      </para>
+   </body>
+</class>
+''')
+class SetOf(SequenceOf):
+
+   _addFragment('''
+   <constructor>
+      <header>
+         <memberof>SetOf</memberof>
+         <super>SequenceOf</super>
+         <parameter>contains</parameter>
+         <parameter>optional=0</parameter>
+         <parameter>default=''</parameter>
+      </header>
+      <body>
+         <para>
+            The <parameter>contains</parameter> should be the constructor
+            for the objects which this SET OF contains.
+         </para>
+      </body>
+   </constructor>
+   ''')
+
+   def __init__(self, contains, optional=0, default=''):
+      SequenceOf.__init__(self, contains, optional, default)
+      self.normnumber = TAG_SET
+
+_addFragment('''
+<class>
+   <header>
+      <name>Explicit</name>
+      <super>Sequence</super>
+   </header>
+   <body>
+      <para>
+         Explicit objects support the DER concept of explicit tagging.  In
+         general they behave just like a SEQUENCE which must have only one
+         element.  See below for other differences.
+      </para>
+   </body>
+</class>
+''')
+class Explicit(Sequence):           
+
+   _addFragment('''
+   <constructor>
+      <header>
+         <memberof>Explicit</memberof>
+         <super>Sequence</super>
+         <parameter>expclass</parameter>
+         <parameter>expform</parameter>
+         <parameter>expnumber</parameter>
+         <parameter>contents</parameter>
+         <parameter>optional=0</parameter>
+         <parameter>default=''</parameter>
+      </header>
+      <body>
+         <para>
+            <parameter>expclass</parameter>,
+            <parameter>expform</parameter>,
+            <parameter>expnumber</parameter> should be as
+            specified in the ASN1 documentation for this object.
+            <parameter>contents</parameter> should be an object instance
+            such as <classname>Integer</classname>,
+            <classname>Oid</classname> or a derived object which supports
+            the <classname>_GeneralObjec</classname> interface.
+         </para>
+      </body>
+   </constructor>
+   ''')
+
+   def __init__(self, expclass, expform, expnumber, contents, optional=0, default=''):
+      self.contents = [contents]
+      self.next = 0
+      _GeneralObject.__init__(self, expclass, expform, expnumber, _encodeSequence, _decodeSequence, optional, default)
+
+   _addFragment('''
+   <method>
+      <header>
+         <memberof>Explicit</memberof>
+         <name>set</name>
+         <parameter>value</parameter>
+      </header>
+      <body>
+         <para>
+            <parameter>value</parameter> is passed direct to
+            <function>set</function> of the explicit object, so it should
+            not be placed in a list or tuple(unless you are setting a constructed
+            object).  
+         </para>
+      </body>
+   </method>
+   ''')
+   def set(self, value):
+      return Sequence.set(self, [value])
+
+   _addFragment('''
+   <method>
+      <header>
+         <memberof>Explicit</memberof>
+         <name>get</name>
+      </header>
+      <body>
+         <para>
+            The value of explicit object is returned and not
+            put in a tuple.   
+         </para>
+      </body>
+   </method>
+   ''')
+   def get(self):
+      return Sequence.get(self)[0]
+
+_addFragment('''
+<class>
+   <header>
+      <name>Choice</name>
+   </header>
+   <body>
+      <para>
+         This object represents the ASN1 Choice type.  
+      </para>
+   </body>
+</class>
+''')
+class Choice(object):
+
+   _addFragment('''
+   <constructor>
+      <header>
+         <memberof>Choice</memberof>
+         <parameter>choices</parameter>
+         <parameter>optional=0</parameter>
+         <parameter>default=''</parameter>
+      </header>
+      <body>
+         <para>
+            <parameter>choices</parameter> should be a dictionary of 
+            objects which support the <classname>_GeneralObject</classname>
+            interface.  The key being the name of the choice specified in the
+            ASN1 documentation.  <parameter>optional</parameter> is a boolean
+            indicating if this object is optional.  The final parameter,
+            <parameter>default</parameter> is the base 64 encoded DER
+            value, which should be used as the default in leu of a value to
+            read or incase it is unset.  If neither
+            <parameter>optional</parameter> or
+            <parameter>default</parameter> is not set then the first choice
+            which is optional or has a default will be honored.
+         </para>
+      </body>
+   </constructor>
+   ''')
+
+   def __init__(self, choices, optional=0, default=''):
+      self.value = None
+      self.choices = choices
+      self.optional = optional
+      self.default = default
+      self.choice = None
+      self.reset()
+
+   def _ioSafe(self):
+      if self.optional or self._isSet():
+         return 1
+      elif self.choice and self.choices[ self.choice ]._ioSafe():
+         return 1
+      else:
+         return 0
+
+   def _isSet(self):
+      if self.choice and self.choices[self.choice]._isSet():
+         return 1
+      else:
+         return 0
+
+   _addFragment('''
+   <method>
+      <header>
+         <memberof>Choice</memberof>
+         <name>reset</name>
+      </header>
+      <body>
+         <para>
+            This function re-initialises the object, clearing the value or
+            setting it to any default.
+         </para>
+      </body>
+   </method>
+   ''')
+   def reset(self):
+      self.value = None
+      self.choice = None
+      if self.default:
+         buf = cStringIO.StringIO( base64.decodestring( self.default ) )
+         io = _TlvIo(buf)
+         io.read()
+         self.read(io)
+      else:
+         for key in self.choices.keys():
+            self.choices[key].reset()
+            if self.choices[key]._ioSafe():
+               self.choice = key
+               break;
+            
+
+   _addFragment('''
+   <method>
+      <header>
+         <memberof>Choice</memberof>
+         <name>set</name>
+         <parameter>value</parameter>
+      </header>
+      <body>
+         <para>
+            <parameter>value</parameter> should be a list or tuple with two
+            elements. The first value should be the name of the choice to
+            be set and the second the value to set it with.
+         </para>
+      </body>
+   </method>
+   ''')
+   def set(self, val):
+      if val is None:
+         return
+      if not (isinstance(val, types.ListType) or isinstance(val, types.TupleType)):
+         raise DerError, 'argument should be a list or tuple'
+      if not self.choices.has_key( val[0] ):
+         raise DerError, 'unknown choice: %s' % val[0]
+      self.choices[ val[0] ].set(val[1])
+      self.choice = val[0]
+
+   _addFragment('''
+   <method>
+      <header>
+         <memberof>Choice</memberof>
+         <name>get</name>
+      </header>
+      <body>
+         <para>
+            This function will return tuple with two elements. The first
+            value will be the name of the choice which was set and the second
+            the value it was set to.
+         </para>
+      </body>
+   </method>
+   ''')
+
+   def get(self):
+      if self._isSet():
+         return (self.choice, self.choices[ self.choice ].get())
+      else:
+         return None
+
+   _addFragment('''
+   <method>
+      <header>
+         <memberof>Choice</memberof>
+         <name>toString</name>
+      </header>
+      <body>
+         <para>
+            Encodes the value in DER and returns it as a string.
+         </para>
+      </body>
+   </method>
+   ''')
+
+   def toString(self):
+      buf = cStringIO.StringIO()
+      self.write(buf)
+      return buf.getvalue()
+
+   _addFragment('''
+   <method>
+      <header>
+         <memberof>Choice</memberof>
+         <name>fromString</name>
+      </header>
+      <body>
+         <para>
+            Decodes the string and sets the value of this object.
+         </para>
+      </body>
+   </method>
+   ''')
+
+   def fromString(self, value):
+      buf = cStringIO.StringIO(value)
+      self.read(buf)
+
+   _addFragment('''
+   <method>
+      <header>
+         <memberof>Choice</memberof>
+         <name>read</name>
+         <parameter>io</parameter>
+      </header>
+      <body>
+         <para>
+            <parameter>io</parameter> should be a file like object.  If the
+            object being read matches the expected class, form and tag the
+            value is read and decoded using
+            <function>decRoutine</function>.  Else, if it has a default
+            that is read and stored.  
+         </para>
+         <para>
+            The return value of this function does not indicate success but
+            whether this TLV was processed successfully.  This bahaviour is
+            vital for processing constructed types since the object may be
+            optional or have a default.  Failure to decode would be indicated 
+            by an exception.  
+         </para>
+      </body>
+   </method>
+   ''')
+
+   def _readChoices(self, io):
+      for key in self.choices.keys():
+         try:
+            readindicator = self.choices[key].read(io)
+            self.choice = key
+            break;
+         except DerError:
+            if DEBUG:
+               traceback.print_exc()
+      return readindicator
+ 
+   def read(self, io=None):    
+
+      self.choice = None
+      processDefOpt = 0
+      readindicator = 0
+
+      if io is None:
+         processDefOpt = 1
+      elif isinstance(io, _TlvIo):
+         if not io:
+            processDefOpt = 1
+      else:
+         pos = io.tell()
+         io.seek(0,2)
+         if io.tell():
+            io.seek(pos)
+         else:
+            processDefOpt = 1
+
+      if processDefOpt:
+         if self.optional or self.default:
+            self.reset()
+            return 0
+         else:
+            readindicator = self._readChoices(io)
+            for key in self.choices.keys():
+               try:
+                  readindicator = self.choices[key].read(io)
+                  self.choice = key
+                  break;
+               except DerError:
+                  if DEBUG:
+                     traceback.print_exc()
+            if not self._isSet():
+               raise DerError, 'no TLV is available to read in non-optional/non-default object: %s' % repr(self)
+            else:
+               return readindicator
+
+      if not isinstance(io, _TlvIo):
+         tmp = _TlvIo(io)
+         tmp.read()
+         io = tmp
+
+      for key in self.choices.keys():
+         try:
+            if self.choices[key].read(io):
+               self.choice = key
+               readindicator = 1
+               break;
+         except DerError:
+            if DEBUG:
+               traceback.print_exc()
+ 
+      if not self._isSet():
+         self.reset()
+      else:
+         return readindicator
+
+   _addFragment('''
+   <method>
+      <header>
+         <memberof>Choice</memberof>
+         <name>write</name>
+         <parameter>file</parameter>
+      </header>
+      <body>
+         <para>
+            If this object has not been set and is not optional and dosn't
+            have a default, a <classname>DerError</classname> exception will be raised
+         </para>
+         <para>
+            If no value has been set and this object is optional, nothing
+            is written.  If this object's value is equal to the default,
+            nothing is written as stipulated by DER.  Otherwise the value
+            is encoded and written.  
+         </para>
+      </body>
+   </method>
+   ''')
+   def write(self,file):
+      if self.optional and not self.choice:
+         pass
+      elif not self.choice:
+         raise DerError, 'choice not set'
+      elif self.choice:
+         if self.default:
+            defval = base64.decodestring( self.default )
+            if defval != self.choices[ self.choice ].toString():
+               self.choices[ self.choice ].write(file)
+         else:
+            self.choices[ self.choice ].write(file)
+      else:
+         raise DerError, 'an internal error has occured: %s' % repr(self)
+
+