Make main ops async, support CryptoKeys, and use Web Crypto if available

Fixes #19

README.md

@@ -27,18 +27,18 @@ npm install age-encryption
 ```ts
 import * as age from "age-encryption"
 
-const identity = age.generateIdentity()
-const recipient = age.identityToRecipient(identity)
+const identity = await age.generateIdentity()
+const recipient = await age.identityToRecipient(identity)
 console.log(identity)
 console.log(recipient)
 
 const e = new age.Encrypter()
 e.addRecipient(recipient)
-const ciphertext = e.encrypt("Hello, age!")
+const ciphertext = await e.encrypt("Hello, age!")
 
 const d = new age.Decrypter()
 d.addIdentity(identity)
-const out = d.decrypt(ciphertext, "text")
+const out = await d.decrypt(ciphertext, "text")
 console.log(out)
 ```
 
@@ -49,11 +49,11 @@ import { Encrypter, Decrypter } from "age-encryption"
 
 const e = new Encrypter()
 e.setPassphrase("burst-swarm-slender-curve-ability-various-crystal-moon-affair-three")
-const ciphertext = e.encrypt("Hello, age!")
+const ciphertext = await e.encrypt("Hello, age!")
 
 const d = new Decrypter()
 d.addPassphrase("burst-swarm-slender-curve-ability-various-crystal-moon-affair-three")
-const out = d.decrypt(ciphertext, "text")
+const out = await d.decrypt(ciphertext, "text")
 console.log(out)
 ```
 
@@ -81,18 +81,20 @@ Then, you can use it like this
 ```html
 <script src="age.js"></script>
 <script>
-    const identity = age.generateIdentity()
-    const recipient = age.identityToRecipient(identity)
+(async () => {
+    const identity = await age.generateIdentity()
+    const recipient = await age.identityToRecipient(identity)
     console.log(identity)
     console.log(recipient)
 
     const e = new age.Encrypter()
     e.addRecipient(recipient)
-    const ciphertext = e.encrypt("Hello, age!")
+    const ciphertext = await e.encrypt("Hello, age!")
 
     const d = new age.Decrypter()
     d.addIdentity(identity)
-    const out = d.decrypt(ciphertext, "text")
+    const out = await d.decrypt(ciphertext, "text")
     console.log(out)
+})()
 </script>
 ```

lib/index.ts

@@ -2,25 +2,32 @@ import { bech32 } from "@scure/base"
 import { hmac } from "@noble/hashes/hmac"
 import { hkdf } from "@noble/hashes/hkdf"
 import { sha256 } from "@noble/hashes/sha256"
-import { x25519 } from "@noble/curves/ed25519"
 import { randomBytes } from "@noble/hashes/utils"
+import * as x25519 from "./x25519.js"
 import { scryptUnwrap, scryptWrap, x25519Identity, x25519Unwrap, x25519Wrap } from "./recipients.js"
 import { encodeHeader, encodeHeaderNoMAC, parseHeader, Stanza } from "./format.js"
 import { decryptSTREAM, encryptSTREAM } from "./stream.js"
 
-export function generateIdentity(): string {
+export function generateIdentity(): Promise<string> {
   const scalar = randomBytes(32)
-  return bech32.encode("AGE-SECRET-KEY-", bech32.toWords(scalar)).toUpperCase()
+  const identity = bech32.encode("AGE-SECRET-KEY-", bech32.toWords(scalar)).toUpperCase()
+  return Promise.resolve(identity)
 }
 
-export function identityToRecipient(identity: string): string {
-  const res = bech32.decodeToBytes(identity)
-  if (!identity.startsWith("AGE-SECRET-KEY-1") ||
-    res.prefix.toUpperCase() !== "AGE-SECRET-KEY-" ||
-    res.bytes.length !== 32)
-    throw Error("invalid identity")
+export async function identityToRecipient(identity: string | CryptoKey): Promise<string> {
+  let scalar: Uint8Array | CryptoKey
+  if (identity instanceof CryptoKey) {
+    scalar = identity
+  } else {
+    const res = bech32.decodeToBytes(identity)
+    if (!identity.startsWith("AGE-SECRET-KEY-1") ||
+      res.prefix.toUpperCase() !== "AGE-SECRET-KEY-" ||
+      res.bytes.length !== 32)
+      throw Error("invalid identity")
+    scalar = res.bytes
+  }
 
-  const recipient = x25519.scalarMultBase(res.bytes)
+  const recipient = await x25519.scalarMultBase(scalar)
   return bech32.encode("age", bech32.toWords(recipient))
 }
 
@@ -52,7 +59,7 @@ export class Encrypter {
     this.recipients.push(res.bytes)
   }
 
-  encrypt(file: Uint8Array | string): Uint8Array {
+  async encrypt(file: Uint8Array | string): Promise<Uint8Array> {
     if (typeof file === "string") {
       file = new TextEncoder().encode(file)
     }
@@ -61,7 +68,7 @@ export class Encrypter {
     const stanzas: Stanza[] = []
 
     for (const recipient of this.recipients) {
-      stanzas.push(x25519Wrap(fileKey, recipient))
+      stanzas.push(await x25519Wrap(fileKey, recipient))
     }
     if (this.passphrase !== null) {
       stanzas.push(scryptWrap(fileKey, this.passphrase, this.scryptWorkFactor))
@@ -91,7 +98,14 @@ export class Decrypter {
     this.passphrases.push(s)
   }
 
-  addIdentity(s: string): void {
+  addIdentity(s: string | CryptoKey): void {
+    if (s instanceof CryptoKey) {
+      this.identities.push({
+        identity: s,
+        recipient: x25519.scalarMultBase(s),
+      })
+      return
+    }
     const res = bech32.decodeToBytes(s)
     if (!s.startsWith("AGE-SECRET-KEY-1") ||
       res.prefix.toUpperCase() !== "AGE-SECRET-KEY-" ||
@@ -103,11 +117,11 @@ export class Decrypter {
     })
   }
 
-  decrypt(file: Uint8Array, outputFormat?: "uint8array"): Uint8Array
-  decrypt(file: Uint8Array, outputFormat: "text"): string
-  decrypt(file: Uint8Array, outputFormat?: "text" | "uint8array"): Uint8Array | string {
+  async decrypt(file: Uint8Array, outputFormat?: "uint8array"): Promise<Uint8Array>
+  async decrypt(file: Uint8Array, outputFormat: "text"): Promise<string>
+  async decrypt(file: Uint8Array, outputFormat?: "text" | "uint8array"): Promise<string | Uint8Array> {
     const h = parseHeader(file)
-    const fileKey = this.unwrapFileKey(h.recipients)
+    const fileKey = await this.unwrapFileKey(h.recipients)
     if (fileKey === null) {
       throw Error("no identity matched any of the file's recipients")
     }
@@ -127,7 +141,7 @@ export class Decrypter {
     return out
   }
 
-  private unwrapFileKey(recipients: Stanza[]): Uint8Array | null {
+  private async unwrapFileKey(recipients: Stanza[]): Promise<Uint8Array | null> {
     for (const s of recipients) {
       // Ideally this should be implemented by passing all stanzas to the scrypt
       // identity implementation, and letting it throw the error. In practice,
@@ -142,7 +156,7 @@ export class Decrypter {
       }
 
       for (const i of this.identities) {
-        const k = x25519Unwrap(s, i)
+        const k = await x25519Unwrap(s, i)
         if (k !== null) { return k }
       }
     }

lib/recipients.ts

@@ -1,20 +1,20 @@
 import { hkdf } from "@noble/hashes/hkdf"
 import { sha256 } from "@noble/hashes/sha256"
 import { scrypt } from "@noble/hashes/scrypt"
-import { x25519 } from "@noble/curves/ed25519"
 import { chacha20poly1305 } from "@noble/ciphers/chacha"
 import { randomBytes } from "@noble/hashes/utils"
 import { base64nopad } from "@scure/base"
+import * as x25519 from "./x25519.js"
 import { Stanza } from "./format.js"
 
 export interface x25519Identity {
-    identity: Uint8Array, recipient: Uint8Array,
+    identity: Uint8Array | CryptoKey, recipient: Promise<Uint8Array>,
 }
 
-export function x25519Wrap(fileKey: Uint8Array, recipient: Uint8Array): Stanza {
+export async function x25519Wrap(fileKey: Uint8Array, recipient: Uint8Array): Promise<Stanza> {
     const ephemeral = randomBytes(32)
-    const share = x25519.scalarMultBase(ephemeral)
-    const secret = x25519.scalarMult(ephemeral, recipient)
+    const share = await x25519.scalarMultBase(ephemeral)
+    const secret = await x25519.scalarMult(ephemeral, recipient)
 
     const salt = new Uint8Array(share.length + recipient.length)
     salt.set(share)
@@ -24,7 +24,7 @@ export function x25519Wrap(fileKey: Uint8Array, recipient: Uint8Array): Stanza {
     return new Stanza(["X25519", base64nopad.encode(share)], encryptFileKey(fileKey, key))
 }
 
-export function x25519Unwrap(s: Stanza, i: x25519Identity): Uint8Array | null {
+export async function x25519Unwrap(s: Stanza, i: x25519Identity): Promise<Uint8Array | null> {
     if (s.args.length < 1 || s.args[0] !== "X25519") {
         return null
     }
@@ -36,11 +36,12 @@ export function x25519Unwrap(s: Stanza, i: x25519Identity): Uint8Array | null {
         throw Error("invalid X25519 stanza")
     }
 
-    const secret = x25519.scalarMult(i.identity, share)
+    const secret = await x25519.scalarMult(i.identity, share)
 
-    const salt = new Uint8Array(share.length + i.recipient.length)
+    const recipient = await i.recipient
+    const salt = new Uint8Array(share.length + recipient.length)
     salt.set(share)
-    salt.set(i.recipient, share.length)
+    salt.set(recipient, share.length)
 
     const key = hkdf(sha256, secret, salt, "age-encryption.org/v1/X25519", 32)
     return decryptFileKey(s.body, key)

lib/x25519.ts

@@ -0,0 +1,75 @@
+import { x25519 } from "@noble/curves/ed25519"
+
+const exportable = false
+
+let webCryptoOff = false
+
+export function forceWebCryptoOff(off: boolean) {
+    webCryptoOff = off
+}
+
+export const isX25519Supported = (() => {
+    let supported: boolean | undefined
+    return async () => {
+        if (supported === undefined) {
+            try {
+                await crypto.subtle.importKey("raw", x25519.GuBytes, { name: "X25519" }, exportable, [])
+                supported = true
+            } catch { supported = false }
+        }
+        return supported
+    }
+})()
+
+export async function scalarMult(scalar: Uint8Array | CryptoKey, u: Uint8Array): Promise<Uint8Array> {
+    if (!(await isX25519Supported()) || webCryptoOff) {
+        if (scalar instanceof CryptoKey) {
+            throw new Error("CryptoKey provided but X25519 WebCrypto is not supported")
+        }
+        return x25519.scalarMult(scalar, u)
+    }
+    let key: CryptoKey
+    if (scalar instanceof CryptoKey) {
+        key = scalar
+    } else {
+        key = await importX25519Key(scalar)
+    }
+    const peer = await crypto.subtle.importKey("raw", u, { name: "X25519" }, exportable, [])
+    // 256 bits is the fixed size of a X25519 shared secret. It's kind of
+    // worrying that the WebCrypto API encourages truncating it.
+    return new Uint8Array(await crypto.subtle.deriveBits({ name: "X25519", public: peer }, key, 256))
+}
+
+export async function scalarMultBase(scalar: Uint8Array | CryptoKey): Promise<Uint8Array> {
+    if (!(await isX25519Supported()) || webCryptoOff) {
+        if (scalar instanceof CryptoKey) {
+            throw new Error("CryptoKey provided but X25519 WebCrypto is not supported")
+        }
+        return x25519.scalarMultBase(scalar)
+    }
+    // The WebCrypto API simply doesn't support deriving public keys from
+    // private keys. importKey returns only a CryptoKey (unlike generateKey
+    // which returns a CryptoKeyPair) despite deriving the public key internally
+    // (judging from the banchmarks, at least on Node.js). Our options are
+    // exporting as JWK, deleting jwk.d, and re-importing (which only works for
+    // exportable keys), or (re-)doing a scalar multiplication by the basepoint
+    // manually. Here we do the latter.
+    return scalarMult(scalar, x25519.GuBytes)
+}
+
+const pkcs8Prefix = new Uint8Array([0x30, 0x2e, 0x02, 0x01, 0x00, 0x30, 0x05, 0x06,
+    0x03, 0x2b, 0x65, 0x6e, 0x04, 0x22, 0x04, 0x20])
+
+async function importX25519Key(key: Uint8Array): Promise<CryptoKey> {
+    // For some reason, the WebCrypto API only supports importing X25519 private
+    // keys as PKCS #8 or JWK (even if it supports importing public keys as raw).
+    // Thankfully since they are always the same length, we can just prepend a
+    // fixed ASN.1 prefix for PKCS #8.
+    if (key.length !== 32) {
+        throw new Error("X25519 private key must be 32 bytes")
+    }
+    const pkcs8 = new Uint8Array([...pkcs8Prefix, ...key])
+    // Annoingly, importKey (at least on Node.js) computes the public key, which
+    // is a waste if we're only going to run deriveBits.
+    return crypto.subtle.importKey("pkcs8", pkcs8, { name: "X25519" }, exportable, ["deriveBits"])
+}

package.json

@@ -28,6 +28,7 @@
         "examples:node": "cd tests/examples && npm install && npm run test:node",
         "examples:bun": "cd tests/examples && bun install && bun run test:bun",
         "examples:esbuild": "cd tests/examples && npm install && npm run test:esbuild",
+        "bench": "vitest bench --run",
         "lint": "eslint .",
         "build": "tsc -p tsconfig.build.json",
         "prepublishOnly": "npm run build"

tests/examples/browser.html

@@ -2,19 +2,21 @@
 <head>
 <script src="age.js"></script>
 <script>
-    const identity = age.generateIdentity()
-    const recipient = age.identityToRecipient(identity)
+(async () => {
+    const identity = await age.generateIdentity()
+    const recipient = await age.identityToRecipient(identity)
     console.log(identity)
     console.log(recipient)
 
     const e = new age.Encrypter()
     e.addRecipient(recipient)
-    const ciphertext = e.encrypt("Hello, age!")
+    const ciphertext = await e.encrypt("Hello, age!")
 
     const d = new age.Decrypter()
     d.addIdentity(identity)
-    const out = d.decrypt(ciphertext, "text")
+    const out = await d.decrypt(ciphertext, "text")
     console.log(out)
 
     globalThis.testDone = true
+})()
 </script>

tests/examples/identity.js

@@ -1,15 +1,15 @@
 import { Encrypter, Decrypter, generateIdentity, identityToRecipient } from "age-encryption"
 
-const identity = generateIdentity()
-const recipient = identityToRecipient(identity)
+const identity = await generateIdentity()
+const recipient = await identityToRecipient(identity)
 console.log(identity)
 console.log(recipient)
 
 const e = new Encrypter()
 e.addRecipient(recipient)
-const ciphertext = e.encrypt("Hello, age!")
+const ciphertext = await e.encrypt("Hello, age!")
 
 const d = new Decrypter()
 d.addIdentity(identity)
-const out = d.decrypt(ciphertext, "text")
+const out = await d.decrypt(ciphertext, "text")
 console.log(out)

tests/examples/passphrase.js

@@ -3,9 +3,9 @@ import { Encrypter, Decrypter } from "age-encryption"
 const e = new Encrypter()
 e.setScryptWorkFactor(12) // this is NOT secure, used to avoid extra work in tests
 e.setPassphrase("burst-swarm-slender-curve-ability-various-crystal-moon-affair-three")
-const ciphertext = e.encrypt("Hello, age!")
+const ciphertext = await e.encrypt("Hello, age!")
 
 const d = new Decrypter()
 d.addPassphrase("burst-swarm-slender-curve-ability-various-crystal-moon-affair-three")
-const out = d.decrypt(ciphertext, "text")
+const out = await d.decrypt(ciphertext, "text")
 console.log(out)