Repository files navigation

This library is a fork fromphpecc/phpecc, which is itself a fork ofmdanter/ecc.It should serve as a drop-in replacement for any applications that previously dependedon either method.

By default, this library will attempt to use OpenSSL's implementation first. This requiresPHP 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. Thereare 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 attacksin the "optimized" code.

We cannot guarantee that the generic elliptic curve code is constant-time. We insteadurge users to use either OpenSSL's implementation or our constant-time implementation.

If you just need Diffie-Hellman or ECDSA, you should installEasyECCinstead of working with this library directly. EasyECC was designed to use PHPECCin a secure-by-default manner.

This library is a rewrite/update of Matyas Danter's ECC library. All credit goes to him.

The library supports the following curves:

• secp256k1
• nistp256 / secp256r1
• nistp384 / secp384r1
• nistp521
• brainpoolp256r1
• brainpoolp384r1
• brainpoolp512r1

Additionally, the following curves are also provided if, and only if, youenable insecure curves:

• secp112r1
• nistp192
• nistp224

During ECDSA, a random valuek is required. It is acceptable to use a true RNG to generate this value, butshould the samek 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 ak value,if you haveany bias in the distribution of bits ink,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 secretdependant branches.

The "optimized" constant-time code usesComplete addition formulas for prime order elliptic curvesto avoid side-channels with point addition and point doubling.

This package is released under the MIT license.

• PHP 7.1+ or PHP 8.0+
• composer
• ext-gmp

You can install this library via Composer :

composer require paragonie/ecc:^2

When sending in pull requests, please make sure to run themake command.

The default target runs all PHPUnit and PHPCS tests. All testsmust validate for your contribution to be accepted.

It's also always a good idea to check the results of theScrutinizer analysis for your pull requests.

Examples:

• Key generation
• ECDH exchange
• Signature creation
• Signature verification

TheEccFactory 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 inequivalent to less than 120 bits, it is consideredinsecure. (We do not provide constant-timeimplementations 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 passtrue to the second argument, like so:

<?phpuseMdanter\Ecc\EccFactory;useMdanter\Ecc\Math\GmpMath;$adapter =newGmpMath();// 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();