@noble/curves 0.1.0 → 0.2.0

package/README.md

@@ -2,15 +2,21 @@
 
 Minimal, zero-dependency JS implementation of elliptic curve cryptography.
 
-Implements Short Weierstrass curves with ECDSA signature scheme.
+- Short Weierstrass curve with ECDSA signatures
+- Twisted Edwards curve with EdDSA signatures
+- Montgomery curve for ECDH key agreement
 
-To keep the package minimal, no curve definitions are provided out-of-box.
-Main reason for that is the fact hashing library is usually required for full functionality. Use separate package that defines popular curves: `micro-curve-definitions` for P192, P224, P256, P384, P521, secp256k1, stark curve, bn254, pasta (pallas/vesta) - it depends on `@noble/hashes`.
+To keep the package minimal, no curve definitions are provided out-of-box. Use `micro-curve-definitions` module:
+
+- It provides P192, P224, P256, P384, P521, secp256k1, stark curve, bn254, pasta (pallas/vesta) short weierstrass curves
+- It also provides ed25519 and ed448 twisted edwards curves
+- Main reason for separate package is the fact hashing library (like `@noble/hashes`) is required for full functionality
+- We may reconsider merging packages in future, when a stable version would be ready
 
 Future plans:
 
-- Edwards, Twisted Edwards & Montgomery curves
-- hash-to-curve standard
+- hash to curve standard
+- point indistinguishability
 - pairings
 
 ### This library belongs to _noble_ crypto
@@ -40,30 +46,108 @@ npm install @noble/curves
 ```
 
 ```ts
-// Short Weierstrass curve
-import shortw from '@noble/curves/shortw';
+import { weierstrass } from '@noble/curves/weierstrass'; // Short Weierstrass curve
 import { sha256 } from '@noble/hashes/sha256';
 import { hmac } from '@noble/hashes/hmac';
 import { concatBytes, randomBytes } from '@noble/hashes/utils';
 
-export const secp256k1 = shortw({
+const secp256k1 = weierstrass({
   a: 0n,
   b: 7n,
-  // Field over which we'll do calculations
-  P: 2n ** 256n - 2n ** 32n - 2n ** 9n - 2n ** 8n - 2n ** 7n - 2n ** 6n - 2n ** 4n - 1n,
-  // Curve order, total count of valid points in the field
+  P: 0xfffffffffffffffffffffffffffffffffffffffffffffffffffffffefffffc2fn,
   n: 0xfffffffffffffffffffffffffffffffebaaedce6af48a03bbfd25e8cd0364141n,
-  // Base point (x, y) aka generator point
   Gx: 55066263022277343669578718895168534326250603453777594175500187360389116729240n,
   Gy: 32670510020758816978083085130507043184471273380659243275938904335757337482424n,
   hash: sha256,
   hmac: (k: Uint8Array, ...msgs: Uint8Array[]) => hmac(sha256, key, concatBytes(...msgs)),
-  randomBytes: randomBytes
+  randomBytes
 });
 
-// secp256k1.getPublicKey(priv)
-// secp256k1.sign(msg, priv)
+secp256k1.getPublicKey(secp256k1.utils.randomPrivateKey());
+secp256k1.sign(randomBytes(32), secp256k1.utils.randomPrivateKey());
 // secp256k1.verify(sig, msg, pub)
+
+import { twistedEdwards } from '@noble/curves/edwards'; // Twisted Edwards curve
+import { sha512 } from '@noble/hashes/sha512';
+
+const ed25519 = twistedEdwards({
+  a: -1n,
+  d: 37095705934669439343138083508754565189542113879843219016388785533085940283555n,
+  P: 57896044618658097711785492504343953926634992332820282019728792003956564819949n,
+  n: 7237005577332262213973186563042994240857116359379907606001950938285454250989n,
+  h: 8n,
+  Gx: 15112221349535400772501151409588531511454012693041857206046113283949847762202n,
+  Gy: 46316835694926478169428394003475163141307993866256225615783033603165251855960n,
+  hash: sha512,
+  randomBytes,
+  adjustScalarBytes(bytes) { // could be no-op
+    bytes[0] &= 248;
+    bytes[31] &= 127;
+    bytes[31] |= 64;
+    return bytes;
+  },
+} as const);
+ed25519.getPublicKey(ed25519.utils.randomPrivateKey());
+```
+
+## Performance
+
+Benchmark results on Apple M2 with node v18.10:
+
+```
+==== secp256k1 ====
+  - getPublicKey1 (samples: 10000)
+    noble_old x 8,131 ops/sec @ 122μs/op
+    secp256k1 x 7,374 ops/sec @ 135μs/op
+  - getPublicKey255 (samples: 10000)
+    noble_old x 7,894 ops/sec @ 126μs/op
+    secp256k1 x 7,327 ops/sec @ 136μs/op
+  - sign (samples: 5000)
+    noble_old x 5,243 ops/sec @ 190μs/op
+    secp256k1 x 4,834 ops/sec @ 206μs/op
+  - getSharedSecret (samples: 1000)
+    noble_old x 653 ops/sec @ 1ms/op
+    secp256k1 x 634 ops/sec @ 1ms/op
+  - verify (samples: 1000)
+    secp256k1_old x 1,038 ops/sec @ 962μs/op
+    secp256k1 x 1,009 ops/sec @ 990μs/op
+==== ed25519 ====
+  - getPublicKey (samples: 10000)
+    old x 8,632 ops/sec @ 115μs/op
+    noble x 8,390 ops/sec @ 119μs/op
+  - sign (samples: 5000)
+    old x 4,376 ops/sec @ 228μs/op
+    noble x 4,233 ops/sec @ 236μs/op
+  - verify (samples: 1000)
+    old x 865 ops/sec @ 1ms/op
+    noble x 860 ops/sec @ 1ms/op
+==== ed448 ====
+  - getPublicKey (samples: 5000)
+    noble x 3,224 ops/sec @ 310μs/op
+  - sign (samples: 2500)
+    noble x 1,561 ops/sec @ 640μs/op
+  - verify (samples: 500)
+    noble x 313 ops/sec @ 3ms/op
+==== nist ====
+  - getPublicKey (samples: 2500)
+    P256 x 7,993 ops/sec @ 125μs/op
+    P384 x 3,819 ops/sec @ 261μs/op
+    P521 x 2,074 ops/sec @ 481μs/op
+  - sign (samples: 1000)
+    P256 x 5,327 ops/sec @ 187μs/op
+    P384 x 2,728 ops/sec @ 366μs/op
+    P521 x 1,594 ops/sec @ 626μs/op
+  - verify (samples: 250)
+    P256 x 806 ops/sec @ 1ms/op
+    P384 x 353 ops/sec @ 2ms/op
+    P521 x 171 ops/sec @ 5ms/op
+==== stark ====
+  - pedersen (samples: 500)
+    old x 85 ops/sec @ 11ms/op
+    noble x 1,216 ops/sec @ 822μs/op
+  - verify (samples: 500)
+    old x 302 ops/sec @ 3ms/op
+    noble x 698 ops/sec @ 1ms/op
 ```
 
 ## License

package/lib/edwards.d.ts

@@ -0,0 +1,108 @@
+/*! noble-curves - MIT License (c) 2022 Paul Miller (paulmillr.com) */
+import { BasicCurve, Hex, PrivKey } from './utils.js';
+import { Group, GroupConstructor } from './group.js';
+export declare type CHash = {
+    (message: Uint8Array | string): Uint8Array;
+    blockLen: number;
+    outputLen: number;
+    create(): any;
+};
+export declare type CurveType = BasicCurve & {
+    a: bigint;
+    d: bigint;
+    hash: CHash;
+    randomBytes: (bytesLength?: number) => Uint8Array;
+    adjustScalarBytes?: (bytes: Uint8Array) => Uint8Array;
+    domain?: (data: Uint8Array, ctx: Uint8Array, phflag: boolean) => Uint8Array;
+    uvRatio?: (u: bigint, v: bigint) => {
+        isValid: boolean;
+        value: bigint;
+    };
+    preHash?: CHash;
+};
+declare function validateOpts(curve: CurveType): Readonly<{
+    readonly nBitLength: number;
+    readonly nByteLength: number;
+    readonly P: bigint;
+    readonly n: bigint;
+    readonly h: bigint;
+    readonly Gx: bigint;
+    readonly Gy: bigint;
+    readonly a: bigint;
+    readonly d: bigint;
+    readonly hash: CHash;
+    readonly randomBytes: (bytesLength?: number | undefined) => Uint8Array;
+    readonly adjustScalarBytes?: ((bytes: Uint8Array) => Uint8Array) | undefined;
+    readonly domain?: ((data: Uint8Array, ctx: Uint8Array, phflag: boolean) => Uint8Array) | undefined;
+    readonly uvRatio?: ((u: bigint, v: bigint) => {
+        isValid: boolean;
+        value: bigint;
+    }) | undefined;
+    readonly preHash?: CHash | undefined;
+}>;
+export interface SignatureType {
+    readonly r: PointType;
+    readonly s: bigint;
+    assertValidity(): SignatureType;
+    toRawBytes(): Uint8Array;
+    toHex(): string;
+}
+export declare type SignatureConstructor = {
+    new (r: PointType, s: bigint): SignatureType;
+    fromHex(hex: Hex): SignatureType;
+};
+export interface ExtendedPointType extends Group<ExtendedPointType> {
+    readonly x: bigint;
+    readonly y: bigint;
+    readonly z: bigint;
+    readonly t: bigint;
+    multiply(scalar: number | bigint, affinePoint?: PointType): ExtendedPointType;
+    multiplyUnsafe(scalar: number | bigint): ExtendedPointType;
+    isSmallOrder(): boolean;
+    isTorsionFree(): boolean;
+    toAffine(invZ?: bigint): PointType;
+}
+export interface ExtendedPointConstructor extends GroupConstructor<ExtendedPointType> {
+    new (x: bigint, y: bigint, z: bigint, t: bigint): ExtendedPointType;
+    fromAffine(p: PointType): ExtendedPointType;
+    toAffineBatch(points: ExtendedPointType[]): PointType[];
+    normalizeZ(points: ExtendedPointType[]): ExtendedPointType[];
+}
+export interface PointType extends Group<PointType> {
+    readonly x: bigint;
+    readonly y: bigint;
+    _setWindowSize(windowSize: number): void;
+    toRawBytes(isCompressed?: boolean): Uint8Array;
+    toHex(isCompressed?: boolean): string;
+    isTorsionFree(): boolean;
+}
+export interface PointConstructor extends GroupConstructor<PointType> {
+    new (x: bigint, y: bigint): PointType;
+    fromHex(hex: Hex): PointType;
+    fromPrivateKey(privateKey: PrivKey): PointType;
+}
+export declare type PubKey = Hex | PointType;
+export declare type SigType = Hex | SignatureType;
+export declare type CurveFn = {
+    CURVE: ReturnType<typeof validateOpts>;
+    getPublicKey: (privateKey: PrivKey, isCompressed?: boolean) => Uint8Array;
+    sign: (message: Hex, privateKey: Hex) => Uint8Array;
+    verify: (sig: SigType, message: Hex, publicKey: PubKey) => boolean;
+    Point: PointConstructor;
+    ExtendedPoint: ExtendedPointConstructor;
+    Signature: SignatureConstructor;
+    utils: {
+        mod: (a: bigint, b?: bigint) => bigint;
+        invert: (number: bigint, modulo?: bigint) => bigint;
+        randomPrivateKey: () => Uint8Array;
+        getExtendedPublicKey: (key: PrivKey) => {
+            head: Uint8Array;
+            prefix: Uint8Array;
+            scalar: bigint;
+            point: PointType;
+            pointBytes: Uint8Array;
+        };
+    };
+};
+export declare function twistedEdwards(curveDef: CurveType): CurveFn;
+export {};