@libp2p/noise 12.0.1 → 16.1.4-6059227cb

package/src/noise.ts

@@ -1,192 +1,237 @@
-import { decode } from 'it-length-prefixed'
-import { lpStream, type LengthPrefixedStream } from 'it-length-prefixed-stream'
-import { duplexPair } from 'it-pair/duplex'
-import { pipe } from 'it-pipe'
+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 { pureJsCrypto } from './crypto/js.js'
-import { decryptStream, encryptStream } from './crypto/streaming.js'
+import { defaultCrypto } from './crypto/index.js'
+import { wrapCrypto } from './crypto.js'
 import { uint16BEDecode, uint16BEEncode } from './encoder.js'
-import { XXHandshake } from './handshake-xx.js'
-import { type MetricsRegistry, registerMetrics } from './metrics.js'
-import { getPayload } from './utils.js'
-import type { bytes } from './@types/basic.js'
-import type { IHandshake } from './@types/handshake-interface.js'
-import type { INoiseConnection, KeyPair } from './@types/libp2p.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 { NoiseExtensions } from './proto/payload.js'
-import type { SecuredConnection } from '@libp2p/interface/connection-encrypter'
-import type { Metrics } from '@libp2p/interface/metrics'
-import type { PeerId } from '@libp2p/interface/peer-id'
-import type { Duplex, Source } from 'it-stream-types'
-
-interface HandshakeParams {
-  connection: LengthPrefixedStream
-  isInitiator: boolean
-  localPeer: PeerId
-  remotePeer?: PeerId
+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?: bytes
-  extensions?: NoiseExtensions
+  staticNoiseKey?: Uint8Array
+  extensions?: Partial<NoiseExtensions>
   crypto?: ICryptoInterface
   prologueBytes?: Uint8Array
-  metrics?: Metrics
 }
 
 export class Noise implements INoiseConnection {
   public protocol = '/noise'
-  public crypto: ICryptoInterface
+  public crypto: ICrypto
 
   private readonly prologue: Uint8Array
-  private readonly staticKeys: KeyPair
+  private readonly staticKey: KeyPair
   private readonly extensions?: NoiseExtensions
   private readonly metrics?: MetricsRegistry
-
-  constructor (init: NoiseInit = {}) {
-    const { staticNoiseKey, extensions, crypto, prologueBytes, metrics } = init
-
-    this.crypto = crypto ?? pureJsCrypto
-    this.extensions = extensions
+  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.staticKeys = this.crypto.generateX25519KeyPairFromSeed(staticNoiseKey)
+      this.staticKey = _crypto.generateX25519KeyPairFromSeed(staticNoiseKey)
     } else {
-      this.staticKeys = this.crypto.generateX25519KeyPair()
+      this.staticKey = _crypto.generateX25519KeyPair()
     }
-    this.prologue = prologueBytes ?? new Uint8Array(0)
+    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 {PeerId} localPeer - PeerId of the receiving peer
-   * @param {Duplex<AsyncGenerator<Uint8Array>, AsyncIterable<Uint8Array>, Promise<void>>} connection - streaming iterable duplex that will be encrypted
-   * @param {PeerId} remotePeer - PeerId of the remote peer. Used to validate the integrity of the remote peer.
-   * @returns {Promise<SecuredConnection>}
+   * @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
    */
-  public async secureOutbound (localPeer: PeerId, connection: Duplex<AsyncGenerator<Uint8Array>, AsyncIterable<Uint8Array>, Promise<void>>, remotePeer?: PeerId): Promise<SecuredConnection<NoiseExtensions>> {
-    const wrappedConnection = lpStream(
-      connection,
-      {
-        lengthEncoder: uint16BEEncode,
-        lengthDecoder: uint16BEDecode,
-        maxDataLength: NOISE_MSG_MAX_LENGTH_BYTES
-      }
-    )
-    const handshake = await this.performHandshake({
-      connection: wrappedConnection,
-      isInitiator: true,
-      localPeer,
-      remotePeer
+  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 conn = await this.createSecureConnection(wrappedConnection, handshake)
+
+    const handshake = await this.performHandshakeInitiator(
+      wrappedConnection,
+      this.components.privateKey,
+      log,
+      options?.remotePeer?.publicKey,
+      options
+    )
+    const publicKey = publicKeyFromProtobuf(handshake.payload.identityKey)
 
     return {
-      conn,
-      remoteExtensions: handshake.remoteExtensions,
-      remotePeer: handshake.remotePeer
+      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 {PeerId} localPeer - PeerId of the receiving peer.
-   * @param {Duplex<AsyncGenerator<Uint8Array>, AsyncIterable<Uint8Array>, Promise<void>>} connection - streaming iterable duplex that will be encryption.
-   * @param {PeerId} remotePeer - optional PeerId of the initiating peer, if known. This may only exist during transport upgrades.
-   * @returns {Promise<SecuredConnection>}
+   * @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
    */
-  public async secureInbound (localPeer: PeerId, connection: Duplex<AsyncGenerator<Uint8Array>, AsyncIterable<Uint8Array>, Promise<void>>, remotePeer?: PeerId): Promise<SecuredConnection<NoiseExtensions>> {
-    const wrappedConnection = lpStream(
-      connection,
-      {
-        lengthEncoder: uint16BEEncode,
-        lengthDecoder: uint16BEDecode,
-        maxDataLength: NOISE_MSG_MAX_LENGTH_BYTES
-      }
-    )
-    const handshake = await this.performHandshake({
-      connection: wrappedConnection,
-      isInitiator: false,
-      localPeer,
-      remotePeer
+  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 conn = await this.createSecureConnection(wrappedConnection, handshake)
+
+    const handshake = await this.performHandshakeResponder(
+      wrappedConnection,
+      this.components.privateKey,
+      log,
+      options?.remotePeer?.publicKey,
+      options
+    )
+    const publicKey = publicKeyFromProtobuf(handshake.payload.identityKey)
 
     return {
-      conn,
-      remotePeer: handshake.remotePeer,
-      remoteExtensions: handshake.remoteExtensions
+      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)
     }
   }
 
   /**
-   * If Noise pipes supported, tries IK handshake first with XX as fallback if it fails.
-   * If noise pipes disabled or remote peer static key is unknown, use XX.
-   *
-   * @param {HandshakeParams} params
+   * Perform XX handshake as initiator.
    */
-  private async performHandshake (params: HandshakeParams): Promise<IHandshake> {
-    const payload = await getPayload(params.localPeer, this.staticKeys.publicKey, this.extensions)
-
-    // run XX handshake
-    return this.performXXHandshake(params, payload)
-  }
-
-  private async performXXHandshake (
-    params: HandshakeParams,
-    payload: bytes
-  ): Promise<XXHandshake> {
-    const { isInitiator, remotePeer, connection } = params
-    const handshake = new XXHandshake(
-      isInitiator,
-      payload,
-      this.prologue,
-      this.crypto,
-      this.staticKeys,
-      connection,
-      remotePeer
-    )
+  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 {
-      await handshake.propose()
-      await handshake.exchange()
-      await handshake.finish()
+      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()
-      if (e instanceof Error) {
-        e.message = `Error occurred during XX handshake: ${e.message}`
-        throw e
-      }
+      throw e
     }
 
-    return handshake
+    return result
   }
 
-  private async createSecureConnection (
-    connection: LengthPrefixedStream<Duplex<AsyncGenerator<Uint8Array>, AsyncIterable<Uint8Array>, Promise<void>>>,
-    handshake: IHandshake
-  ): Promise<Duplex<AsyncGenerator<Uint8Array>, Source<Uint8Array>, Promise<void>>> {
-    // Create encryption box/unbox wrapper
-    const [secure, user] = duplexPair<Uint8Array>()
-    const network = connection.unwrap()
-
-    await pipe(
-      secure, // write to wrapper
-      encryptStream(handshake, this.metrics), // encrypt data + prefix with message length
-      network, // send to the remote peer
-      (source) => decode(source, { lengthDecoder: uint16BEDecode }), // read message length prefix
-      decryptStream(handshake, this.metrics), // decrypt the incoming data
-      secure // pipe to the wrapper
-    )
+  /**
+   * 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 user
+    return result
   }
 }

package/src/nonce.ts

@@ -1,4 +1,4 @@
-import type { bytes, uint64 } from './@types/basic.js'
+import { alloc as uint8ArrayAlloc } from 'uint8arrays/alloc'
 
 export const MIN_NONCE = 0
 // For performance reasons, the nonce is represented as a JS `number`
@@ -9,20 +9,20 @@ export const MIN_NONCE = 0
 // 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 = 'Cipherstate has reached maximum n, a new handshake must be performed'
+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: uint64
-  private readonly bytes: bytes
+  private n: number
+  private readonly bytes: Uint8Array
   private readonly view: DataView
 
   constructor (n = MIN_NONCE) {
     this.n = n
-    this.bytes = new Uint8Array(12)
+    this.bytes = uint8ArrayAlloc(12)
     this.view = new DataView(this.bytes.buffer, this.bytes.byteOffset, this.bytes.byteLength)
     this.view.setUint32(4, n, true)
   }
@@ -33,11 +33,11 @@ export class Nonce {
     this.view.setUint32(4, this.n, true)
   }
 
-  getBytes (): bytes {
+  getBytes (): Uint8Array {
     return this.bytes
   }
 
-  getUint64 (): uint64 {
+  getUint64 (): number {
     return this.n
   }
 

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

@@ -2,10 +2,11 @@ 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;
-}
+}