path: root/python/PyECC/ecc/Key.py

#   ====================================================================
#
#       ELLIPTIC CURVE KEY ENCAPSULATION
#       Version 2011-01-26
#
#       Copyright (c) 2010 - 2011 | Toni Mattis
#
#   ====================================================================

"""
== Elliptic Curve Key Encapsulation ==

Keypairs
--------
Keypairs are generated using: Key.generate(bits)

The number of bits is tied to the NIST-proposed elliptic curves
and has to be 192, 224, 256, 384 or 521 (not 512!).
The result is a Key object containing public and private key.

private() is a method for checking whether the Key object is a
pure public key or also includes the private part.


Exchange
--------
Public keys have to be exported using the export()-Method without
passing an argument. The result is a string which can be safely
transmitted.

Using Key.decode(<encoded key>) the receiver obtains a new
public Key object of the sender.


Storage
-------
For storing a key, export(True) exports both private and public
key as a string. Make sure this information is properly encrypted
when stored.

Key.decode(<encoded key>) obtains the full Key object from the
encoded keypair.


Public Keys
-----------
A public Key object can perform the following cryptographic
operations:

*   validate()      Checks key integrity, i.e. after loading the
                    key from a file. Returns True if the key is
                    valid. Invalid keys should be discarded.

*   fingerprint()   Returns the public key fingerprint used to
                    identify the key. Optional arguments:
                    1. as_hex - True, if output should be formatted
                        as hexadecimal number (default: True).
                    2. hashfunc - The official name of the hash
                        function being used (default: 'sha1')
                        For supported hash functions see below.

*   keyid()         Returns a (mostly) unique Key ID, which is
                    shorter than the fingerprint. The result
                    is an integer of max. 64 bits.

*   verify()        Verifies whether the given data (argument 1)
                    matches the signature (argument 2) issued
                    by the owner of this key. A falsification
                    can have multiple causes:
                    
                    - Data, public key or signature were altered
                      during transmission/storage.
                    - The siganture was not issued by the owner
                      of this key but may be valid with another
                      key.
                    - The signature was issued for different data.
                    - The signature was issued using a different
                      hash function. Another hash function may work.
                      
                    Optionally, the name of a hash algorithm
                    can be provided. For hash names see below.

* encrypt()         Encrypts a packet of data destined for the owner
                    of this key*. After encryption only the holder
                    of this Key's private part is able to decrypt
                    the message.

Private Keys / Keypairs
-----------------------

If the key object is private, then it is a keypair consisting of
a public and a private key. Therefore all Public key operations
are supported.

Additional functions:

* sign()            Signs given data using this private key. The
                    result is a signature which can be passed as
                    argument to the verify() function in addition
                    to the data being verified.

                    As additional argument the name of the hash
                    function can be provided (defaults to 'sha256').
                    For hash names see below.

* auth_encrypt()    Performs authenticated encryption of data
                    (argument 1) for the holder of the key provided
                    as second argument. Only the receiver whose
                    public key is given is able to derypt and verify
                    the message. The message will be implicitly
                    signed using the own private key. *

* decrypt()         Decrypts a message which has been encrypted
                    using the public key of this keypair*. If
                    decryption yields random data, this can have
                    multiple causes:
                    - You were not the intended receiver, a different
                      private key may be able to decrypt it.
                    - The message was altered.
                    - Your private key is damaged.

* auth_decrypt()    Decrypts a message while verifying whether
                    it has been authentically issued by the holder
                    of the given key (argument 2). When
                    authentication failed, a
                    SecurityViolationException is thrown. Reasons
                    for this to happen are those mentioned with
                    decrypt() and verify(). *

*) The encryption used here depends on the "eccrypt" module imported
by this module. Default implementation should use RABBIT as cipher
and do the asymmetric part using an optimized El-Gamal scheme.
        
            

Hash functions
--------------
The following hash functions can be passed at the moment:

name     | hash size              | security level
         | (bits, bytes, hex digits)
---------+------------------------+----------------
'sha1'      160 / 20 / 40           medium
'sha224'    224 / 28 / 56           medium-strong
'sha256'    256 / 32 / 64           strong
'sha384'    384 / 48 / 96           very strong
'sha512'    512 / 64 / 128          very strong

'md5'       128 / 16 / 32           weak (not recommended!)


Curves
------
According to FIPS 186-3, Appendix D.1.2 there are 5 elliptic
curves recommended. All of those are strong, but those with
a higher bit number even stronger.

192 and 224 bits are sufficient for most purposes.
256 bits offer an additional magnitude of security.
    (i.e. for classified / strongly confidential data)
384 and 521 bits provide exceptionally strong security. According
    to current research they most probably keep this level for
    decades in the future.

FIPS also recommends curves over polynomial fields but actually
only prime fields are implemented here. (Because 2^521-1 is a mersenne
prime having great security characteristics, 521 bits are preferred
over a constructed 512 bit field.)
"""

from encoding import *
from eccrypt import *
import ecdsa
import hashlib
from SecurityViolationException import *

class Key:

    # --- KEY SETUP ------------------------------------------------------------

    def __init__(self, public_key, private_key = None):
        '''Create a Key(pair) from numeric keys.'''
        self._pub = public_key
        self._priv = private_key
        self._fingerprint = {}
        self._id = None

    @staticmethod
    def generate(bits):
        '''Generate a new ECDSA keypair'''
        return Key(*ecdsa.keypair(bits))

    # --- BINARY REPRESENTATION ------------------------------------------------

    def encode(self, include_private = False):
        '''Returns a strict binary representation of this Key'''
        e = Encoder().int(self.keyid(), 8)
        e.int(self._pub[0], 2).point(self._pub[1], 2)
        if include_private and self._priv:
            e.long(self._priv[1], 2)
        else:
            e.long(0, 2)
        return e.out()

    def compress(self):
        '''Returns a compact public key representation'''
        

    @staticmethod
    def decode(s):
        '''Constructs a new Key object from its binary representation'''
        kid, ksize, pub, priv = Decoder(s).int(8).int(2).point(2).long(2).out()
        k = Key((ksize, pub), (ksize, priv) if priv else None)
        if kid == k.keyid():
            return k
        else:
            raise ValueError, "Invalid Key ID"

    # --- IDENTIFICATION AND VALIDATION ----------------------------------------

    def private(self):
        '''Checks whether Key object contains private key'''
        return bool(self._priv)

    def validate(self):
        '''Checks key validity'''
        if ecdsa.validate_public_key(self._pub):
            if self._priv:          # ? validate and match private key
                return ecdsa.validate_private_key(self._priv) and \
                       ecdsa.match_keys(self._pub, self._priv)
            else:
                return True         # : everything valid
        else:
            return False

    def fingerprint(self, as_hex = True, hashfunc = 'sha1'):
        '''Get the public key fingerprint'''
        if hashfunc in self._fingerprint:
            return self._fingerprint[hashfunc] if not as_hex else \
                   self._fingerprint[hashfunc].encode("hex")
        else:
            h = hashlib.new(hashfunc, enc_point(self._pub[1]))
            d = h.digest()
            self._fingerprint[hashfunc] = d
            return d.encode("hex") if as_hex else d

    def keyid(self):
        '''Get a short, unique identifier'''
        if not self._id:
            self._id = dec_long(self.fingerprint(False, 'sha1')[:8])
        return self._id

    # --- DIGITAL SIGNATURES ---------------------------------------------------

    def sign(self, data, hashfunc = 'sha256'):
        '''Sign data using the specified hash function'''
        if self._priv:
            h = dec_long(hashlib.new(hashfunc, data).digest())
            s = ecdsa.sign(h, self._priv)
            return enc_point(s)
        else:
            raise AttributeError, "Private key needed for signing."

    def verify(self, data, sig, hashfunc = 'sha256'):
        '''Verify the signature of data using the specified hash function'''
        h = dec_long(hashlib.new(hashfunc, data).digest())
        s = dec_point(sig)
        return ecdsa.verify(h, s, self._pub)

    # --- HYBRID ENCRYPTION ----------------------------------------------------

    def encrypt(self, data):
        '''Encrypt a message using this public key'''
        ctext, mkey = encrypt(data, self._pub)
        return Encoder().point(mkey).str(ctext, 4).out()

    def decrypt(self, data):
        '''Decrypt an encrypted message using this private key'''
        mkey, ctext = Decoder(data).point().str(4).out()
        return decrypt(ctext, mkey, self._priv)
        
    # --- AUTHENTICATED ENCRYPTION ---------------------------------------------

    def auth_encrypt(self, data, receiver):
        '''Sign and encrypt a message'''
        sgn = self.sign(data)
        ctext, mkey = encrypt(data, receiver._pub)
        return Encoder().point(mkey).str(ctext, 4).str(sgn, 2).out()

    def auth_decrypt(self, data, source):
        '''Decrypt and verify a message'''
        mkey, ctext, sgn = Decoder(data).point().str(4).str(2).out()
        text = decrypt(ctext, mkey, self._priv)
        if source.verify(text, sgn):
            return text
        else:
            raise SecurityViolationException, "Invalid Signature"


if __name__ == "__main__":

    import time

    def test_overhead():
        print "sender", "receiver", "+bytes", "+enctime", "+dectime"
        for s in [192, 224, 256, 384, 521]:
            sender = Key.generate(s)
            for r in [192, 224, 256, 384, 521]:
                receiver = Key.generate(r)
                t = time.time()
                e = sender.auth_encrypt("", receiver)
                t1 = time.time() - t
                t = time.time()
                receiver.auth_decrypt(e, sender)
                t2 = time.time() - t
                print s, r, len(e), t1, t2