Help on module hvdi.crypt:

NAME
    hvdi.crypt - HawkEncrypt API Python bindings by Dalen Bernaca

DESCRIPTION
    hcrypt.c Version: 0.91 beta
    crypt.py Version: 1.0  beta
    
    HawkCrypt is a cryptographic library for password protecting data. It uses MD5
    to produce 128 bit encryption keys and random 128 bit (16 byte) salt values.
    Blowfish is used to perform 128 bit encryption. It also provides MD5 hashing
    to add a 32 bit message authentication code (MAC) to packets using a shared
    password. The MAC is separate from encryption so you can authenticate without
    encrypting if you choose. The 32 bit MAC is created by folding the 128 bit MD5
    hash down to 32 bits.
    
    If you want to use encryption with a MAC, I suggest you encrypt then add the
    MAC. That way you can validate before you decrypt and save some CPU cycles if
    you need to discard an invalid packet.
    
    * Higher level encryption classes are added by Dalen
      to simplify use of the encryption/decryption and
      provide more Pythonic interface.

CTYPES FUNCTIONS
    c_long AuthenticatePacket(LP_c_ubyte _in, c_long buflen, LP_hcrypt_key key)
     |  int AuthenticatePacket(unsigned char *in, int buflen, hcrypt_key *key)
     |    Using key, compares the MD5 hash with the last 4 bytes of in. If they match it
     |    returns 1, otherwise it returns 0. Make sure you either discard or do not use
     |    the last 4 bytes of the packet since they were added by SignPacket.
    
    DecryptPacket(LP_c_ubyte _in, LP_c_ubyte out, c_long buflen, LP_hcrypt_key key)
     |  void DecryptPacket(unsigned char *in, unsigned char *out, int buflen,
     |                           hcrypt_key *key)
     |    Decrypts a packet from in to out. buflen is the number of bytes to decrypt.
     |    in and out may be the same buffer.
    
    DecryptStream(LP_c_ubyte _in, LP_c_ubyte out, c_long buflen, LP_hcrypt_key key)
     |  void DecryptStream(unsigned char *in, unsigned char *out, int buflen,
     |                           hcrypt_key *key)
     |    Decrypts a byte stream from in to out. buflen is the number of bytes to decrypt.
     |    This should only be used for files, TCP streams, or other reliable streams.
     |    in and out may be the same buffer.
    
    DeleteKey(LP_hcrypt_key key)
     |  void DeleteKey(hcrypt_key *key)
     |    Deletes the key.
    
    DeleteSalt(LP_hcrypt_salt salt)
     |  void DeleteSalt(hcrypt_salt *salt)
     |    Deletes the salt.
    
    EncryptPacket(LP_c_ubyte _in, LP_c_ubyte out, c_long buflen, LP_hcrypt_key key)
     |  void EncryptPacket(unsigned char *in, unsigned char *out, int buflen,
     |                           hcrypt_key *key)
     |    Encrypts a packet from in to out. buflen is the number of bytes to encrypt.
     |    in and out may be the same buffer.
    
    EncryptStream(LP_c_ubyte _in, LP_c_ubyte out, c_long buflen, LP_hcrypt_key key)
     |  void EncryptStream(unsigned char *in, unsigned char *out, int buflen,
     |                           hcrypt_key *key)
     |    Encrypts a byte stream from in to out. buflen is the number of bytes to encrypt.
     |    This should only be used for files, TCP streams, or other reliable streams.
     |    in and out may be the same buffer.
    
    LP_hcrypt_key NewKey(String password, LP_hcrypt_salt salt)
     |  hcrypt_key* NewKey(const char *password, const hcrypt_salt* salt)
     |    Creates an encryption key from a password and an optional salt. Both the
     |    sender and receiver must use the same password and optional salt to create
     |    the key. The salt is created by hcryptNewSalt and sent to each
     |    client. If salt is None then only the password will be used to create the key,
     |    and it will be easier for a hacker to use a dictionary attack.
    
    LP_hcrypt_salt NewSalt()
     |  hcrypt_salt* NewSalt(void)
     |    Creates a salt value (or salt for short) that can be used with NewKey()
     |    to create hacker resistant keys. The hcrypt_salt is an array of 16 unsigned
     |    bytes (128 bits). The creator of the salt must send it to the other clients
     |    so that they may use it along with the password to create the key.
    
    SignPacket(LP_c_ubyte _in, c_long buflen, LP_hcrypt_key key)
     |  void SignPacket(unsigned char *in, int buflen, hcrypt_key *key)
     |    Using key, appends a 4 byte MD5 hash to the end of in. You MUST make sure
     |    that it is long enough to store 4 more bytes, and make sure you add 4 bytes
     |    to buflen after the call!

CTYPES STRUCTURES
    structure BF_KEY
        A BlowFish key structure. Used privately in hcrypt_key structure.
        Not really relevant as part of the API as there is no need
        for a developer to access it or its attributes directly.
    
        FIELDS
         |  BF_KEY.P = c_ulong_Array_18
         |  BF_KEY.S = c_ulong_Array_1024
    
    structure hcrypt_key
        A structure that holds a key for packet encryption/decryption.
        Use the hvdi.crypt.NewKey() function to get its properly initialized
        and usable instance, and hvdi.crypt.DeleteKey() to remove it from memory.
        There is no need for a developer to access any of its attributes directly,
        just to pass its instance as an argument to:
        hvdi.crypt.[EncryptPacket(), DecryptPacket(), SignPacket(), AuthenticatePacket()] and
        to some more functions of the same nature, and possibly to the higher level
        interface class hvdi.crypt.Key().
    
        FIELDS
         |  hcrypt_key.bf = BF_KEY
         |  hcrypt_key.iv = c_ubyte_Array_8
         |  hcrypt_key.digest = c_ubyte_Array_16
         |  hcrypt_key.n = c_long
    
    structure hcrypt_salt
        A structure that holds a salt for packet encryption/decryption.
        It is used in the key creation by the
        hvdi.crypt.NewKey() function or possibly by the higher level
        interface class hvdi.crypt.Key().
        Use the hvdi.crypt.NewSalt() function to get its properly initialized
        and usable instance, and hvdi.crypt.DeleteSalt() to remove it from memory.
        As the salt is necessary on the receiving end of encrypted packets,
        along with the password, to recreate the decryption key,
        a developer can extract its 16-byte value from hcrypt_salt's
        single attribute data. Also, the structure may be manually initialized
        and filled on the receiving end to pass it to the
        hvdi.crypt.NewKey() function by setting the said data attribute.
    
        FIELDS
         |  hcrypt_salt.data = c_ubyte_Array_16

PYTHON CLASSES

    class Key
     |  Instantiates a higher level Key() object to use with Packet() class and with Encoder() and Decoder()
     |  classes from hvdi.hvdi module.
     |
     |  Methods defined here:
     |
     |  __init__(self, password=None, salt=None)
     |      If password is None the output of:
     |      os.urandom(32) will be used instead.
     |      You can always find out what it is by using the method getpassword().
     |
     |      If salt is None it will be generated.
     |      You can retrieve its string value using the getsalt() method.
     |      You can get it in the list form using the getsaltlist() method.
     |      You can get the ctypes array in which it is stored using the getsaltarray() method.
     |      You can get the ctypespointer to initialized hcrypt_salt structure using the getsaltptr() method.
     |      You can get the initialized ctypes hcrypt_salt structure itself using the getsaltobj() method.
     |
     |      If you already have a salt then provide it as a 16 characters long string,
     |      an initialized hcrypt_salt structure, a pointer to initialized hcrypt_salt structure
     |      (as returned by hvdi.crypt.NewSalt()) or an iterable sequence
     |      of 16 integers ranging from 0 to 256.
     |
     |      If you set salt to False or 0 the salt will not be used
     |      and your encryptions will be vulnerable to dictionary attacks.
     |
     |      If you want to use only one Key() object in your program but multiple keys,
     |      you can use the change() function to reinitialize the object.
     |
     |      To get to the ctypes pointer to initialized hcrypt_key structure, use the attribute "key".
     |
     |  change(self, password=None, salt=None)
     |      Resets the object to the new values.
     |      See the __doc__ string for the __init__() method.
     |
     |  copy(self)
     |      Returns a new copy of this Key() object.
     |
     |  getpassword(self)
     |      Returns the password used to generate the key.
     |
     |  getsalt(self)
     |      Returns the salt as a string of bytes.
     |
     |  getsaltarray(self)
     |      Returns the ctypes.c_ubyte array housing the salt data.
     |
     |  getsaltlist(self)
     |      Returns the salt as a list of integers.
     |
     |  getsaltobj(self)
     |      Returns the ctypes hcrypt_salt initialized structure.
     |
     |  getsaltptr(self)
     |      Returns the ctypes pointer to the hcrypt_salt initialized structure.
     |
     |  tostring(self)
     |      Returns a serialized version of complete key
     |      (password and salt) that can be used to store
     |      or transfer the key. The key is self signed for corruption checks.
     |      To get the Key() object back from the string
     |      use the class method Key.fromstring().
     |
     |  __del__(self)
     |      Clean up the memory.
     |
     |  __eq__(self, other)
     |      Two Key()s are considered equal when both
     |      their password and salt match.
     |
     |  ----------------------------------------------------------------------
     |  Class methods defined here:
     |
     |  fromstring(cls, key) from __builtin__.classobj
     |      Returns a deserialized Key() object.
     |      key --> A string as returned by tostring() method
     |
     |  ----------------------------------------------------------------------

    class Packet(hvdi.tweaks.String)
     |  This class represents one encryptable/decryptable packet.
     |  The class is ultimately inheriting from UserString() to provide
     |  direct access to the data involved.
     |  encrypt(), decrypt() or sign() methods will change the Packet()
     |  in place and return a reference to it self to use
     |  in chained operations.
     |  If you do not wish to mess up an old Packet(), then use the method copy() like this:
     |      op = Packet("something").sign()
     |      np = op.copy().encrypt()
     |  The method verify() will only return True/False depending on the result of verification.
     |  The method getkey() will return the Key() object being used as default key.
     |  All other methods return the Packet() object and can be used in chained operations.
     |
     |  You can think about the Packet() as of a string with additional, useful methods.
     |
     |  Be careful about the order of encrypting and signing if you use both.
     |  If you encrypt and sign in one order, then try to decrypt and verify in another, the verification will fail.
     |
     |  Methods defined here:
     |
     |  __init__(self, data, key=None, encrypted=0, signed=0, password=None, salt=None)
     |      To initialize a new Packet() you need the following arguments:
     |      data      --> A Packet() data to be used
     |                    data can be another Packet() object too.
     |                    To learn how the data is inherited in such
     |                    a circumstance, see the __doc__ strings of
     |                    verify() and packet() methods.
     |      key       --> A Key() object to use in all operations
     |                    It can be None (default)
     |                    In this case a new key will be constructed using:
     |                    key = Key(password, salt)
     |                    To see how this will work see the Key()'s
     |                    class __doc__ string.
     |                    You can later access the generated key using the
     |                    Packet()'s "key" attribute.
     |                    If key is a string Key.fromstring() will be called.
     |      encrypted --> Is the data you provided encrypted or plain? (0 - plain - default)
     |      signed    --> Is the data you provided signed or not? (0 - not signed - default)
     |                    If signed is 1 then last 4 bytes of data
     |                    are considered a signature and are
     |                    separated from others.
     |                    They will be living in "signature" attribute.
     |                    To get complete data either extract the signature from the attribute or use
     |                    Packet().getdata() to get the whole buffer string.
     |
     |  copy(self, copykey=0)
     |      Returns a new exact copy of this Packet().
     |
     |      If copykey is 1 then the Key() object is also copied a new.
     |      If it is not, (0 default) then the reference of the Key() is passed onto the copy
     |      and if you make changes on a Key()
     |      in old Packet(), they will be reflected in the copy as well.
     |
     |  decrypt(self, key=None)
     |      Decrypts a Packet().
     |      If key is specified it overrides the default one.
     |
     |  encrypt(self, key=None)
     |      Encrypts a Packet().
     |      If key is specified it overrides the default one.
     |
     |  forget(self)
     |      Forgets that the packet has already been verified.
     |      To learn more, see the __doc__ string for method verify().
     |      forget() method returns a reference to this Packet() so that
     |      it can be used in chained calls if needed.
     |
     |  getdata(self)
     |      Returns complete data along with signature if
     |      the Packet() was signed. The data is a str().
     |
     |  getkey(self)
     |      Returns a reference to the currently used Key() object.
     |
     |  isencrypted lambda self
     |
     |  issigned lambda self
     |
     |  isverified lambda self
     |
     |  pack(self, key=None, encrypted=0, signed=0, password=None, salt=None)
     |      Enables you to chain this Packet() directly to another one.
     |      Complete data from this Packet() will be transfered to a new one.
     |      The returned Packet() will be considered as unencrypted
     |      and will be considered as unsigned unless you force the change
     |      by using the corresponding arguments.
     |      If key is None this Packet()'s key will be passed on.
     |      If it is not or password or salt are given, they will be used
     |      as in Packet()'s __init__() method.
     |
     |      If you set signed to 1 and this Packet() has already been verified then its signature will not propagate as it is.
     |      Last four bytes of the data will be used instead.
     |
     |      Example usage for double encryption:
     |      k1 = Key()
     |      k2 = Key()
     |      k3 = Key()
     |      k4 = Key()
     |      p = Packet("blah", k1)
     |      # Sign the plain textwith k1, encrypt it and the signature with k2, then encrypt them once more
     |      # with k3, and sign all together as encrypted with k4.
     |      p = p.sign().encrypt(k2).pack(k3).encrypt().sign(k4)
     |      # And to get it back:
     |      q = Packet(p, k4, encrypted=1, signed=1)
     |      if q.verify():
     |          q = q.decrypt(k3).pack(k2, encrypted=1, signed=1).decrypt()
     |          if q.verify(k1):
     |              print "Decrypted packet verified with k1!"
     |              print "It says:", q
     |          else:
     |              print "Decrypted packet corrupt or not authentic!"
     |      else:
     |          print "Packet corrupt or not authentic!"
     |      # Or like this:
     |      q = Packet(p, k4, encrypted=1, signed=1)
     |      try:
     |          q = q.verify(throw=1).decrypt(k3).pack(k2, encrypted=1, signed=1).decrypt().verify(k1, throw=1)
     |          print "Decrypted packet verified with k1!"
     |          print "It says:", q
     |      except Exception, e:
     |          print e
     |
     |  setkey(self, key=None, password=None, salt=None)
     |      Sets the key. Key must be the Key() object.
     |      If it is None then password and salt will be used to construct it as in
     |      key = Key(password, salt)
     |      Returns this Packet() object for chaining when wanting to generate new key on the fly as in:
     |      signkey = Key()
     |      p = Packet("blah", signkey).sign().setkey().encrypt()
     |      encryptionkey = p.getkey()
     |
     |  sign(self, key=None)
     |      Signs a Packet().
     |      If key is specified it overrides the default one.
     |      It is advisable to use different keys for encryption and signing.
     |
     |  verify(self, key=None, remember=1, throw=0)
     |      Verifies a Packet() by returning a boolean
     |      confirming or denying the authenticity
     |      of the Packet()'s data.
     |      If key is specified it overrides the default one.
     |      It is advisable to use different keys for encryption and signing.
     |
     |      If remember is 1 (default) then Packet() will remember that it has been
     |      already verified (if verification passed). If trying to verify() it again an error will be raised.
     |      Also, Packet() that remembers that it was successfully verified
     |      will not propagate its signature when using the pack() method or
     |      doing the Pack(Pack()) call but use only its data instead.
     |      This behaviour is desirable in most cases.
     |      If for some reason you want to forget it was verified later on,
     |      you can use the forget() method.
     |
     |      If you set throw to 1 (0 default), then verify() will return
     |      the Packet()'s reference instead of the boolean and
     |      raise an error if the verification fails.
     |
     |  ----------------------------------------------------------------------
