From 46ea6f3614aada164e89e87c695e324474c2b5a5 Mon Sep 17 00:00:00 2001
From: Paragon Initiative Enterprises <security@paragonie.com>
Date: Wed, 1 May 2024 10:04:05 -0400
Subject: [PATCH] Release notes for v2.3.0

---
 doc/release-notes-2.3.0.md | 78 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 78 insertions(+)
 create mode 100644 doc/release-notes-2.3.0.md

diff --git a/doc/release-notes-2.3.0.md b/doc/release-notes-2.3.0.md
new file mode 100644
index 0000000..1862919
--- /dev/null
+++ b/doc/release-notes-2.3.0.md
@@ -0,0 +1,78 @@
+phpecc 2.3.0
+
+# Rapid Development Should Be Over For Now
+
+As of v2.3.0, we feel comfortable with the security of PHP ECC, so we removed the ugly
+notice from the README. So the pace of release should slow down considerably (unless
+something breaks, of course).
+
+Naturally, this means there are significant changes since v2.2.0. Let's get into them.
+
+## EccFactory Rejects Insecure Curves By Default
+
+This is [documented in the README](https://github.com/paragonie/phpecc?tab=readme-ov-file#insecure-curves),
+but for the sake of convenience:
+
+> 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();
+> ```
+
+This means if you previously followed the [examples](https://github.com/paragonie/phpecc/tree/master/examples)
+and used `EccFactory` to get your elliptic curves, great news! You're protected by default.
+
+Unfortunately, if you were selecting insecure curves for whatever reason, upgrading to v2.3.0 will
+cause your application to throw an `InsecureCurveException` now. You can pass `true` to the second
+argument of the appropriate static method to disable this guard-rail, but why do that when you could
+instead **use a more secure algorithm**?
+
+The choice is ultimately yours. We just have strong opinions on which is the better one.
+
+## Added Support for the Brainpool Curves 
+
+Not all of them, mind you. Only brainpoolP256r1, brainpoolP384r1, and brainpoolP512r1.
+
+(German PHP software developers rejoice! You can now comply with your government's
+[Technical Guideline BSI TR-03111](https://www.bsi.bund.de/SharedDocs/Downloads/EN/BSI/Publications/TechGuidelines/TR03111/BSI-TR-03111_V-2-1_pdf.pdf?__blob=publicationFile&v=1)
+technical requirements for elliptic curve cryptography with this library.)
+
+## Added Secure Factories
+
+While `EccFactory` seems the be the primary way that other developers were utilizing PHP ECC
+in their software, we took the liberty of also creating `SecureCurveFactory`, which extends
+`CurveFactory` and throws exceptions if you ask for something insecure.
+
+* Curves with an ECDLP security of less than 120 bits are always considered insecure.
+* If you do not request our optimized constant-time implementation, your calls to
+  `SecureCurveFactory` mey still succeed on some environments where ext-openssl can 
+  provide secure cryptography. Specifically, PHP 8.1+ with OpenSSL 3.0+ ought to work.
+  Otherwise, it will throw an exception, because insecure cryptography is not tolerated
+  by that API.
+
+We care a lot about misuse resistance and avoiding accidental foot-bullets. 
+
+For your convenience, there's also `SecureNistCurve`, `SecureSecgCurve`, and even 
+`SecureBrainpoolCurve` in the same namespace as `CurveFactory` and `SecureCurveFactory`.