paragonie/ecc

PHP Elliptic Curve Cryptography library

v2.3.0 2024-05-01 14:04 UTC

Requires

• php: ^7.1||^8.0
• ext-gmp: *
• genkgo/php-asn1: ^2
• paragonie/sodium_compat: ^1|^2

Requires (Dev)

• ext-json: *
• phpunit/phpunit: ^6|^7|^8|^9
• squizlabs/php_codesniffer: ^2|^3
• symfony/yaml: ^2.6|^3.0|^4
• vimeo/psalm: ^2|^3|^4|^5

Suggests

• ext-openssl: (PHP 8.1, OpenSSL 3+) Improved performance, less worries about side-channels

MIT

• Paragon Initiative Enterprises
• Matyas Danter
• Thibaud Fabre
• Thomas Kerin

• Diffie
• Hellman
• ECDSA
• elliptic
• curve
• secp256k1
• ecdh
• phpecc
• nistp192
• nistp224
• nistp256
• nistp521
• secp256r1
• nistp384

README

Notice

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.

Security Information

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 instead of working with this library directly. EasyECC was designed to use PHPECC in a secure-by-default manner.

Historical Information

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, you enable 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.

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

The "optimized" constant-time code uses Complete addition formulas for prime order elliptic curves to avoid side-channels with point addition and point doubling.

License

This package is released under the MIT license.

Requirements

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

Installation

You can install this library via Composer :

composer require paragonie/ecc:^2

Contribute

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

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

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

Usage

Examples:

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

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