Skip to content

Commit c797d60

Browse files
baloomikelodder7
baloo
and
mikelodder7
authored
ed448-goldilocks: initial import (#1219)
Imports source code from: https://github.com/crate-crypto/Ed448-Goldilocks Signed-off-by: Michael Lodder <mike@litprotocol.com> Co-authored-by: Michael Lodder <mike@litprotocol.com>
1 parent 0c503ce commit c797d60

42 files changed

Lines changed: 7755 additions & 2 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.github/workflows/ed448-goldilocks.yml‎

Lines changed: 132 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,132 @@
1+
name: ed448-goldilocks
2+
3+
on:
4+
pull_request:
5+
paths:
6+
- ".github/workflows/ed448-goldilocks.yml"
7+
- "ed448-goldilocks/**"
8+
- "Cargo.*"
9+
push:
10+
branches: master
11+
12+
defaults:
13+
run:
14+
working-directory: ed448-goldilocks
15+
16+
env:
17+
CARGO_INCREMENTAL: 0
18+
RUSTFLAGS: "-Dwarnings"
19+
RUSTDOCFLAGS: "-Dwarnings"
20+
21+
jobs:
22+
build:
23+
runs-on: ubuntu-latest
24+
strategy:
25+
matrix:
26+
rust:
27+
- 1.85.0 # MSRV
28+
- stable
29+
target:
30+
- thumbv7em-none-eabi
31+
- wasm32-unknown-unknown
32+
steps:
33+
- uses: actions/checkout@v4
34+
- uses: dtolnay/rust-toolchain@master
35+
with:
36+
toolchain: ${{ matrix.rust }}
37+
targets: ${{ matrix.target }}
38+
- run: cargo build --target ${{ matrix.target }} --release --no-default-features
39+
- run: cargo build --target ${{ matrix.target }} --release --no-default-features --features alloc
40+
- run: cargo build --target ${{ matrix.target }} --release --no-default-features --features pkcs8
41+
- run: cargo build --target ${{ matrix.target }} --release --no-default-features --features signing
42+
- run: cargo build --target ${{ matrix.target }} --release --no-default-features --features serde
43+
- run: cargo build --target ${{ matrix.target }} --release --no-default-features --features zeroize
44+
- run: cargo build --target ${{ matrix.target }} --release --no-default-features --features alloc,pkcs8,signing,serde,zeroize
45+
46+
benches:
47+
runs-on: ubuntu-latest
48+
strategy:
49+
matrix:
50+
rust:
51+
- 1.85.0 # MSRV
52+
- stable
53+
steps:
54+
- uses: actions/checkout@v4
55+
- uses: dtolnay/rust-toolchain@master
56+
with:
57+
toolchain: ${{ matrix.rust }}
58+
- run: cargo build --all-features --benches
59+
60+
test:
61+
runs-on: ubuntu-latest
62+
strategy:
63+
matrix:
64+
include:
65+
# 32-bit Linux
66+
- target: i686-unknown-linux-gnu
67+
rust: 1.85.0 # MSRV
68+
deps: sudo apt update && sudo apt install gcc-multilib
69+
- target: i686-unknown-linux-gnu
70+
rust: stable
71+
deps: sudo apt update && sudo apt install gcc-multilib
72+
73+
# 64-bit Linux
74+
- target: x86_64-unknown-linux-gnu
75+
rust: 1.85.0 # MSRV
76+
- target: x86_64-unknown-linux-gnu
77+
rust: stable
78+
79+
steps:
80+
- uses: actions/checkout@v4
81+
- uses: dtolnay/rust-toolchain@master
82+
with:
83+
toolchain: ${{ matrix.rust }}
84+
targets: ${{ matrix.target }}
85+
- run: ${{ matrix.deps }}
86+
- run: cargo check --target ${{ matrix.target }} --all-features
87+
- run: cargo test --release --target ${{ matrix.target }} --no-default-features
88+
- run: cargo test --release --target ${{ matrix.target }}
89+
- run: cargo test --release --target ${{ matrix.target }} --all-features
90+
91+
cross:
92+
strategy:
93+
matrix:
94+
include:
95+
# ARM32
96+
- target: armv7-unknown-linux-gnueabihf
97+
rust: 1.85.0 # MSRV (cross)
98+
- target: armv7-unknown-linux-gnueabihf
99+
rust: stable
100+
101+
# ARM64
102+
- target: aarch64-unknown-linux-gnu
103+
rust: 1.85.0 # MSRV (cross)
104+
- target: aarch64-unknown-linux-gnu
105+
rust: stable
106+
107+
# PPC32
108+
- target: powerpc-unknown-linux-gnu
109+
rust: 1.85.0 # MSRV (cross)
110+
- target: powerpc-unknown-linux-gnu
111+
rust: stable
112+
113+
runs-on: ubuntu-latest
114+
steps:
115+
- uses: actions/checkout@v4
116+
- run: ${{ matrix.deps }}
117+
- uses: dtolnay/rust-toolchain@master
118+
with:
119+
toolchain: ${{ matrix.rust }}
120+
targets: ${{ matrix.target }}
121+
- uses: RustCrypto/actions/cross-install@master
122+
- run: cross test --release --target ${{ matrix.target }} --all-features
123+
124+
doc:
125+
runs-on: ubuntu-latest
126+
steps:
127+
- uses: actions/checkout@v4
128+
- uses: RustCrypto/actions/cargo-cache@master
129+
- uses: dtolnay/rust-toolchain@master
130+
with:
131+
toolchain: stable
132+
- run: cargo doc --all-features

‎Cargo.lock‎

Lines changed: 40 additions & 2 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎Cargo.toml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,7 @@ members = [
1010
"p256",
1111
"p384",
1212
"p521",
13+
"ed448-goldilocks",
1314
"primefield",
1415
"primeorder",
1516
"sm2"

‎ed448-goldilocks/Cargo.toml‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
[package]
2+
name = "ed448-goldilocks"
3+
version = "0.17.0-pre.0"
4+
authors = ["RustCrypto Developers"]
5+
categories = ["cryptography"]
6+
keywords = ["cryptography", "decaf", "ed448", "ed448-goldilocks"]
7+
homepage = "https://docs.rs/ed448-goldilocks/"
8+
repository = "https://github.com/RustCrypto/elliptic-curves/tree/master/ed448"
9+
documentation = "https://docs.rs/ed448-goldilocks"
10+
license = "BSD-3-Clause"
11+
edition = "2024"
12+
rust-version = "1.85"
13+
readme = "README.md"
14+
description = """A pure-Rust implementation of Ed448 and Curve448 and Decaf.
15+
This crate also includes signing and verifying of Ed448 signatures.
16+
"""
17+
18+
[dependencies]
19+
crypto-bigint = { version = "=0.7.0-pre.4", features = ["hybrid-array"], default-features = false }
20+
crypto_signature = { version = "3.0.0-rc.0", default-features = false, features = ["digest", "rand_core"], optional = true, package = "signature" }
21+
elliptic-curve = { version = "0.14.0-rc.3", features = ["arithmetic", "bits", "hash2curve", "jwk", "pkcs8", "pem", "sec1"] }
22+
rand_core = { version = "0.9", default-features = false }
23+
serdect = { version = "0.3.0", optional = true }
24+
sha3 = { version = "0.11.0-rc.0", default-features = false }
25+
subtle = { version = "2.6", default-features = false }
26+
zeroize = { version = "1.8", default-features = false, optional = true }
27+
28+
[features]
29+
default = ["std", "signing", "pkcs8"]
30+
alloc = ["serdect/alloc", "zeroize/alloc", "crypto_signature/alloc"]
31+
pkcs8 = ["elliptic-curve/pkcs8"]
32+
signing = ["dep:crypto_signature", "zeroize"]
33+
serde = ["dep:serdect"]
34+
std = ["serdect/default", "zeroize/default"]
35+
zeroize = ["dep:zeroize"]
36+
37+
[dev-dependencies]
38+
hex-literal = "1"
39+
hex = "0.4"
40+
rand_core = { version = "0.9", features = ["os_rng"] }
41+
rand_chacha = "0.9"
42+
serde_bare = "0.5"
43+
serde_json = "1.0"

‎ed448-goldilocks/README.md‎

Lines changed: 91 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,91 @@
1+
<p align="center">
2+
<img src="resources/bear.png" width = "400">
3+
</p>
4+
5+
ed448-goldilocks-plus
6+
7+
[![Crate][crate-image]][crate-link]
8+
[![Docs][docs-image]][docs-link]
9+
![BSD-3 Licensed][license-image]
10+
11+
THIS CODE HAS NOT BEEN AUDITED OR REVIEWED. USE AT YOUR OWN RISK.
12+
13+
## Field Choice
14+
15+
The field size is a Solinas trinomial prime 2^448 - 2^224 -1. This prime is called the Goldilocks prime.
16+
17+
## Curves
18+
19+
This repository implements three curves explicitly and another curve implicitly.
20+
21+
The three explicitly implemented curves are:
22+
23+
- Ed448-Goldilocks
24+
25+
- Curve448
26+
27+
- Twisted-Goldilocks
28+
29+
30+
## Ed448-Goldilocks Curve
31+
32+
- The goldilocks curve is an Edwards curve with affine equation x^2 + y^2 = 1 - 39081x^2y^2 .
33+
- This curve was defined by Mike Hamburg in https://eprint.iacr.org/2015/625.pdf .
34+
- The cofactor of this curve over the goldilocks prime is 4.
35+
36+
## Twisted-Goldilocks Curve
37+
38+
- The twisted goldilocks curve is a Twisted Edwards curve with affine equation y^2 - x^2 = 1 - 39082x^2y^2 .
39+
- This curve is also defined in https://eprint.iacr.org/2015/625.pdf .
40+
- The cofactor of this curve over the goldilocks prime is 4.
41+
42+
### Isogeny
43+
44+
- This curve is 2-isogenous to Ed448-Goldilocks. Details of the isogeny can be found here: https://www.shiftleft.org/papers/isogeny/isogeny.pdf
45+
46+
## Curve448
47+
48+
This curve is 2-isogenous to Ed448-Goldilocks. Details of Curve448 can be found here: https://tools.ietf.org/html/rfc7748
49+
50+
The main usage of this curve is for X448.
51+
52+
N.B. In that document there is an Edwards curve that is birationally equivalent to Curve448, with a large `d` value. This curve is not implemented and to my knowledge, has no utility.
53+
54+
## Strategy
55+
56+
The main strategy for group arithmetic on Ed448-Goldilocks is to perform the 2-isogeny to map the point to the Twisted-Goldilocks curve, then use the faster Twisted Edwards formulas to perform scalar multiplication. Computing the 2-isogeny then the dual isogeny will pick up a factor of 4 once we map the point back to the Ed448-Goldilocks curve, so the scalar must be adjusted by a factor of 4. Adjusting the scalar is dependent on the point and the scalar. More details can be found in the 2-isogenous paper.
57+
58+
# Decaf
59+
60+
The Decaf strategy [link paper] is used to build a group of prime order from the Twisted Goldilocks curve. The Twisted Goldilocks curve is used as it has faster formulas. We can also use Curve448 or Ed448-Goldilocks. Decaf takes advantage of an isogeny with a Jacobi Quartic curve which is not explicitly defined. Details of this can be found here: https://www.shiftleft.org/papers/decaf/decaf.pdf However, to my knowledge there is no documentation for the Decaf protocol implemented in this repository, which is a tweaked version of the original decaf protocol linked in the paper.
61+
62+
## Completed Point vs Extensible Point
63+
64+
Deviating from Curve25519-Dalek, this library will implement Extensible points instead of Completed Points. Due to the following observation:
65+
66+
- There is a cost of 3/4 Field multiplications to switch from the CompletedPoint. So if we were to perform repeated doubling, this would add an extra cost for each doubling in projective form. More details on the ExtensiblePoint can be found here [3.2]: https://www.shiftleft.org/papers/fff/fff.pdf
67+
68+
## Credits
69+
70+
The library design was taken from Dalek's design of Curve25519. The code for Montgomery curve arithmetic was also taken from Dalek's library.
71+
72+
The golang implementation of Ed448 and libdecaf were used as references.
73+
74+
Special thanks to Mike Hamburg for answering all the questions asked regarding Decaf and goldilocks.
75+
76+
This library adds [hash_to_curve](https://datatracker.ietf.org/doc/rfc9380/) and serialization of structs.
77+
78+
## Contribution
79+
80+
Unless you explicitly state otherwise, any contribution intentionally
81+
submitted for inclusion in the work by you, as defined in the BSD-3-Clause
82+
license, shall be dual licensed as above, without any additional terms or
83+
conditions.
84+
85+
[//]: # (badges)
86+
87+
[crate-image]: https://img.shields.io/crates/v/ed448-goldilocks-plus.svg
88+
[crate-link]: https://crates.io/crates/ed448-goldilocks-plus
89+
[docs-image]: https://docs.rs/ed448-goldilocks-plus/badge.svg
90+
[docs-link]: https://docs.rs/ed448-goldilocks-plus/
91+
[license-image]: https://img.shields.io/badge/License-BSD%203--Clause-blue.svg

‎ed448-goldilocks/resources/bear.png‎

197 KB
Loading

‎ed448-goldilocks/src/constants.rs‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
use crate::*;
2+
use crate::{Scalar, decaf::DecafPoint};
3+
4+
pub const DECAF_BASEPOINT: DecafPoint = DecafPoint(curve::twedwards::extended::ExtendedPoint {
5+
X: TWISTED_EDWARDS_BASE_POINT.X,
6+
Y: TWISTED_EDWARDS_BASE_POINT.Y,
7+
Z: TWISTED_EDWARDS_BASE_POINT.Z,
8+
T: TWISTED_EDWARDS_BASE_POINT.T,
9+
});
10+
11+
/// `BASEPOINT_ORDER` is the order of the Ed448 basepoint, i.e.,
12+
/// $$
13+
/// \ell = 2^\{446\} + 0x8335dc163bb124b65129c96fde933d8d723a70aadc873d6d54a7bb0d.
14+
/// $$
15+
pub const BASEPOINT_ORDER: Scalar = Scalar(ORDER);

‎ed448-goldilocks/src/curve.rs‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
pub mod edwards;
2+
pub mod montgomery;
3+
pub(crate) mod scalar_mul;
4+
pub(crate) mod twedwards;
5+
6+
pub use edwards::{AffinePoint, CompressedEdwardsY, EdwardsPoint};
7+
pub use montgomery::{MontgomeryPoint, ProjectiveMontgomeryPoint};

‎ed448-goldilocks/src/curve/edwards.rs‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
/// This module contains the code for the Goldilocks curve.
2+
/// The goldilocks curve is the (untwisted) Edwards curve with affine equation x^2 + y^2 = 1 - 39081x^2y^2
3+
/// Scalar Multiplication for this curve is pre-dominantly delegated to the Twisted Edwards variation using a (doubling) isogeny
4+
/// Passing the point back to the Goldilocks curve using the dual-isogeny clears the cofactor.
5+
/// The small remainder of the Scalar Multiplication is computed on the untwisted curve.
6+
/// See <https://www.shiftleft.org/papers/isogeny/isogeny.pdf> for details
7+
///
8+
/// This isogeny strategy does not clear the cofactor on the Goldilocks curve unless the Scalar is a multiple of 4.
9+
/// or the point is known to be in the q-torsion subgroup.
10+
/// Hence, one will need to multiply by the cofactor to ensure it is cleared when using the Goldilocks curve.
11+
/// If this is a problem, one can use a different isogeny strategy (Decaf/Ristretto)
12+
pub(crate) mod affine;
13+
pub(crate) mod extended;
14+
pub use affine::AffinePoint;
15+
pub use extended::{CompressedEdwardsY, EdwardsPoint};

0 commit comments

Comments
 (0)