prepare for new release
[python_pycryptopp.git] / README.ed25519.rst
1 =====================================================
2  Python Bindings to Ed25519 Digital Signature System
3 =====================================================
4
5 This package provides python bindings to a C implementation of the Ed25519
6 public-key signature system [1]_. The C code is copied from the SUPERCOP
7 benchmark suite [2]_, using the portable "ref" implementation (not the
8 high-performance assembly code), and is very similar to the copy in the NaCl
9 library [3]_. The C code is in the public domain [4]_. This python binding is
10 released under the MIT license [5]_.
11
12 With this library, you can quickly (2ms) create signing+verifying keypairs,
13 derive a verifying key from a signing key, sign messages, and verify the
14 signatures. The keys and signatures are very short, making them easy to
15 handle and incorporate into other protocols. All known attacks take at least
16 2^128 operations, providing the same security level as AES-128, NIST P-256,
17 and RSA-3072.
18
19
20 Speed and Key Sizes
21 -------------------
22
23 Signing keys are just 32 bytes (256 bits) of random data, so generating a
24 signing key is trivial: signingkey = os.urandom(32). Deriving a public
25 verifying key takes more time, as do the actual signing and verifying
26 operations.
27
28 A 256-bit elliptic curve key is estimated to be as strong as a much larger
29 RSA key. The "ECRYPT II" cryptographic experts group estimate the strength of
30 a 256-bit elliptic curve key to similar to the strength of a 3248-bit RSA
31 public key: http://keylength.com
32
33 On Brian Warner's 2010-era Mac laptop (2.8GHz Core2Duo), deriving a verifying
34 key takes 1.9ms, signing takes 1.9ms, and verification takes 6.3ms. The
35 high-performance assembly code in SUPERCOP (amd64-51-30k and amd64-64-24k) is
36 up to 100x faster than the portable reference version, and the python
37 overhead appears to be minimal (1-2us), so future releases may run even
38 faster.
39
40 Ed25519 private signing keys are 32 bytes long (this is expanded internally
41 to 64 bytes when necessary). The public verifying keys are also 32 bytes
42 long.  Signatures are 64 bytes long. All operations provide a 128-bit
43 security level.
44
45
46 Security
47 --------
48
49 The Ed25519 algorithm and C implementation are carefully designed to prevent
50 timing attacks. The Python wrapper might not preserve this property. Until it
51 has been audited for this purpose, do not allow attackers to measure how long
52 it takes you to generate a keypair or sign a message. Key generation depends
53 upon a strong source of random numbers. Do not use it on a system where
54 os.urandom() is weak.
55
56 Unlike typical DSA/ECDSA algorithms, signing does *not* require a source of
57 entropy. Ed25519 signatures are deterministic: using the same key to sign the
58 same data any number of times will result in the same signature each time.
59
60
61 Usage
62 -----
63
64 The first step is to generate a signing key and store it. At the same time,
65 you'll probably need to derive the verifying key and give it to someone else.
66 Signing keys are 32-byte uniformly-random strings. The safest way to generate
67 a key is with os.urandom(32)::
68
69  import os
70  from pycryptopp.publickey import ed25519
71
72  sk_bytes = os.urandom(32)
73  signing_key = ed25519.SigningKey(sk_bytes)
74  open("my-secret-key","wb").write(sk_bytes)
75
76  vkey_hex = signing_key.get_verifying_key_bytes().encode('hex')
77  print "the public key is", vkey_hex
78
79 To reconstruct the same key from the stored form later, just pass it back
80 into SigningKey::
81
82  sk_bytes = open("my-secret-key","rb").read()
83  signing_key = ed25519.SigningKey(sk_bytes)
84
85
86 Once you have the SigningKey instance, use its .sign() method to sign a
87 message. The signature is 64 bytes::
88
89  sig = signing_key.sign("hello world")
90  print "sig is:", sig.encode('hex')
91
92 On the verifying side, the receiver first needs to construct a
93 ed25519.VerifyingKey instance from the serialized form, then use its
94 .verify() method on the signature and message::
95
96  vkey_hex = "1246b84985e1ab5f83f4ec2bdf271114666fd3d9e24d12981a3c861b9ed523c6"
97  verifying_key = ed25519.VerifyingKey(vkey_hex.decode('hex'))
98  try:
99    verifying_key.verify(sig, "hello world")
100    print "signature is good"
101  except ed25519.BadSignatureError:
102    print "signature is bad!"
103
104 If you happen to have the SigningKey but not the corresponding VerifyingKey,
105 you can derive it with .get_verifying_key_bytes(). This allows the sending
106 side to hold just 32 bytes of data and derive everything else from that.
107 Deriving a verifying key takes about 1.9ms::
108
109  sk_bytes = open("my-secret-key","rb").read()
110  signing_key = ed25519.SigningKey(sk_bytes)
111  verifying_key = ed25519.VerifyingKey(signing_key.get_verifying_key_bytes())
112
113 There is also a basic command-line keygen/sign/verify tool in bin/edsig .
114
115
116 API Summary
117 -----------
118
119 The complete API is summarized here::
120
121  sk_bytes = os.urandom(32)
122  sk = SigningKey(sk_bytes)
123  vk_bytes = sk.get_verifying_key_bytes()
124  vk = VerifyingKey(vk_bytes)
125
126  signature = sk.sign(message)
127  vk.verify(signature, message)
128
129
130 footnotes
131 ---------
132
133 .. [1] http://ed25519.cr.yp.to/
134 .. [2] http://bench.cr.yp.to/supercop.html
135 .. [3] http://nacl.cr.yp.to/
136 .. [4] http://ed25519.cr.yp.to/software.html "Copyrights"
137 .. [5] LICENSE, included in this distribution