Add docs on Schnorr

Author: paulmillr

README.md

@@ -206,6 +206,23 @@ const publicKey2 = secp.recoverPublicKey(sigR, keccak256(msg), { prehash: false
 
 Recover public key from Signature instance with `recovery` bit set.
 
+### schnorr
+
+```ts
+import { schnorr } from '@noble/secp256k1';
+const { secretKey, publicKey } = schnorr.keygen();
+const msg = new TextEncoder().encode('hello noble');
+const sig = schnorr.sign(msg, secretKey);
+const isValid = schnorr.verify(sig, msg, publicKey);
+
+const sig = await schnorr.signAsync(msg, secretKey);
+const isValid = await schnorr.verifyAsync(sig, msg, publicKey);
+```
+
+Schnorr
+signatures compliant with [BIP340](https://github.com/bitcoin/bips/blob/master/bip-0340.mediawiki)
+are supported.
+
 ### utils
 
 A bunch of useful **utilities** are also exposed:
@@ -326,9 +343,39 @@ Point.fromBytes x 13,656 ops/sec @ 73μs/op
 
 ## Upgrading
 
+### v2 to v3
+
+v3 brings the package closer to noble-curves v2.
+
+- Add Schnorr signatures
+- Most methods now expect Uint8Array, string hex inputs are prohibited
+- Add `keygen`, `keygenAsync` method
+- sign, verify: Switch to **prehashed messages**. Instead of
+  messageHash, the methods now expect unhashed message.
+  To bring back old behavior, use option `{prehash: false}`
+- sign, verify: Switch to **Uint8Array signatures** (format: 'compact') by default.
+- verify: **der format must be explicitly specified** in `{format: 'der'}`.
+  This reduces malleability
+- verify: **prohibit Signature-instance** signature. User must now always do
+  `signature.toBytes()`
+- Node v20.19 is now the minimum required version
+- Various small changes for types
+- etc: hashes are now set in `hashes` object. Also sha256 needs to be set now for `prehash: true`:
+
+```js
+// before
+// etc.hmacSha256Sync = (key, ...messages) => hmac(sha256, key, etc.concatBytes(...messages));
+// etc.hmacSha256Async = (key, ...messages) => Promise.resolve(etc.hmacSha256Sync(key, ...messages));
+// after
+hashes.hmacSha256 = (key, msg) => hmac(sha256, key, msg);
+hashes.sha256 = sha256;
+hashes.hmacSha256Async = async (key, msg) => hmac(sha256, key, msg);
+hashes.sha256Async = async (msg) => sha256(msg);
+```
+
 ### v1 to v2
 
-noble-secp256k1 v2 improves security and reduces attack surface.
+v2 improves security and reduces attack surface.
 The goal of v2 is to provide minimum possible JS library which is safe and fast.
 
 - Disable some features to ensure 4x smaller than v1, 5KB bundle size:

index.d.ts

@@ -230,7 +230,8 @@ type KeysSecPub = {
     secretKey: Bytes;
     publicKey: Bytes;
 };
-declare const keygen: (seed?: Bytes) => KeysSecPub;
+type KeygenFn = (seed?: Bytes) => KeysSecPub;
+declare const keygen: KeygenFn;
 /** Math, hex, byte helpers. Not in `utils` because utils share API with noble-curves. */
 declare const etc: {
     hexToBytes: (hex: string) => Bytes;
@@ -254,26 +255,25 @@ declare const utils: {
  * Schnorr public key is just `x` coordinate of Point as per BIP340.
  */
 declare const pubSchnorr: (secretKey: Bytes) => Bytes;
+declare const keygenSchnorr: KeygenFn;
 /**
  * Creates Schnorr signature as per BIP340. Verifies itself before returning anything.
  * auxRand is optional and is not the sole source of k generation: bad CSPRNG won't be dangerous.
  */
 declare const signSchnorr: (message: Bytes, secretKey: Bytes, auxRand?: Bytes) => Bytes;
-declare const signAsyncSchnorr: (message: Bytes, secretKey: Bytes, auxRand?: Bytes) => Promise<Bytes>;
+declare const signSchnorrAsync: (message: Bytes, secretKey: Bytes, auxRand?: Bytes) => Promise<Bytes>;
 /**
  * Verifies Schnorr signature.
  * Will swallow errors & return false except for initial type validation of arguments.
  */
 declare const verifySchnorr: (s: Bytes, m: Bytes, p: Bytes) => boolean;
-declare const verifyAsyncSchnorr: (s: Bytes, m: Bytes, p: Bytes) => Promise<boolean>;
+declare const verifySchnorrAsync: (s: Bytes, m: Bytes, p: Bytes) => Promise<boolean>;
 declare const schnorr: {
+    keygen: typeof keygenSchnorr;
     getPublicKey: typeof pubSchnorr;
     sign: typeof signSchnorr;
     verify: typeof verifySchnorr;
+    signAsync: typeof signSchnorrAsync;
+    verifyAsync: typeof verifySchnorrAsync;
 };
-declare const schnorrAsync: {
-    getPublicKey: typeof pubSchnorr;
-    signAsync: typeof signAsyncSchnorr;
-    verifyAsync: typeof verifyAsyncSchnorr;
-};
-export { etc, getPublicKey, getSharedSecret, hash, hashes, keygen, Point, recoverPublicKey, recoverPublicKeyAsync, schnorr, schnorrAsync, sign, signAsync, Signature, utils, verify, verifyAsync, };
+export { etc, getPublicKey, getSharedSecret, hash, hashes, keygen, Point, recoverPublicKey, recoverPublicKeyAsync, schnorr, sign, signAsync, Signature, utils, verify, verifyAsync };

index.js

@@ -805,10 +805,11 @@ const randomSecretKey = (seed = randomBytes(lengths.seed)) => {
     const num = M(bytesToNumBE(seed), N - 1n);
     return numTo32b(num + 1n);
 };
-const keygen = (seed) => {
+const createKeygen = (getPublicKey) => (seed) => {
     const secretKey = randomSecretKey(seed);
     return { secretKey, publicKey: getPublicKey(secretKey) };
 };
+const keygen = createKeygen(getPublicKey);
 /** Math, hex, byte helpers. Not in `utils` because utils share API with noble-curves. */
 const etc = {
     hexToBytes: hexToBytes,
@@ -863,6 +864,7 @@ const challengeAsync = async (...args) => bytesModN(await taggedHashAsync(T_CHAL
 const pubSchnorr = (secretKey) => {
     return extpubSchnorr(secretKey).px; // d'=int(sk). Fail if d'=0 or d'≥n. Ret bytes(d'⋅G)
 };
+const keygenSchnorr = createKeygen(pubSchnorr);
 // Common preparation fn for both sync and async signing
 const prepSigSchnorr = (message, secretKey, auxRand) => {
     const { px, d } = extpubSchnorr(secretKey);
@@ -900,7 +902,7 @@ const signSchnorr = (message, secretKey, auxRand = randomBytes(L)) => {
         err(E_INVSIG);
     return sig;
 };
-const signAsyncSchnorr = async (message, secretKey, auxRand = randomBytes(L)) => {
+const signSchnorrAsync = async (message, secretKey, auxRand = randomBytes(L)) => {
     const { m, px, d, a } = prepSigSchnorr(message, secretKey, auxRand);
     const aux = await taggedHashAsync(T_AUX, a);
     // Let t be the byte-wise xor of bytes(d) and hash/aux(a)
@@ -912,7 +914,7 @@ const signAsyncSchnorr = async (message, secretKey, auxRand = randomBytes(L)) =>
     const e = await challengeAsync(rx, px, m);
     const sig = createSigSchnorr(k, rx, e, d);
     // If Verify(bytes(P), m, sig) (see below) returns failure, abort
-    if (!(await verifyAsyncSchnorr(sig, m, px)))
+    if (!(await verifySchnorrAsync(sig, m, px)))
         err(E_INVSIG);
     return sig;
 };
@@ -956,16 +958,14 @@ const _verifSchnorr = (signature, message, publicKey, challengeFn) => {
  * Will swallow errors & return false except for initial type validation of arguments.
  */
 const verifySchnorr = (s, m, p) => _verifSchnorr(s, m, p, challenge);
-const verifyAsyncSchnorr = async (s, m, p) => _verifSchnorr(s, m, p, challengeAsync);
+const verifySchnorrAsync = async (s, m, p) => _verifSchnorr(s, m, p, challengeAsync);
 const schnorr = {
+    keygen: keygenSchnorr,
     getPublicKey: pubSchnorr,
     sign: signSchnorr,
     verify: verifySchnorr,
-};
-const schnorrAsync = {
-    getPublicKey: pubSchnorr,
-    signAsync: signAsyncSchnorr,
-    verifyAsync: verifyAsyncSchnorr,
+    signAsync: signSchnorrAsync,
+    verifyAsync: verifySchnorrAsync,
 };
 // ## Precomputes
 // --------------
@@ -1043,4 +1043,4 @@ const wNAF = (n) => {
     return { p, f }; // return both real and fake points for JIT
 };
 // !! Remove the export below to easily use in REPL / browser console
-export { etc, getPublicKey, getSharedSecret, hash, hashes, keygen, Point, recoverPublicKey, recoverPublicKeyAsync, schnorr, schnorrAsync, sign, signAsync, Signature, utils, verify, verifyAsync, };
+export { etc, getPublicKey, getSharedSecret, hash, hashes, keygen, Point, recoverPublicKey, recoverPublicKeyAsync, schnorr, sign, signAsync, Signature, utils, verify, verifyAsync };

index.ts

@@ -876,10 +876,12 @@ const randomSecretKey = (seed = randomBytes(lengths.seed)) => {
 };
 
 type KeysSecPub = { secretKey: Bytes; publicKey: Bytes };
-const keygen = (seed?: Bytes): KeysSecPub => {
+type KeygenFn = (seed?: Bytes) => KeysSecPub;
+const createKeygen = (getPublicKey: (secretKey: Bytes) => Bytes) => (seed?: Bytes): KeysSecPub => {
   const secretKey = randomSecretKey(seed);
   return { secretKey, publicKey: getPublicKey(secretKey) };
-};
+}
+const keygen: KeygenFn = createKeygen(getPublicKey);
 
 /** Math, hex, byte helpers. Not in `utils` because utils share API with noble-curves. */
 const etc = {
@@ -942,6 +944,8 @@ const pubSchnorr = (secretKey: Bytes): Bytes => {
   return extpubSchnorr(secretKey).px; // d'=int(sk). Fail if d'=0 or d'≥n. Ret bytes(d'⋅G)
 };
 
+const keygenSchnorr: KeygenFn = createKeygen(pubSchnorr);
+
 // Common preparation fn for both sync and async signing
 const prepSigSchnorr = (message: Bytes, secretKey: Bytes, auxRand: Bytes) => {
   const { px, d } = extpubSchnorr(secretKey);
@@ -981,7 +985,7 @@ const signSchnorr = (message: Bytes, secretKey: Bytes, auxRand: Bytes = randomBy
   return sig;
 };
 
-const signAsyncSchnorr = async (
+const signSchnorrAsync = async (
   message: Bytes,
   secretKey: Bytes,
   auxRand: Bytes = randomBytes(L)
@@ -997,7 +1001,7 @@ const signAsyncSchnorr = async (
   const e = await challengeAsync(rx, px, m);
   const sig = createSigSchnorr(k, rx, e, d);
   // If Verify(bytes(P), m, sig) (see below) returns failure, abort
-  if (!(await verifyAsyncSchnorr(sig, m, px))) err(E_INVSIG);
+  if (!(await verifySchnorrAsync(sig, m, px))) err(E_INVSIG);
   return sig;
 };
 
@@ -1050,27 +1054,23 @@ const _verifSchnorr = (
  */
 const verifySchnorr = (s: Bytes, m: Bytes, p: Bytes): boolean =>
   _verifSchnorr(s, m, p, challenge) as boolean;
-const verifyAsyncSchnorr = async (s: Bytes, m: Bytes, p: Bytes): Promise<boolean> =>
+const verifySchnorrAsync = async (s: Bytes, m: Bytes, p: Bytes): Promise<boolean> =>
   _verifSchnorr(s, m, p, challengeAsync) as Promise<boolean>;
 
 const schnorr: {
+  keygen: typeof keygenSchnorr,
   getPublicKey: typeof pubSchnorr;
   sign: typeof signSchnorr;
   verify: typeof verifySchnorr;
+  signAsync: typeof signSchnorrAsync,
+  verifyAsync: typeof verifySchnorrAsync
 } = {
+  keygen: keygenSchnorr,
   getPublicKey: pubSchnorr,
   sign: signSchnorr,
   verify: verifySchnorr,
-};
-
-const schnorrAsync: {
-  getPublicKey: typeof pubSchnorr;
-  signAsync: typeof signAsyncSchnorr;
-  verifyAsync: typeof verifyAsyncSchnorr;
-} = {
-  getPublicKey: pubSchnorr,
-  signAsync: signAsyncSchnorr,
-  verifyAsync: verifyAsyncSchnorr,
+  signAsync: signSchnorrAsync,
+  verifyAsync: verifySchnorrAsync,
 };
 
 // ## Precomputes
@@ -1152,20 +1152,11 @@ const wNAF = (n: bigint): { p: Point; f: Point } => {
 // !! Remove the export below to easily use in REPL / browser console
 export {
   etc,
-  getPublicKey,
-  getSharedSecret,
-  hash,
-  hashes,
+  getPublicKey, getSharedSecret,
+  hash, hashes,
   keygen,
-  Point,
-  recoverPublicKey,
-  recoverPublicKeyAsync,
-  schnorr,
-  schnorrAsync,
-  sign,
-  signAsync,
-  Signature,
-  utils,
-  verify,
-  verifyAsync,
+  Point, recoverPublicKey, recoverPublicKeyAsync, schnorr, sign, signAsync,
+
+  Signature, utils, verify, verifyAsync
 };
+