From f110174010d134429441314b9b4565237c76f051 Mon Sep 17 00:00:00 2001
From: Tony Arcieri <bascule@gmail.com>
Date: Sat, 8 Apr 2023 19:04:26 -0600
Subject: [PATCH] p224: add `ecdh` feature (#814)

Adds a feature for performing elliptic curve Diffie-Hellman similar to
the same feature in the `p256` and `p384` crates.
---
 Cargo.lock       |  1 +
 p224/Cargo.toml  |  2 ++
 p224/src/ecdh.rs | 47 +++++++++++++++++++++++++++++++++++++++++++++++
 p224/src/lib.rs  |  7 +++++++
 p256/src/ecdh.rs |  2 +-
 p384/src/ecdh.rs |  2 +-
 6 files changed, 59 insertions(+), 2 deletions(-)
 create mode 100644 p224/src/ecdh.rs

diff --git a/Cargo.lock b/Cargo.lock
index 6669ee3f..9271dbc5 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -721,6 +721,7 @@ dependencies = [
  "elliptic-curve",
  "hex-literal 0.4.1",
  "primeorder",
+ "rand_core",
 ]
 
 [[package]]
diff --git a/p224/Cargo.toml b/p224/Cargo.toml
index ba5fcb66..ac1013e0 100644
--- a/p224/Cargo.toml
+++ b/p224/Cargo.toml
@@ -25,12 +25,14 @@ primeorder = { version = "0.13", optional = true, path = "../primeorder" }
 [dev-dependencies]
 hex-literal = "0.4"
 primeorder = { version = "0.13", features = ["dev"], path = "../primeorder" }
+rand_core = { version = "0.6", features = ["getrandom"] }
 
 [features]
 default = ["pem", "std"]
 alloc = ["elliptic-curve/alloc"]
 std = ["alloc", "elliptic-curve/std"]
 
+ecdh = ["wip-arithmetic-do-not-use", "elliptic-curve/ecdh"]
 pem = ["elliptic-curve/pem", "pkcs8"]
 pkcs8 = ["elliptic-curve/pkcs8"]
 test-vectors = ["dep:hex-literal"]
diff --git a/p224/src/ecdh.rs b/p224/src/ecdh.rs
new file mode 100644
index 00000000..ce2c7f6a
--- /dev/null
+++ b/p224/src/ecdh.rs
@@ -0,0 +1,47 @@
+//! Elliptic Curve Diffie-Hellman (Ephemeral) Support.
+//!
+//! This module contains a high-level interface for performing ephemeral
+//! Diffie-Hellman key exchanges using the secp224r1 elliptic curve.
+//!
+//! # Usage
+//!
+//! This usage example is from the perspective of two participants in the
+//! exchange, nicknamed "Alice" and "Bob".
+//!
+//! ```
+//! use p224::{EncodedPoint, PublicKey, ecdh::EphemeralSecret};
+//! use rand_core::OsRng; // requires 'getrandom' feature
+//!
+//! // Alice
+//! let alice_secret = EphemeralSecret::random(&mut OsRng);
+//! let alice_pk_bytes = EncodedPoint::from(alice_secret.public_key());
+//!
+//! // Bob
+//! let bob_secret = EphemeralSecret::random(&mut OsRng);
+//! let bob_pk_bytes = EncodedPoint::from(bob_secret.public_key());
+//!
+//! // Alice decodes Bob's serialized public key and computes a shared secret from it
+//! let bob_public = PublicKey::from_sec1_bytes(bob_pk_bytes.as_ref())
+//!     .expect("bob's public key is invalid!"); // In real usage, don't panic, handle this!
+//!
+//! let alice_shared = alice_secret.diffie_hellman(&bob_public);
+//!
+//! // Bob decodes Alice's serialized public key and computes the same shared secret
+//! let alice_public = PublicKey::from_sec1_bytes(alice_pk_bytes.as_ref())
+//!     .expect("alice's public key is invalid!"); // In real usage, don't panic, handle this!
+//!
+//! let bob_shared = bob_secret.diffie_hellman(&alice_public);
+//!
+//! // Both participants arrive on the same shared secret
+//! assert_eq!(alice_shared.raw_secret_bytes(), bob_shared.raw_secret_bytes());
+//! ```
+
+pub use elliptic_curve::ecdh::diffie_hellman;
+
+use crate::NistP224;
+
+/// NIST P-224 Ephemeral Diffie-Hellman Secret.
+pub type EphemeralSecret = elliptic_curve::ecdh::EphemeralSecret<NistP224>;
+
+/// Shared secret value computed via ECDH key agreement.
+pub type SharedSecret = elliptic_curve::ecdh::SharedSecret<NistP224>;
diff --git a/p224/src/lib.rs b/p224/src/lib.rs
index 522751e6..19bd5b15 100644
--- a/p224/src/lib.rs
+++ b/p224/src/lib.rs
@@ -18,6 +18,9 @@
 #[cfg(feature = "wip-arithmetic-do-not-use")]
 pub mod arithmetic;
 
+#[cfg(feature = "ecdh")]
+pub mod ecdh;
+
 #[cfg(any(feature = "test-vectors", test))]
 pub mod test_vectors;
 
@@ -92,6 +95,10 @@ pub type FieldBytes = elliptic_curve::FieldBytes<NistP224>;
 
 impl FieldBytesEncoding<NistP224> for Uint {}
 
+/// NIST P-224 public key.
+#[cfg(feature = "wip-arithmetic-do-not-use")]
+pub type PublicKey = elliptic_curve::PublicKey<NistP224>;
+
 /// NIST P-224 secret key.
 pub type SecretKey = elliptic_curve::SecretKey<NistP224>;
 
diff --git a/p256/src/ecdh.rs b/p256/src/ecdh.rs
index 94aa94aa..ab408dd8 100644
--- a/p256/src/ecdh.rs
+++ b/p256/src/ecdh.rs
@@ -1,7 +1,7 @@
 //! Elliptic Curve Diffie-Hellman (Ephemeral) Support.
 //!
 //! This module contains a high-level interface for performing ephemeral
-//! Diffie-Hellman key exchanges using the secp256k1 elliptic curve.
+//! Diffie-Hellman key exchanges using the secp256r1 elliptic curve.
 //!
 //! # Usage
 //!
diff --git a/p384/src/ecdh.rs b/p384/src/ecdh.rs
index 1e9ec85c..2e12c3da 100644
--- a/p384/src/ecdh.rs
+++ b/p384/src/ecdh.rs
@@ -1,7 +1,7 @@
 //! Elliptic Curve Diffie-Hellman (Ephemeral) Support.
 //!
 //! This module contains a high-level interface for performing ephemeral
-//! Diffie-Hellman key exchanges using the secp384 elliptic curve.
+//! Diffie-Hellman key exchanges using the secp384r1 elliptic curve.
 //!
 //! # Usage
 //!