# ==================================================================== # # 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() 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() 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