diff --git a/README.md b/README.md new file mode 100644 index 0000000..7372203 --- /dev/null +++ b/README.md @@ -0,0 +1,112 @@ +# Decaf elliptic curve library + +This library is for elliptic curve research and practical application. +It currently supports Ed448-Goldilocks and Curve25519. + +## Mailing lists + +Because this is new software, please expect it to have bugs, perhaps +even critical security bugs. If you are using it, please sign up for +updates: + +* Security-critical announcements (very low volume, God willing): decaf-security@googlegroups.com +* New version announcements (low volume): decaf-announce@googlegroups.com +* Library discussion (potentially more volume): decaf-discuss@googlegroups.com + +## General elliptic curve operations. + +This is a multi-purpose elliptic curve library. There is a C library, +and a set of C++ wrapper headers. The C++ code consists entirely of +inline calls, and has no compiled component. + +The library implements a fairly complete suite of operations on the +supported curves: + +* Point and scalar serialization and deserialization. +* Point addition, subtraction, doubling, and equality. +* Point multiplication by scalars. Accelerated double- and dual-scalar multiply. +* Scalar addition, subtraction, multiplication, division, and equality. +* Construction of precomputed tables from points. Precomputed scalarmul. +* Hashing to the curve with an Elligator variant. Inverse of elligator + for steganography. These are useful eg for PAKE. + +Internally, the library uses twisted Edwards curves with the "decaf" +technique to remove the curve's cofactor of 4 or 8. More about that +later. The upshot is that systems using the "decaf" interface will +be using a prime-order group, which mitigates one of the few +disadvantages of Edwards curves. However, this means that it is not +able to implement systems which care about cofactor information. + +The goal of this library is not only to follow best practices, but to +make it easier for clients of the library to follow best practices. +With a few well-marked exceptions, the functions in this library should +be strongly constant-time: they do not allow secret data to flow to +array indices, nor to control decisions except for a final failure +check. Furthermore, the C++ wrapping uses RAII to automatically clear +sensitive data, and has interfaces designed to prevent certain mistakes. + +## CFRG cryptosystems. + +The library additionally supports two cryptosystems defined by the +Crypto Forum Research Group (CFRG): the X448/X25519 Diffie-Hellman +functions, and the EdDSA signature scheme. Future versions might +support additional operations on these curves, such as precomputed +signature verification or conversion of Ed25519 keys to Curve25519 +keys. (Or they might not. We'll see.) + +## Symmetric crypto and hashing + +The Decaf library doesn't implement much symmetric crypto, but it does +contain the hash functions required by the CFRG cryptosystems: SHA512, +SHA-3 and SHAKE. + +The library also includes some work on an experimental protocol framework +called STROBE (based on Markku-Juhani Saarinen's BLINKER). This +framework is incomplete and will change in the future! There's also a +significant chance that it's insecure in its current form. Therefore, +all the STROBE interfaces have been marked as TOY for this version. +Please don't use them for anything serious. + +The Decaf library contains a random number generator, SpongeRNG, which +uses STROBE internally. This is used in the test suite to generate +random tests. It's probably secure, but since STROBE is not final, +its internals will almost certainly change. I recommend using your own +RNG instead for now. For example, consider libottery. + +## Internals + +The "decaf" technique is described in https://eprint.iacr.org/2015/673 +While the title of that paper is "removing cofactors through point +compression", it might be more accurate to say "through quotients and +isogenies". The internal representation of points is as "even" elements +of a twisted Edwards curve with a=-1. Using this subgroup removes a +factor of 2 from the cofactor. The remaining factor of 2 or 4 is +removed with a quotient group: any two points which differ by an element +of the 2- or 4-torsion subgroup are considered equal to each other. + +When a point is written out to wire format, it is converted (by isogeny) +to a Jacobi quartic curve, which is halfway between an Edwards curve +and a Montgomery curve. One of the 4 or 8 equivalent points on the +Jacobi quartic is chosen (it is "distinguished" according to certain +criteria, such as having a positive x-coordinate). The x-coordinate of +this point is written out. The y-coordinate is not written out, but the +decoder knows which of the two possible y-coordinates is correct because +of the distinguishing rules. See the paper for more details. + +## Licensing + +Most of the source files here are by Mike Hamburg. Those files are (c) +2014-2016 Cryptography Research, Inc (a division of Rambus). All of these +files are usable under the MIT license contained in LICENSE.txt. + +## Caveats + +As mentioned in the license, there is absolutely NO WARRANTY on any of this +code. This is an early release, and is likely to have security-critical +bugs despite my best efforts. + +I've attempted to protect against timing attacks and invalid point attacks, +but as of yet I've made no attempt to protect against power analysis. + +Cheers, +-- Mike Hamburg diff --git a/README.txt b/README.txt deleted file mode 100644 index 7aa8f7e..0000000 --- a/README.txt +++ /dev/null @@ -1,24 +0,0 @@ -Ed448-Goldilocks, Decaf version. - -This software is an experimental implementation of a new 448-bit elliptic -curve called Ed448-Goldilocks, with "Decaf" cofactor removal. - -The source files here are all by Mike Hamburg. Most of them are (c) -2014-2015 Cryptography Research, Inc (a division of Rambus). All of these -files are usable under the MIT license contained in LICENSE.txt. - -The Makefile is set for my 2013 MacBook Air. You can `make bench` to run -a completely arbitrary set of benchmarks and tests, or `make lib` to build -a stripped-down version of the library. For non-Haswell platforms, you may -need to replace -mavx2 -mbmi2 by an appropriate vector declaration. - -I've attempted to protect against timing attacks and invalid point attacks, -but as of yet no attempt to protect against power analysis. - -This software is incomplete, and lacks documentation. None of the APIs are -yet stable, though they may be getting there. The software is probably not -secure. Please consult TODO.txt for additional agenda items. Do not taunt -happy fun ball. - -Cheers, --- Mike Hamburg diff --git a/test/bench_decaf.cxx b/test/bench_decaf.cxx index 70da794..14e7db5 100644 --- a/test/bench_decaf.cxx +++ b/test/bench_decaf.cxx @@ -345,7 +345,7 @@ static void macro() { ss = s1.shared_secret(p2,32,true); } - printf("\nProtocol benchmarks:\n"); + printf("\nToy protocol benchmarks:\n"); SpongeRng clientRng(Block("client rng seed"),SpongeRng::DETERMINISTIC); SpongeRng serverRng(Block("server rng seed"),SpongeRng::DETERMINISTIC); SecureBuffer hashedPassword(Block("hello world"));