ecdsa-0.10.tar.gz

# Pure-Python ECDSA [](http://travis-ci.org/warner/python-ecdsa) This is an easy-to-use implementation of ECDSA cryptography (Elliptic Curve Digital Signature Algorithm), implemented purely in Python, released under the MIT license. With this library, you can quickly create keypairs (signing key and verifying key), sign messages, and verify the signatures. The keys and signatures are very short, making them easy to handle and incorporate into other protocols. ## Features This library provides key generation, signing, and verifying, for five popular NIST "Suite B" GF(p) curves, with key lengths of 192, 224, 256, 384, and 521 bits. The "short names" for these curves, as known by the OpenSSL tool, are: prime192v1, secp224r1, prime256v1, secp384r1, and secp521r1. No other curves are included, but it would not be too hard to add more. ## Dependencies This library uses only Python. It requires python2.5 or later versions of the python2.x series. It is also compatible with python3.2 and 3.3. To run the OpenSSL compatibility tests, the 'openssl' tool must be on your $PATH. This release has been tested successfully against both OpenSSL 0.9.8o and 1.0.0a . ## Speed The following table shows how long this library takes to generate keypairs (keygen=), to sign data (sign=), and to verify those signatures (verify=), on my 2008 Mac laptop. All times are in seconds. It also shows the length of a signature (in bytes): the verifying ("public") key is typically the same length as the signature, and the signing ("private") key is half that length. * NIST192p: siglen= 48, keygen=0.160s, sign=0.058s, verify=0.116s * NIST224p: siglen= 56, keygen=0.230s, sign=0.086s, verify=0.165s * NIST256p: siglen= 64, keygen=0.305s, sign=0.112s, verify=0.220s * NIST384p: siglen= 96, keygen=0.801s, sign=0.289s, verify=0.558s * NIST521p: siglen=132, keygen=1.582s, sign=0.584s, verify=1.152s For comparison, a quality C++ implementation of ECDSA (Crypto++) typically computes a NIST256p signature in 2.88ms and a verification in 8.53ms, about 30-40x faster. Keys and signature can be serialized in different ways (see Usage, below). For a NIST192p key, the three basic representations require strings of the following lengths (in bytes): to_string: signkey= 24, verifykey= 48, signature=48 DER: signkey=106, verifykey= 80, signature=55 PEM: signkey=278, verifykey=162, (no support for PEM signatures) ## History In 2006, Peter Pearson announced his pure-python implementation of ECDSA in a [message to sci.crypt][1], available from his [download site][2]. In 2010, Brian Warner wrote a wrapper around this code, to make it a bit easier and safer to use. You are looking at the README for this wrapper. [1]: http://www.derkeiler.com/Newsgroups/sci.crypt/2006-01/msg00651.html [2]: http://webpages.charter.net/curryfans/peter/downloads.html ## Testing There are four test suites, three for the original Pearson module, and one more for the wrapper. To run them all, do this: python ecdsa/numbertheory.py # look for "****" and "failed" for problems python ecdsa/ellipticcurve.py # look for "Bad" for problems python ecdsa/ecdsa.py # look for "****" and "failed" for problems python ecdsa/test_pyecdsa.py # look for "FAILED" for problems On my 2009 Mac laptop, the combined tests take about 34 seconds to run. On a 2.4GHz P4 Linux box, they take 81 seconds. One component of `test_pyecdsa.py` checks compatibility with OpenSSL, by running the "openssl" CLI tool. If this tool is not on your $PATH, you may want to comment out this test (the easiest way is to add a line that says "del OpenSSL" to the end of test_pyecdsa.py). ## Security This library does not protect against timing attacks. Do not allow attackers to measure how long it takes you to generate a keypair or sign a message. This library depends upon a strong source of random numbers. Do not use it on a system where os.urandom() is weak. ## Usage You start by creating a SigningKey. You can use this to sign data, by passing in a data string and getting back the signature (also a string). You can also ask a SigningKey to give you the corresponding VerifyingKey. The VerifyingKey can be used to verify a signature, by passing it both the data string and the signature string: it either returns True or raises BadSignatureError. from ecdsa import SigningKey sk = SigningKey.generate() # uses NIST192p vk = sk.get_verifying_key() signature = sk.sign("message") assert vk.verify(signature, "message") Each SigningKey/VerifyingKey is associated with a specific curve, like NIST192p (the default one). Longer curves are more secure, but take longer to use, and result in longer keys and signatures. from ecdsa import SigningKey, NIST384p sk = SigningKey.generate(curve=NIST384p) vk = sk.get_verifying_key() signature = sk.sign("message") assert vk.verify(signature, "message") The SigningKey can be serialized into several different formats: the shortest is to call `s=sk.to_string()`, and then re-create it with `SigningKey.from_string(s, curve)` . This short form does not record the curve, so you must be sure to tell from_string() the same curve you used for the original key. The short form of a NIST192p-based signing key is just 24 bytes long. from ecdsa import SigningKey, NIST384p sk = SigningKey.generate(curve=NIST384p) sk_string = sk.to_string() sk2 = SigningKey.from_string(sk_string, curve=NIST384p) # sk and sk2 are the same key `sk.to_pem()` and `sk.to_der()` will serialize the signing key into the same formats that OpenSSL uses. The PEM file looks like the familiar ASCII-armored `"-----BEGIN EC PRIVATE KEY-----"` base64-encoded format, and the DER format is a shorter binary form of the same data. `SigningKey.from_pem()/.from_der()` will undo this serialization. These formats include the curve name, so you do not need to pass in a curve identifier to the deserializer. from ecdsa import SigningKey, NIST384p sk = SigningKey.generate(curve=NIST384p) sk_pem = sk.to_pem() sk2 = SigningKey.from_pem(sk_pem) # sk and sk2 are the same key Likewise, the VerifyingKey can be serialized in the same way: `vk.to_string()/VerifyingKey.from_string()`, `to_pem()/from_pem()`, and `to_der()/from_der()`. The same curve= argument is needed for `VerifyingKey.from_string()`. from ecdsa import SigningKey, VerifyingKey, NIST384p sk = SigningKey.generate(curve=NIST384p) vk = sk.get_verifying_key() vk_string = vk.to_string() vk2 = VerifyingKey.from_string(vk_string, curve=NIST384p) # vk and vk2 are the same key from ecdsa import SigningKey, VerifyingKey, NIST384p sk = SigningKey.generate(curve=NIST384p) vk = sk.get_verifying_key() vk_pem = vk.to_pem() vk2 = VerifyingKey.from_pem(vk_pem) # vk and vk2 are the same key There are a couple of different ways to compute a signature. Fundamentally, ECDSA takes a number that represents the data being signed, and returns a pair of numbers that represent the signature. The hashfunc= argument to `sk.sign()` and `vk.verify()` is used to turn an arbitrary string into fixed-length digest, which is then turned into a number that ECDSA can sign, and both sign and verify must use the same approach. The default value is hashlib.sha1, but if you use NIST256p or a longer curve, you can use hashlib.sha256 instead. There are also multiple ways to represent a signature. The default `sk.sign()` and `vk.verify()` methods present it as a short string, for simplicity and minimal overhead. To use a different scheme, use the `sk.sign(sigencode=)` and `vk.verify(sigdecode=)` arguments. There are helper funcions in the "ecdsa.util" module that can be useful here. It is also possible to create a SigningKey from a "seed", which is deterministic. This can be used in protocols where you want to derive consistent signing key