@libp2p/noise 1.0.0-049bfa0fa

package/src/noise.ts

@@ -0,0 +1,237 @@
+import { publicKeyFromProtobuf } from '@libp2p/crypto/keys'
+import { InvalidCryptoExchangeError, serviceCapabilities } from '@libp2p/interface'
+import { peerIdFromPublicKey } from '@libp2p/peer-id'
+import { lpStream } from '@libp2p/utils'
+import { alloc as uint8ArrayAlloc } from 'uint8arrays/alloc'
+import { NOISE_MSG_MAX_LENGTH_BYTES } from './constants.js'
+import { defaultCrypto } from './crypto/index.js'
+import { wrapCrypto } from './crypto.js'
+import { uint16BEDecode, uint16BEEncode } from './encoder.js'
+import { registerMetrics } from './metrics.js'
+import { performHandshakeInitiator, performHandshakeResponder } from './performHandshake.js'
+import { toMessageStream } from './utils.ts'
+import type { ICryptoInterface } from './crypto.js'
+import type { NoiseComponents } from './index.js'
+import type { MetricsRegistry } from './metrics.js'
+import type { HandshakeResult, ICrypto, INoiseConnection, INoiseExtensions, KeyPair } from './types.js'
+import type { SecuredConnection, PrivateKey, PublicKey, StreamMuxerFactory, SecureConnectionOptions, Logger, MessageStream } from '@libp2p/interface'
+import type { LengthPrefixedStream } from '@libp2p/utils'
+
+export interface NoiseExtensions {
+  webtransportCerthashes: Uint8Array[]
+}
+
+export interface NoiseInit {
+  /**
+   * x25519 private key, reuse for faster handshakes
+   */
+  staticNoiseKey?: Uint8Array
+  extensions?: Partial<NoiseExtensions>
+  crypto?: ICryptoInterface
+  prologueBytes?: Uint8Array
+}
+
+export class Noise implements INoiseConnection {
+  public protocol = '/noise'
+  public crypto: ICrypto
+
+  private readonly prologue: Uint8Array
+  private readonly staticKey: KeyPair
+  private readonly extensions?: NoiseExtensions
+  private readonly metrics?: MetricsRegistry
+  private readonly components: NoiseComponents
+  private readonly log: Logger
+
+  constructor (components: NoiseComponents, init: NoiseInit = {}) {
+    const { staticNoiseKey, extensions, crypto, prologueBytes } = init
+    const { metrics } = components
+
+    this.components = components
+    this.log = components.logger.forComponent('libp2p:noise')
+    const _crypto = crypto ?? defaultCrypto
+    this.crypto = wrapCrypto(_crypto)
+    this.extensions = {
+      webtransportCerthashes: [],
+      ...extensions
+    }
+    this.metrics = metrics ? registerMetrics(metrics) : undefined
+
+    if (staticNoiseKey) {
+      // accepts x25519 private key of length 32
+      this.staticKey = _crypto.generateX25519KeyPairFromSeed(staticNoiseKey)
+    } else {
+      this.staticKey = _crypto.generateX25519KeyPair()
+    }
+    this.prologue = prologueBytes ?? uint8ArrayAlloc(0)
+  }
+
+  readonly [Symbol.toStringTag] = '@libp2p/noise'
+
+  readonly [serviceCapabilities]: string[] = [
+    '@libp2p/connection-encryption',
+    '@libp2p/noise'
+  ]
+
+  /**
+   * Encrypt outgoing data to the remote party (handshake as initiator)
+   *
+   * @param connection - streaming iterable duplex that will be encrypted
+   * @param options
+   * @param options.remotePeer - PeerId of the remote peer. Used to validate the integrity of the remote peer
+   * @param options.signal - Used to abort the operation
+   */
+  async secureOutbound (connection: MessageStream, options?: SecureConnectionOptions): Promise<SecuredConnection<INoiseExtensions>> {
+    const log = connection.log?.newScope('noise') ?? this.log
+    const wrappedConnection = lpStream(connection, {
+      lengthEncoder: uint16BEEncode,
+      lengthDecoder: uint16BEDecode,
+      maxDataLength: NOISE_MSG_MAX_LENGTH_BYTES
+    })
+
+    const handshake = await this.performHandshakeInitiator(
+      wrappedConnection,
+      this.components.privateKey,
+      log,
+      options?.remotePeer?.publicKey,
+      options
+    )
+    const publicKey = publicKeyFromProtobuf(handshake.payload.identityKey)
+
+    return {
+      connection: toMessageStream(wrappedConnection.unwrap(), handshake, this.metrics),
+      remoteExtensions: handshake.payload.extensions,
+      remotePeer: peerIdFromPublicKey(publicKey),
+      streamMuxer: options?.skipStreamMuxerNegotiation === true ? undefined : this.getStreamMuxer(handshake.payload.extensions?.streamMuxers)
+    }
+  }
+
+  private getStreamMuxer (protocols?: string[]): StreamMuxerFactory | undefined {
+    if (protocols == null || protocols.length === 0) {
+      return
+    }
+
+    const streamMuxers = this.components.upgrader.getStreamMuxers()
+
+    if (streamMuxers != null) {
+      for (const protocol of protocols) {
+        const streamMuxer = streamMuxers.get(protocol)
+
+        if (streamMuxer != null) {
+          return streamMuxer
+        }
+      }
+    }
+
+    if (protocols.length) {
+      throw new InvalidCryptoExchangeError('Early muxer negotiation was requested but the initiator and responder had no common muxers')
+    }
+  }
+
+  /**
+   * Decrypt incoming data (handshake as responder).
+   *
+   * @param connection - streaming iterable duplex that will be encrypted
+   * @param options
+   * @param options.remotePeer - PeerId of the remote peer. Used to validate the integrity of the remote peer
+   * @param options.signal - Used to abort the operation
+   */
+  async secureInbound (connection: MessageStream, options?: SecureConnectionOptions): Promise<SecuredConnection<INoiseExtensions>> {
+    const log = connection.log?.newScope('noise') ?? this.log
+    const wrappedConnection = lpStream(connection, {
+      lengthEncoder: uint16BEEncode,
+      lengthDecoder: uint16BEDecode,
+      maxDataLength: NOISE_MSG_MAX_LENGTH_BYTES
+    })
+
+    const handshake = await this.performHandshakeResponder(
+      wrappedConnection,
+      this.components.privateKey,
+      log,
+      options?.remotePeer?.publicKey,
+      options
+    )
+    const publicKey = publicKeyFromProtobuf(handshake.payload.identityKey)
+
+    return {
+      connection: toMessageStream(wrappedConnection.unwrap(), handshake, this.metrics),
+      remoteExtensions: handshake.payload.extensions,
+      remotePeer: peerIdFromPublicKey(publicKey),
+      streamMuxer: options?.skipStreamMuxerNegotiation === true ? undefined : this.getStreamMuxer(handshake.payload.extensions?.streamMuxers)
+    }
+  }
+
+  /**
+   * Perform XX handshake as initiator.
+   */
+  private async performHandshakeInitiator (
+    connection: LengthPrefixedStream,
+    // TODO: pass private key in noise constructor via Components
+    privateKey: PrivateKey,
+    log: Logger,
+    remoteIdentityKey?: PublicKey,
+    options?: SecureConnectionOptions
+  ): Promise<HandshakeResult> {
+    let result: HandshakeResult
+    const streamMuxers = options?.skipStreamMuxerNegotiation === true ? [] : [...this.components.upgrader.getStreamMuxers().keys()]
+
+    try {
+      result = await performHandshakeInitiator({
+        connection,
+        privateKey,
+        remoteIdentityKey,
+        log: log.newScope('xxhandshake'),
+        crypto: this.crypto,
+        prologue: this.prologue,
+        s: this.staticKey,
+        extensions: {
+          streamMuxers,
+          webtransportCerthashes: [],
+          ...this.extensions
+        }
+      }, options)
+      this.metrics?.xxHandshakeSuccesses.increment()
+    } catch (e: unknown) {
+      this.metrics?.xxHandshakeErrors.increment()
+      throw e
+    }
+
+    return result
+  }
+
+  /**
+   * Perform XX handshake as responder.
+   */
+  private async performHandshakeResponder (
+    connection: LengthPrefixedStream,
+    privateKey: PrivateKey,
+    log: Logger,
+    remoteIdentityKey?: PublicKey,
+    options?: SecureConnectionOptions
+  ): Promise<HandshakeResult> {
+    let result: HandshakeResult
+    const streamMuxers = options?.skipStreamMuxerNegotiation === true ? [] : [...this.components.upgrader.getStreamMuxers().keys()]
+
+    try {
+      result = await performHandshakeResponder({
+        connection,
+        privateKey,
+        remoteIdentityKey,
+        log: log.newScope('xxhandshake'),
+        crypto: this.crypto,
+        prologue: this.prologue,
+        s: this.staticKey,
+        extensions: {
+          streamMuxers,
+          webtransportCerthashes: [],
+          ...this.extensions
+        }
+      }, options)
+      this.metrics?.xxHandshakeSuccesses.increment()
+    } catch (e: unknown) {
+      this.metrics?.xxHandshakeErrors.increment()
+      throw e
+    }
+
+    return result
+  }
+}

package/src/nonce.ts

@@ -0,0 +1,49 @@
+import { alloc as uint8ArrayAlloc } from 'uint8arrays/alloc'
+
+export const MIN_NONCE = 0
+// For performance reasons, the nonce is represented as a JS `number`
+// Although JS `number` can safely represent integers up to 2 ** 53 - 1, we choose to only use
+// 4 bytes to store the data for performance reason.
+// This is a slight deviation from the noise spec, which describes the max nonce as 2 ** 64 - 2
+// The effect is that this implementation will need a new handshake to be performed after fewer messages are exchanged than other implementations with full uint64 nonces.
+// this MAX_NONCE is still a large number of messages, so the practical effect of this is negligible.
+export const MAX_NONCE = 0xffffffff
+
+const ERR_MAX_NONCE = 'Cipher state has reached maximum n, a new handshake must be performed'
+
+/**
+ * The nonce is an uint that's increased over time.
+ * Maintaining different representations help improve performance.
+ */
+export class Nonce {
+  private n: number
+  private readonly bytes: Uint8Array
+  private readonly view: DataView
+
+  constructor (n = MIN_NONCE) {
+    this.n = n
+    this.bytes = uint8ArrayAlloc(12)
+    this.view = new DataView(this.bytes.buffer, this.bytes.byteOffset, this.bytes.byteLength)
+    this.view.setUint32(4, n, true)
+  }
+
+  increment (): void {
+    this.n++
+    // Even though we're treating the nonce as 8 bytes, RFC7539 specifies 12 bytes for a nonce.
+    this.view.setUint32(4, this.n, true)
+  }
+
+  getBytes (): Uint8Array {
+    return this.bytes
+  }
+
+  getUint64 (): number {
+    return this.n
+  }
+
+  assertValue (): void {
+    if (this.n > MAX_NONCE) {
+      throw new Error(ERR_MAX_NONCE)
+    }
+  }
+}

package/src/performHandshake.ts

@@ -0,0 +1,91 @@
+import {
+  logLocalStaticKeys,
+  logLocalEphemeralKeys,
+  logRemoteEphemeralKey,
+  logRemoteStaticKey,
+  logCipherState
+} from './logger.js'
+import { ZEROLEN, XXHandshakeState } from './protocol.js'
+import { createHandshakePayload, decodeHandshakePayload } from './utils.js'
+import type { HandshakeResult, HandshakeParams } from './types.js'
+import type { AbortOptions } from '@libp2p/interface'
+
+export async function performHandshakeInitiator (init: HandshakeParams, options?: AbortOptions): Promise<HandshakeResult> {
+  const { log, connection, crypto, privateKey, prologue, s, remoteIdentityKey, extensions } = init
+
+  const payload = await createHandshakePayload(privateKey, s.publicKey, extensions)
+  const xx = new XXHandshakeState({
+    crypto,
+    protocolName: 'Noise_XX_25519_ChaChaPoly_SHA256',
+    initiator: true,
+    prologue,
+    s
+  })
+
+  logLocalStaticKeys(xx.s, log)
+  log.trace('Stage 0 - Initiator starting to send first message.')
+  await connection.write(xx.writeMessageA(ZEROLEN), options)
+  log.trace('Stage 0 - Initiator finished sending first message.')
+  logLocalEphemeralKeys(xx.e, log)
+
+  log.trace('Stage 1 - Initiator waiting to receive first message from responder...')
+  const plaintext = xx.readMessageB(await connection.read(options))
+  log.trace('Stage 1 - Initiator received the message.')
+  logRemoteEphemeralKey(xx.re, log)
+  logRemoteStaticKey(xx.rs, log)
+
+  log.trace("Initiator going to check remote's signature...")
+  const receivedPayload = await decodeHandshakePayload(plaintext, xx.rs, remoteIdentityKey)
+  log.trace('All good with the signature!')
+
+  log.trace('Stage 2 - Initiator sending third handshake message.')
+  await connection.write(xx.writeMessageC(payload), options)
+  log.trace('Stage 2 - Initiator sent message with signed payload.')
+
+  const [cs1, cs2] = xx.ss.split()
+  logCipherState(cs1, cs2, log)
+
+  return {
+    payload: receivedPayload,
+    encrypt: (plaintext) => cs1.encryptWithAd(ZEROLEN, plaintext),
+    decrypt: (ciphertext, dst) => cs2.decryptWithAd(ZEROLEN, ciphertext, dst)
+  }
+}
+
+export async function performHandshakeResponder (init: HandshakeParams, options?: AbortOptions): Promise<HandshakeResult> {
+  const { log, connection, crypto, privateKey, prologue, s, remoteIdentityKey, extensions } = init
+
+  const payload = await createHandshakePayload(privateKey, s.publicKey, extensions)
+  const xx = new XXHandshakeState({
+    crypto,
+    protocolName: 'Noise_XX_25519_ChaChaPoly_SHA256',
+    initiator: false,
+    prologue,
+    s
+  })
+
+  logLocalStaticKeys(xx.s, log)
+  log.trace('Stage 0 - Responder waiting to receive first message.')
+  xx.readMessageA(await connection.read(options))
+  log.trace('Stage 0 - Responder received first message.')
+  logRemoteEphemeralKey(xx.re, log)
+
+  log.trace('Stage 1 - Responder sending out first message with signed payload and static key.')
+  await connection.write(xx.writeMessageB(payload), options)
+  log.trace('Stage 1 - Responder sent the second handshake message with signed payload.')
+  logLocalEphemeralKeys(xx.e, log)
+
+  log.trace('Stage 2 - Responder waiting for third handshake message...')
+  const plaintext = xx.readMessageC(await connection.read(options))
+  log.trace('Stage 2 - Responder received the message, finished handshake.')
+  const receivedPayload = await decodeHandshakePayload(plaintext, xx.rs, remoteIdentityKey)
+
+  const [cs1, cs2] = xx.ss.split()
+  logCipherState(cs1, cs2, log)
+
+  return {
+    payload: receivedPayload,
+    encrypt: (plaintext) => cs2.encryptWithAd(ZEROLEN, plaintext),
+    decrypt: (ciphertext, dst) => cs1.decryptWithAd(ZEROLEN, ciphertext, dst)
+  }
+}

package/src/proto/payload.proto

@@ -0,0 +1,12 @@
+syntax = "proto3";
+
+message NoiseExtensions {
+    repeated bytes webtransport_certhashes = 1;
+    repeated string stream_muxers = 2;
+}
+
+message NoiseHandshakePayload {
+  bytes identity_key = 1;
+  bytes identity_sig = 2;
+  optional NoiseExtensions extensions = 4;
+}

package/src/proto/payload.ts

@@ -0,0 +1,170 @@
+import { decodeMessage, encodeMessage, MaxLengthError, message } from 'protons-runtime'
+import { alloc as uint8ArrayAlloc } from 'uint8arrays/alloc'
+import type { Codec, DecodeOptions } from 'protons-runtime'
+import type { Uint8ArrayList } from 'uint8arraylist'
+
+export interface NoiseExtensions {
+  webtransportCerthashes: Uint8Array[]
+  streamMuxers: string[]
+}
+
+export namespace NoiseExtensions {
+  let _codec: Codec<NoiseExtensions>
+
+  export const codec = (): Codec<NoiseExtensions> => {
+    if (_codec == null) {
+      _codec = message<NoiseExtensions>((obj, w, opts = {}) => {
+        if (opts.lengthDelimited !== false) {
+          w.fork()
+        }
+
+        if (obj.webtransportCerthashes != null) {
+          for (const value of obj.webtransportCerthashes) {
+            w.uint32(10)
+            w.bytes(value)
+          }
+        }
+
+        if (obj.streamMuxers != null) {
+          for (const value of obj.streamMuxers) {
+            w.uint32(18)
+            w.string(value)
+          }
+        }
+
+        if (opts.lengthDelimited !== false) {
+          w.ldelim()
+        }
+      }, (reader, length, opts = {}) => {
+        const obj: any = {
+          webtransportCerthashes: [],
+          streamMuxers: []
+        }
+
+        const end = length == null ? reader.len : reader.pos + length
+
+        while (reader.pos < end) {
+          const tag = reader.uint32()
+
+          switch (tag >>> 3) {
+            case 1: {
+              if (opts.limits?.webtransportCerthashes != null && obj.webtransportCerthashes.length === opts.limits.webtransportCerthashes) {
+                throw new MaxLengthError('Decode error - map field "webtransportCerthashes" had too many elements')
+              }
+
+              obj.webtransportCerthashes.push(reader.bytes())
+              break
+            }
+            case 2: {
+              if (opts.limits?.streamMuxers != null && obj.streamMuxers.length === opts.limits.streamMuxers) {
+                throw new MaxLengthError('Decode error - map field "streamMuxers" had too many elements')
+              }
+
+              obj.streamMuxers.push(reader.string())
+              break
+            }
+            default: {
+              reader.skipType(tag & 7)
+              break
+            }
+          }
+        }
+
+        return obj
+      })
+    }
+
+    return _codec
+  }
+
+  export const encode = (obj: Partial<NoiseExtensions>): Uint8Array => {
+    return encodeMessage(obj, NoiseExtensions.codec())
+  }
+
+  export const decode = (buf: Uint8Array | Uint8ArrayList, opts?: DecodeOptions<NoiseExtensions>): NoiseExtensions => {
+    return decodeMessage(buf, NoiseExtensions.codec(), opts)
+  }
+}
+
+export interface NoiseHandshakePayload {
+  identityKey: Uint8Array
+  identitySig: Uint8Array
+  extensions?: NoiseExtensions
+}
+
+export namespace NoiseHandshakePayload {
+  let _codec: Codec<NoiseHandshakePayload>
+
+  export const codec = (): Codec<NoiseHandshakePayload> => {
+    if (_codec == null) {
+      _codec = message<NoiseHandshakePayload>((obj, w, opts = {}) => {
+        if (opts.lengthDelimited !== false) {
+          w.fork()
+        }
+
+        if ((obj.identityKey != null && obj.identityKey.byteLength > 0)) {
+          w.uint32(10)
+          w.bytes(obj.identityKey)
+        }
+
+        if ((obj.identitySig != null && obj.identitySig.byteLength > 0)) {
+          w.uint32(18)
+          w.bytes(obj.identitySig)
+        }
+
+        if (obj.extensions != null) {
+          w.uint32(34)
+          NoiseExtensions.codec().encode(obj.extensions, w)
+        }
+
+        if (opts.lengthDelimited !== false) {
+          w.ldelim()
+        }
+      }, (reader, length, opts = {}) => {
+        const obj: any = {
+          identityKey: uint8ArrayAlloc(0),
+          identitySig: uint8ArrayAlloc(0)
+        }
+
+        const end = length == null ? reader.len : reader.pos + length
+
+        while (reader.pos < end) {
+          const tag = reader.uint32()
+
+          switch (tag >>> 3) {
+            case 1: {
+              obj.identityKey = reader.bytes()
+              break
+            }
+            case 2: {
+              obj.identitySig = reader.bytes()
+              break
+            }
+            case 4: {
+              obj.extensions = NoiseExtensions.codec().decode(reader, reader.uint32(), {
+                limits: opts.limits?.extensions
+              })
+              break
+            }
+            default: {
+              reader.skipType(tag & 7)
+              break
+            }
+          }
+        }
+
+        return obj
+      })
+    }
+
+    return _codec
+  }
+
+  export const encode = (obj: Partial<NoiseHandshakePayload>): Uint8Array => {
+    return encodeMessage(obj, NoiseHandshakePayload.codec())
+  }
+
+  export const decode = (buf: Uint8Array | Uint8ArrayList, opts?: DecodeOptions<NoiseHandshakePayload>): NoiseHandshakePayload => {
+    return decodeMessage(buf, NoiseHandshakePayload.codec(), opts)
+  }
+}