## paragonie / ecc

PHP Elliptic Curve Cryptography library

Installs: 11 611

Dependents: 4

Suggesters: 0

Security: 1

Stars: 8

Watchers: 2

Forks: 108

Open Issues: 0

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

This package is auto-updated.

Last update: 2024-05-01 14:22:57 UTC

# 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:

- An optimized constant-time implementation of each elliptic curve.
- 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:

### 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:

- If we can depend on OpenSSL to provide its implementation, we will. This is considered secure.
- If we have an optimized constant-time implementation, it is secure.
- 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.) - 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();