Merge pull request #25 from paragonie/update-readme

Update README

README.md

@@ -15,44 +15,67 @@
 
 This library is a fork from `phpecc/phpecc`, which is itself a fork of `mdanter/ecc`. 
 It should serve as a drop-in replacement for any applications that previously depended
-on either method. 
+on either method.
 
-However, Paragon Initiative Enterprises **CANNOT** guarantee the security of this library
-until we have fully audited its code. This notice will be removed when we believe it to
-be secure.
+### Security Information
 
-In the meantime, **DO NOT** submit bug bounty reports to us for this code. They will be
-closed as out of scope. File an Issue here instead!
+By default, this library will attempt to use OpenSSL's implementation first. This requires 
+PHP 8.1+ and OpenSSL 3.0+ to work. OpenSSL's implementation should be constant-time.
+
+When OpenSSL is not available, this library will back to a Pure PHP implementation. There
+are actually two implementations:
+
+1. An optimized constant-time implementation of each elliptic curve.
+2. A generic elliptic curve algorithm that was shipped with the original PHP ECC library.
+
+We have taken every effort to harden our fork of this library against side-channel attacks
+in the "optimized" code.
+
+We cannot guarantee that the generic elliptic curve code is constant-time. We instead
+urge users to use either OpenSSL's implementation or our constant-time implementation.
 
 ### This Library Implements Low-Level Elliptic Curve Cryptography
 
 If you just need Diffie-Hellman or ECDSA, you should install [EasyECC](https://github.com/paragonie/easy-ecc/)
 instead of working with this library directly. EasyECC was designed to use PHPECC 
 in a secure-by-default manner.
 
-### Information
+### Historical Information
 
 This library is a rewrite/update of Matyas Danter's ECC library. All credit goes to him.
 
-For more information on Elliptic Curve Cryptography please read [this fine article](http://www.matyasdanter.com/2010/12/elliptic-curve-php-oop-dsa-and-diffie-hellman/).
-
 The library supports the following curves:
 
- - secp112r1
  - secp256k1
- - nistp192
- - nistp224
  - nistp256 / secp256r1
  - nistp384 / secp384r1
  - nistp521
+ - brainpoolp256r1
+ - brainpoolp384r1
+ - brainpoolp512r1
+
+Additionally, the following curves are also provided if, and only if, you
+[enable insecure curves](#insecure-curves):
+
+- secp112r1
+- nistp192
+- nistp224
 
 During ECDSA, a random value `k` is required. It is acceptable to use a true RNG to generate this value, but 
-should the same `k` value ever be repeatedly used for a key, an attacker can recover that signing key. 
-The HMAC random generator can derive a deterministic k value from the message hash and private key, voiding
-this concern.
+should the same `k` value ever be repeatedly used for a key, an attacker can recover that signing key.
+
+However, it's actually even worse than a simple "reuse" concern. Even if you never reuse a `k` value, 
+if you have [any bias in the distribution of bits in `k`](https://crypto.stackexchange.com/a/48379), 
+an attacker that observes sufficient signatures can use Lattice Reduction to recover your key.
+
+The HMAC random generator can derive a deterministic k value from the message hash and private key.
+This provides an unbiased distribution of bits, and is therefore suitable for addressing this concern.
 
 The library uses a non-branching Montgomery ladder for scalar multiplication, as it's constant time and avoids secret 
-dependant branches. 
+dependant branches.
+
+The "optimized" constant-time code uses [Complete addition formulas for prime order elliptic curves](https://eprint.iacr.org/2015/1060)
+to avoid side-channels with point addition and point doubling.
 
 ### License
 
@@ -86,3 +109,33 @@ Examples:
  * [ECDH exchange](./examples/ecdh_exchange.php)
  * [Signature creation](./examples/creating_signature.php)
  * [Signature verification](./examples/verify_signature.php)
+
+### Insecure Curves
+
+The `EccFactory` class will, by default, only allow you to instantiate secure elliptic curves.
+An elliptic curve is considered secure if one or more of the following is true:
+
+1. If we can depend on OpenSSL to provide its implementation, we will. This is considered secure.
+2. If we have an optimized constant-time implementation, it is secure.
+3. If the elliptic curve discrete logarithm problem (ECDLP) for the curve has a security level in
+   equivalent to less than 120 bits, it is considered **insecure**. (We do not provide constant-time
+   implementations for these curves, so step 2 should already fail these curves.)
+4. Otherwise, it is considered insecure. **EccFactory will not allow them by default.** 
+
+To bypass this guard-rail, simply pass `true` to the second argument, like so:
+
+```php
+<?php
+use Mdanter\Ecc\EccFactory;
+use Mdanter\Ecc\Math\GmpMath;
+
+$adapter = new GmpMath();
+// This will throw an InsecureCurveException:
+// $p192 = EccFactory::getNistCurves($adapter)->generator192();
+
+// This will succeed:
+$p192 = EccFactory::getNistCurves($adapter, true)->generator192();
+
+// This will also succeed, without any special considerations:
+$p256 = EccFactory::getNistCurves()->generator256();
+```