README.md
1[curve25519](http://cr.yp.to/ecdh.html) is an elliptic curve, developed by
2[Dan Bernstein](http://cr.yp.to/djb.html), for fast
3[Diffie-Hellman](http://en.wikipedia.org/wiki/Diffie-Hellman) key agreement.
4DJB's [original implementation](http://cr.yp.to/ecdh.html) was written in a
5language of his own devising called [qhasm](http://cr.yp.to/qhasm.html).
6The original qhasm source isn't available, only the x86 32-bit assembly output.
7
8This project provides performant, portable 32-bit & 64-bit implementations.
9All implementations are of course constant time in regard to secret data.
10
11#### Performance
12
13Compilers versions are gcc 4.6.3, icc 13.1.1, clang 3.4-1~exp1.
14
15Counts are in thousands of cycles.
16
17Note that SSE2 performance may be less impressive on AMD & older CPUs with slower SSE ops!
18
19##### E5200 @ 2.5ghz, march=core2
20
21<table>
22<thead><tr><th>Version</th><th>gcc</th><th>icc</th><th>clang</th></tr></thead>
23<tbody>
24<tr><td>64-bit SSE2 </td><td> 278k</td><td> 265k</td><td> 302k</td></tr>
25<tr><td>64-bit </td><td> 273k</td><td> 271k</td><td> 377k</td></tr>
26<tr><td>32-bit SSE2 </td><td> 304k</td><td> 289k</td><td> 317k</td></tr>
27<tr><td>32-bit </td><td> 1417k</td><td> 845k</td><td> 981k</td></tr>
28</tbody>
29</table>
30
31##### E3-1270 @ 3.4ghz, march=corei7-avx
32
33<table>
34<thead><tr><th>Version</th><th>gcc</th><th>icc</th><th>clang</th></tr></thead>
35<tbody>
36<tr><td>64-bit </td><td> 201k</td><td> 192k</td><td> 233k</td></tr>
37<tr><td>64-bit SSE2 </td><td> 201k</td><td> 201k</td><td> 261k</td></tr>
38<tr><td>32-bit SSE2 </td><td> 238k</td><td> 225k</td><td> 250k</td></tr>
39<tr><td>32-bit </td><td> 1293k</td><td> 822k</td><td> 848k</td></tr>
40</tbody>
41</table>
42
43#### Compilation
44
45No configuration is needed.
46
47##### 32-bit
48
49 gcc curve25519.c -m32 -O3 -c
50
51##### 64-bit
52
53 gcc curve25519.c -m64 -O3 -c
54
55##### SSE2
56
57 gcc curve25519.c -m32 -O3 -c -DCURVE25519_SSE2 -msse2
58 gcc curve25519.c -m64 -O3 -c -DCURVE25519_SSE2
59
60clang, icc, and msvc are also supported
61
62##### Named Versions
63
64Define CURVE25519_SUFFIX to append a suffix to public functions, e.g.
65`-DCURVE25519_SUFFIX=_sse2` to create curve25519_donna_sse2 and
66curve25519_donna_basepoint_sse2.
67
68#### Usage
69
70To use the code, link against `curve25519.o` and:
71
72 #include "curve25519.h"
73
74To generate a private/secret key, generate 32 cryptographically random bytes:
75
76 curve25519_key sk;
77 randombytes(sk, sizeof(curve25519_key));
78
79Manual clamping is not needed, and it is actually not possible to use unclamped
80keys due to the code taking advantage of the clamped bits internally.
81
82To generate the public key from the private/secret key:
83
84 curve25519_key pk;
85 curve25519_donna_basepoint(pk, sk);
86
87To generate a shared key with your private/secret key and someone elses public key:
88
89 curve25519_key shared;
90 curve25519_donna(shared, mysk, yourpk);
91
92And hash `shared` with a cryptographic hash before using, or e.g. pass `shared` through
93HSalsa20/HChacha as NaCl does.
94
95#### Testing
96
97Fuzzing against a reference implemenation is now available. See [fuzz/README](fuzz/README.md).
98
99Building `curve25519.c` and linking with `test.c` will run basic sanity tests and benchmark curve25519_donna.
100
101#### Papers
102
103[djb's curve25519 paper](http://cr.yp.to/ecdh/curve25519-20060209.pdf)
104
105#### License
106
107Public Domain, or MIT