working on the README

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

README.txt

@@ -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,

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"));