feat: store x509 certs in the keychain (#3062)

Adds `importX509`/`exportX509`/etc methods to the keychain to
enable storing x509 certificates securely.

Author: achingbrain

packages/keychain/package.json

@@ -71,6 +71,7 @@
   },
   "devDependencies": {
     "@libp2p/logger": "^5.1.13",
+    "@peculiar/x509": "^1.12.3",
     "aegir": "^45.1.1",
     "datastore-core": "^10.0.2"
   },

packages/keychain/src/index.ts

@@ -105,6 +105,13 @@ export interface KeyInfo {
   name: string
 }
 
+export interface X509Info {
+  /**
+   * The local key name
+   */
+  name: string
+}
+
 export interface Keychain {
   /**
    * Find a key by name
@@ -201,6 +208,32 @@ export interface Keychain {
    */
   listKeys(): Promise<KeyInfo[]>
 
+  /**
+   * Import an X509 certificate in PEM format
+   */
+  importX509 (name: string, pem: string): Promise<void>
+
+  /**
+   * Export an X509 certificate in PEM format
+   */
+  exportX509 (name: string): Promise<string>
+
+  /**
+   * Removes an X509 certificate from the keychain
+   */
+  removeX509 (name: string): Promise<void>
+
+  /**
+   * List all certificates.
+   *
+   * @example
+   *
+   * ```TypeScript
+   * const certs = await libp2p.keychain.listX509()
+   * ```
+   */
+  listX509(): Promise<X509Info[]>
+
   /**
    * Rotate keychain password and re-encrypt all associated keys
    *

packages/keychain/src/keychain.ts

@@ -10,12 +10,13 @@ import { sha256 } from 'multiformats/hashes/sha2'
 import sanitize from 'sanitize-filename'
 import { fromString as uint8ArrayFromString } from 'uint8arrays/from-string'
 import { toString as uint8ArrayToString } from 'uint8arrays/to-string'
-import { exportPrivateKey } from './utils/export.js'
-import { importPrivateKey } from './utils/import.js'
-import type { KeychainComponents, KeychainInit, Keychain as KeychainInterface, KeyInfo } from './index.js'
+import { exportPrivateKey, exporter } from './utils/export.js'
+import { importPrivateKey, importer } from './utils/import.js'
+import type { KeychainComponents, KeychainInit, Keychain as KeychainInterface, KeyInfo, X509Info } from './index.js'
 import type { Logger, PrivateKey } from '@libp2p/interface'
 
 const keyPrefix = '/pkcs8/'
+const certPrefix = '/x509/'
 const infoPrefix = '/info/'
 const privates = new WeakMap<object, { dek: string }>()
 
@@ -63,8 +64,8 @@ async function randomDelay (): Promise<void> {
 /**
  * Converts a key name into a datastore name
  */
-function DsName (name: string): Key {
-  return new Key(keyPrefix + name)
+function DsName (prefix: string, name: string): Key {
+  return new Key(prefix + name)
 }
 
 /**
@@ -206,7 +207,7 @@ export class Keychain implements KeychainInterface {
       await randomDelay()
       throw new InvalidParametersError('Key is required')
     }
-    const datastoreName = DsName(name)
+    const datastoreName = DsName(keyPrefix, name)
     const exists = await this.components.datastore.has(datastoreName)
     if (exists) {
       await randomDelay()
@@ -248,7 +249,7 @@ export class Keychain implements KeychainInterface {
       throw new InvalidParametersError(`Invalid key name '${name}'`)
     }
 
-    const datastoreName = DsName(name)
+    const datastoreName = DsName(keyPrefix, name)
     try {
       const res = await this.components.datastore.get(datastoreName)
       const pem = uint8ArrayToString(res)
@@ -273,7 +274,7 @@ export class Keychain implements KeychainInterface {
       throw new InvalidParametersError(`Invalid key name '${name}'`)
     }
 
-    const datastoreName = DsName(name)
+    const datastoreName = DsName(keyPrefix, name)
     const keyInfo = await this.findKeyByName(name)
     const batch = this.components.datastore.batch()
     batch.delete(datastoreName)
@@ -317,8 +318,8 @@ export class Keychain implements KeychainInterface {
       await randomDelay()
       throw new InvalidParametersError(`Invalid new key name '${newName}'`)
     }
-    const oldDatastoreName = DsName(oldName)
-    const newDatastoreName = DsName(newName)
+    const oldDatastoreName = DsName(keyPrefix, oldName)
+    const newDatastoreName = DsName(keyPrefix, newName)
     const oldInfoName = DsInfoName(oldName)
     const newInfoName = DsInfoName(newName)
 
@@ -347,6 +348,99 @@ export class Keychain implements KeychainInterface {
     }
   }
 
+  /**
+   * List all the certificates
+   */
+  async listX509 (): Promise<X509Info[]> {
+    const query = {
+      prefix: certPrefix
+    }
+
+    const info = []
+    for await (const value of this.components.datastore.query(query)) {
+      info.push({
+        name: value.key.toString().replace(certPrefix, '')
+      })
+    }
+
+    return info
+  }
+
+  async importX509 (name: string, pem: string): Promise<void> {
+    try {
+      if (!validateKeyName(name)) {
+        throw new InvalidParametersError(`Invalid certificate name '${name}'`)
+      }
+
+      if (pem == null) {
+        throw new InvalidParametersError('PEM is required')
+      }
+
+      if (!pem.includes('-----BEGIN CERTIFICATE-----') && !pem.includes('-----END CERTIFICATE-----')) {
+        throw new InvalidParametersError('PEM was invalid')
+      }
+
+      const datastoreName = DsName(certPrefix, name)
+
+      const exists = await this.components.datastore.has(datastoreName)
+      if (exists) {
+        throw new InvalidParametersError(`Certificate '${name}' already exists`)
+      }
+
+      const cached = privates.get(this)
+
+      if (cached == null) {
+        throw new InvalidParametersError('dek missing')
+      }
+
+      const dek = cached.dek
+      const dsPem = await exporter(uint8ArrayFromString(pem), dek)
+      await this.components.datastore.put(datastoreName, uint8ArrayFromString(dsPem))
+    } catch (err) {
+      await randomDelay()
+      throw err
+    }
+  }
+
+  async exportX509 (name: string): Promise<string> {
+    try {
+      if (!validateKeyName(name)) {
+        throw new InvalidParametersError(`Invalid key name '${name}'`)
+      }
+
+      const datastoreName = DsName(certPrefix, name)
+      const res = await this.components.datastore.get(datastoreName)
+      const encryptedPem = uint8ArrayToString(res)
+      const cached = privates.get(this)
+
+      if (cached == null) {
+        throw new InvalidParametersError('dek missing')
+      }
+
+      const dek = cached.dek
+      const buf = await importer(encryptedPem, dek)
+
+      return uint8ArrayToString(buf)
+    } catch (err: any) {
+      await randomDelay()
+      throw err
+    }
+  }
+
+  async removeX509 (name: string): Promise<void> {
+    try {
+      if (!validateKeyName(name) || name === this.self) {
+        throw new InvalidParametersError(`Invalid key name '${name}'`)
+      }
+
+      const datastoreName = DsName(certPrefix, name)
+      await this.components.datastore.delete(datastoreName)
+    } catch (err) {
+      await randomDelay()
+      throw err
+    }
+  }
+
   /**
    * Rotate keychain password and re-encrypt all associated keys
    */
@@ -381,24 +475,33 @@ export class Keychain implements KeychainInterface {
         this.init.dek?.hash)
       : ''
     privates.set(this, { dek: newDek })
-    const keys = await this.listKeys()
-    for (const key of keys) {
-      const res = await this.components.datastore.get(DsName(key.name))
+
+    const batch = this.components.datastore.batch()
+
+    for (const key of await this.listKeys()) {
+      const res = await this.components.datastore.get(DsName(keyPrefix, key.name))
       const pem = uint8ArrayToString(res)
       const privateKey = await importPrivateKey(pem, oldDek)
       const password = newDek.toString()
       const keyAsPEM = await exportPrivateKey(privateKey, password, privateKey.type === 'RSA' ? 'pkcs-8' : 'libp2p-key')
 
-      // Update stored key
-      const batch = this.components.datastore.batch()
-      const keyInfo = {
-        name: key.name,
-        id: key.id
-      }
-      batch.put(DsName(key.name), uint8ArrayFromString(keyAsPEM))
-      batch.put(DsInfoName(key.name), uint8ArrayFromString(JSON.stringify(keyInfo)))
-      await batch.commit()
+      // add to batch
+      batch.put(DsName(keyPrefix, key.name), uint8ArrayFromString(keyAsPEM))
     }
+
+    for (const key of await this.listX509()) {
+      // decrypt using old password and encrypt using new
+      const res = await this.components.datastore.get(DsName(certPrefix, key.name))
+      const pem = uint8ArrayToString(res)
+      const decrypted = await importer(pem, oldDek)
+      const encrypted = await exporter(decrypted, newDek)
+
+      // add to batch
+      batch.put(DsName(certPrefix, key.name), uint8ArrayFromString(encrypted))
+    }
+
+    await batch.commit()
+
     this.log('keychain reconstructed')
   }
 }

packages/keychain/test/certificates.spec.ts

@@ -0,0 +1,102 @@
+import { generateKeyPair } from '@libp2p/crypto/keys'
+import { defaultLogger } from '@libp2p/logger'
+import { expect } from 'aegir/chai'
+import { MemoryDatastore } from 'datastore-core/memory'
+import { Keychain as KeychainClass } from '../src/keychain.js'
+import { createSelfSigned } from './fixtures/create-certificate.js'
+import type { Keychain } from '../src/index.js'
+import type { Datastore } from 'interface-datastore'
+
+describe('certificates', () => {
+  const passPhrase = 'this is not a secure phrase'
+  const logger = defaultLogger()
+  let kc: Keychain
+  let datastore: Datastore
+
+  beforeEach(async () => {
+    datastore = new MemoryDatastore()
+
+    kc = new KeychainClass({
+      datastore,
+      logger
+    }, { pass: passPhrase })
+  })
+
+  it('can store a ECDSA certificate', async () => {
+    const keyName = `key-${Math.random()}`
+    const certName = `cert-${Math.random()}`
+
+    const key = await generateKeyPair('ECDSA')
+    await kc.importKey(keyName, key)
+
+    const cert = await createSelfSigned(key)
+
+    const pem = cert.toString('pem')
+    await kc.importX509(certName, pem)
+
+    const stored = await kc.exportX509(certName)
+    expect(stored).to.equal(pem)
+  })
+
+  it('can store a RSA certificate', async () => {
+    const keyName = `key-${Math.random()}`
+    const certName = `cert-${Math.random()}`
+
+    const key = await generateKeyPair('RSA')
+    await kc.importKey(keyName, key)
+
+    const cert = await createSelfSigned(key)
+
+    const pem = cert.toString('pem')
+    await kc.importX509(certName, pem)
+
+    const stored = await kc.exportX509(certName)
+    expect(stored).to.equal(pem)
+  })
+
+  it('can remove a certificate', async () => {
+    const keyName = `key-${Math.random()}`
+    const certName = `cert-${Math.random()}`
+
+    const key = await generateKeyPair('RSA')
+    await kc.importKey(keyName, key)
+
+    const cert = await createSelfSigned(key)
+
+    const pem = cert.toString('pem')
+    await kc.importX509(certName, pem)
+
+    await kc.removeX509(certName)
+
+    await expect(kc.exportX509(certName)).to.eventually.be.rejected
+      .with.property('name', 'NotFoundError')
+  })
+
+  it('can list all certificates', async () => {
+    const keyName = `key-${Math.random()}`
+    const certName1 = `cert-${Math.random()}-1`
+    const certName2 = `cert-${Math.random()}-2`
+    const certName3 = `cert-${Math.random()}-3`
+
+    const key = await generateKeyPair('RSA')
+    await kc.importKey(keyName, key)
+
+    const cert1 = await createSelfSigned(key)
+    const cert2 = await createSelfSigned(key)
+    const cert3 = await createSelfSigned(key)
+
+    await kc.importX509(certName1, cert1.toString('pem'))
+    await kc.importX509(certName2, cert2.toString('pem'))
+    await kc.importX509(certName3, cert3.toString('pem'))
+
+    const certs = await kc.listX509()
+
+    expect(certs).to.deep.equal([{
+      name: certName1
+    }, {
+      name: certName2
+    }, {
+      name: certName3
+    }])
+  })
+})

packages/keychain/test/fixtures/create-certificate.ts

@@ -0,0 +1,25 @@
+import { privateKeyToCryptoKeyPair } from '@libp2p/crypto/keys'
+import * as x509 from '@peculiar/x509'
+import type { PrivateKey } from '@libp2p/interface'
+
+export async function createSelfSigned (privateKey: PrivateKey): Promise<x509.X509Certificate> {
+  const keys = await privateKeyToCryptoKeyPair(privateKey)
+
+  return x509.X509CertificateGenerator.createSelfSigned({
+    serialNumber: '01',
+    name: 'CN=Test',
+    notBefore: new Date('2020/01/01'),
+    notAfter: new Date('2020/01/02'),
+    signingAlgorithm: {
+      name: 'RSASSA-PKCS1-v1_5',
+      hash: 'SHA-256'
+    },
+    keys,
+    extensions: [
+      new x509.BasicConstraintsExtension(true, 2, true),
+      new x509.ExtendedKeyUsageExtension(['1.2.3.4.5.6.7', '2.3.4.5.6.7.8'], true),
+      new x509.KeyUsagesExtension(x509.KeyUsageFlags.keyCertSign | x509.KeyUsageFlags.cRLSign, true),
+      await x509.SubjectKeyIdentifierExtension.create(keys.publicKey)
+    ]
+  })
+}