fix: reuse WebRTC certificates between restarts (#3071)

To ensure WebRTC addresses are stable between restarts, store the
generated certiciates in the datastore and the key that they are
generated from in the keychain, if one has been configured.

Author: achingbrain

packages/transport-webrtc/README.md

@@ -230,6 +230,60 @@ await pipe(
 )
 ```
 
+## WebRTC Direct certificate hashes
+
+WebRTC Direct listeners publish the hash of their TLS certificate as part of
+the listening multiaddr.
+
+By default these certificates are generated at start up using an ephemeral
+keypair that only exists while the node is running.
+
+This means that the certificate hashes change when the node is restarted,
+which can be undesirable if multiaddrs are intended to be long lived (e.g.
+if the node is used as a network bootstrapper).
+
+To reuse the same certificate and keypair, configure a persistent datastore
+and the [@libp2p/keychain](https://www.npmjs.com/package/@libp2p/keychain)
+service as part of your service map:
+
+## Example - Reuse TLS certificates after restart
+
+```ts
+import { LevelDatastore } from 'datastore-level'
+import { webRTCDirect } from '@libp2p/webrtc'
+import { keychain } from '@libp2p/keychain'
+import { createLibp2p } from 'libp2p'
+
+// store data on disk between restarts
+const datastore = new LevelDatastore('/path/to/store')
+
+const listener = await createLibp2p({
+  addresses: {
+    listen: [
+      '/ip4/0.0.0.0/udp/0/webrtc-direct'
+    ]
+  },
+  datastore,
+  transports: [
+    webRTCDirect()
+  ],
+  services: {
+    keychain: keychain()
+  }
+})
+
+await listener.start()
+
+console.info(listener.getMultiaddrs())
+// /ip4/...../udp/../webrtc-direct/certhash/foo
+
+await listener.stop()
+await listener.start()
+
+console.info(listener.getMultiaddrs())
+// /ip4/...../udp/../webrtc-direct/certhash/foo
+```
+
 # Install
 
 ```console

packages/transport-webrtc/package.json

@@ -54,8 +54,10 @@
     "@chainsafe/is-ip": "^2.0.2",
     "@chainsafe/libp2p-noise": "^16.0.0",
     "@ipshipyard/node-datachannel": "^0.26.4",
+    "@libp2p/crypto": "^5.0.15",
     "@libp2p/interface": "^2.7.0",
     "@libp2p/interface-internal": "^2.3.9",
+    "@libp2p/keychain": "^5.1.4",
     "@libp2p/peer-id": "^5.1.0",
     "@libp2p/utils": "^6.6.0",
     "@multiformats/multiaddr": "^12.4.0",
@@ -65,6 +67,7 @@
     "any-signal": "^4.1.1",
     "detect-browser": "^5.3.0",
     "get-port": "^7.1.0",
+    "interface-datastore": "^8.3.1",
     "it-length-prefixed": "^10.0.1",
     "it-protobuf-stream": "^2.0.1",
     "it-pushable": "^3.2.3",
@@ -83,11 +86,11 @@
     "uint8arrays": "^5.1.0"
   },
   "devDependencies": {
-    "@libp2p/crypto": "^5.0.15",
     "@libp2p/interface-compliance-tests": "^6.4.2",
     "@libp2p/logger": "^5.1.13",
     "@types/sinon": "^17.0.3",
     "aegir": "^45.1.1",
+    "datastore-core": "^10.0.2",
     "delay": "^6.0.0",
     "it-length": "^3.0.6",
     "it-pair": "^2.0.6",

packages/transport-webrtc/src/constants.ts

@@ -110,3 +110,23 @@ export const MUXER_PROTOCOL = '/webrtc'
  * The protocol used for the signalling stream protocol
  */
 export const SIGNALING_PROTOCOL = '/webrtc-signaling/0.0.1'
+
+/**
+ * Used to store generated certificates in the datastore
+ */
+export const DEFAULT_CERTIFICATE_DATASTORE_KEY = '/libp2p/webrtc-direct/certificate'
+
+/**
+ * Used to store the certificate private key in the keychain
+ */
+export const DEFAULT_CERTIFICATE_PRIVATE_KEY_NAME = 'webrtc-direct-certificate-private-key'
+
+/**
+ * The default type of certificate private key
+ */
+export const DEFAULT_CERTIFICATE_PRIVATE_KEY_TYPE = 'ECDSA'
+
+/**
+ * How long the certificate is valid for
+ */
+export const DEFAULT_CERTIFICATE_LIFESPAN = 365

packages/transport-webrtc/src/index.ts

@@ -206,6 +206,60 @@
  *   }
  * )
  * ```
+ *
+ * ## WebRTC Direct certificate hashes
+ *
+ * WebRTC Direct listeners publish the hash of their TLS certificate as part of
+ * the listening multiaddr.
+ *
+ * By default these certificates are generated at start up using an ephemeral
+ * keypair that only exists while the node is running.
+ *
+ * This means that the certificate hashes change when the node is restarted,
+ * which can be undesirable if multiaddrs are intended to be long lived (e.g.
+ * if the node is used as a network bootstrapper).
+ *
+ * To reuse the same certificate and keypair, configure a persistent datastore
+ * and the [@libp2p/keychain](https://www.npmjs.com/package/@libp2p/keychain)
+ * service as part of your service map:
+ *
+ * @example Reuse TLS certificates after restart
+ *
+ * ```ts
+ * import { LevelDatastore } from 'datastore-level'
+ * import { webRTCDirect } from '@libp2p/webrtc'
+ * import { keychain } from '@libp2p/keychain'
+ * import { createLibp2p } from 'libp2p'
+ *
+ * // store data on disk between restarts
+ * const datastore = new LevelDatastore('/path/to/store')
+ *
+ * const listener = await createLibp2p({
+ *   addresses: {
+ *     listen: [
+ *       '/ip4/0.0.0.0/udp/0/webrtc-direct'
+ *     ]
+ *   },
+ *   datastore,
+ *   transports: [
+ *     webRTCDirect()
+ *   ],
+ *   services: {
+ *     keychain: keychain()
+ *   }
+ * })
+ *
+ * await listener.start()
+ *
+ * console.info(listener.getMultiaddrs())
+ * // /ip4/...../udp/../webrtc-direct/certhash/foo
+ *
+ * await listener.stop()
+ * await listener.start()
+ *
+ * console.info(listener.getMultiaddrs())
+ * // /ip4/...../udp/../webrtc-direct/certhash/foo
+ * ```
  */
 
 import { WebRTCTransport } from './private-to-private/transport.js'

packages/transport-webrtc/src/private-to-public/listener.ts

@@ -3,37 +3,38 @@ import { InvalidParametersError, TypedEventEmitter } from '@libp2p/interface'
 import { getThinWaistAddresses } from '@libp2p/utils/get-thin-waist-addresses'
 import { multiaddr, fromStringTuples } from '@multiformats/multiaddr'
 import { WebRTCDirect } from '@multiformats/multiaddr-matcher'
-import { Crypto } from '@peculiar/webcrypto'
 import getPort from 'get-port'
 import pWaitFor from 'p-wait-for'
 import { CODEC_CERTHASH, CODEC_WEBRTC_DIRECT } from '../constants.js'
 import { connect } from './utils/connect.js'
-import { generateTransportCertificate } from './utils/generate-certificates.js'
 import { createDialerRTCPeerConnection } from './utils/get-rtcpeerconnection.js'
 import { stunListener } from './utils/stun-listener.js'
 import type { DataChannelOptions, TransportCertificate } from '../index.js'
+import type { WebRTCDirectTransportCertificateEvents } from './transport.js'
 import type { DirectRTCPeerConnection } from './utils/get-rtcpeerconnection.js'
 import type { StunServer } from './utils/stun-listener.js'
-import type { PeerId, ListenerEvents, Listener, Upgrader, ComponentLogger, Logger, CounterGroup, Metrics, PrivateKey } from '@libp2p/interface'
+import type { PeerId, ListenerEvents, Listener, Upgrader, ComponentLogger, Logger, CounterGroup, Metrics, PrivateKey, TypedEventTarget } from '@libp2p/interface'
+import type { Keychain } from '@libp2p/keychain'
 import type { Multiaddr } from '@multiformats/multiaddr'
-
-const crypto = new Crypto()
+import type { Datastore } from 'interface-datastore'
 
 export interface WebRTCDirectListenerComponents {
   peerId: PeerId
   privateKey: PrivateKey
   logger: ComponentLogger
   upgrader: Upgrader
+  keychain?: Keychain
+  datastore: Datastore
   metrics?: Metrics
 }
 
 export interface WebRTCDirectListenerInit {
   upgrader: Upgrader
-  certificates?: TransportCertificate[]
+  certificate: TransportCertificate
   maxInboundStreams?: number
   dataChannel?: DataChannelOptions
   rtcConfiguration?: RTCConfiguration | (() => RTCConfiguration | Promise<RTCConfiguration>)
-  useLibjuice?: boolean
+  emitter: TypedEventTarget<WebRTCDirectTransportCertificateEvents>
 }
 
 export interface WebRTCListenerMetrics {
@@ -53,7 +54,7 @@ let UDP_MUX_LISTENERS: UDPMuxServer[] = []
 
 export class WebRTCDirectListener extends TypedEventEmitter<ListenerEvents> implements Listener {
   private listeningMultiaddr?: Multiaddr
-  private certificate?: TransportCertificate
+  private certificate: TransportCertificate
   private stunServer?: StunServer
   private readonly connections: Map<string, DirectRTCPeerConnection>
   private readonly log: Logger
@@ -69,8 +70,8 @@ export class WebRTCDirectListener extends TypedEventEmitter<ListenerEvents> impl
     this.components = components
     this.connections = new Map()
     this.log = components.logger.forComponent('libp2p:webrtc-direct:listener')
-    this.certificate = init.certificates?.[0]
     this.shutdownController = new AbortController()
+    this.certificate = init.certificate
 
     if (components.metrics != null) {
       this.metrics = {
@@ -80,6 +81,12 @@ export class WebRTCDirectListener extends TypedEventEmitter<ListenerEvents> impl
         })
       }
     }
+
+    // inform the transport manager our addresses have changed
+    init.emitter.addEventListener('certificate:renew', evt => {
+      this.certificate = evt.detail
+      this.safeDispatchEvent('listening')
+    })
   }
 
   async listen (ma: Multiaddr): Promise<void> {
@@ -132,23 +139,6 @@ export class WebRTCDirectListener extends TypedEventEmitter<ListenerEvents> impl
       isIPv6: family === 6,
       server: Promise.resolve()
         .then(async (): Promise<StunServer> => {
-          // ensure we have a certificate
-          if (this.certificate == null) {
-            this.log.trace('creating TLS certificate')
-            const keyPair = await crypto.subtle.generateKey({
-              name: 'ECDSA',
-              namedCurve: 'P-256'
-            }, true, ['sign', 'verify'])
-
-            const certificate = await generateTransportCertificate(keyPair, {
-              days: 365 * 10
-            })
-
-            if (this.certificate == null) {
-              this.certificate = certificate
-            }
-          }
-
           if (port === 0) {
             // libjuice doesn't map 0 to a random free port so we have to do it
             // ourselves