js-libp2p-interfaces/src/crypto

interface-crypto

A test suite you can use to implement a libp2p crypto module. A libp2p crypto module is used to ensure all exchanged data between two peers is encrypted.

Modules that implement the interface

• js-libp2p-secio

Table of Contents

• interface-crypto
  • Table of Contents
  • Using the Test Suite
  • API
    • Secure Inbound
    • Secure Outbound
  • Crypto Errors
    • Error Types

Using the Test Suite

You can also check out the internal test suite to see the setup in action.

const tests = require('libp2p-interfaces/src/crypto/tests')
const yourCrypto = require('./your-crypto')

tests({
  setup () {
    // Set up your crypto if needed, then return it
    return yourCrypto
  },
  teardown () {
    // Clean up your crypto if needed
  }
})

API

• Crypto
  • protocol<string>: The protocol id of the crypto module.
  • secureInbound<function(PeerId, duplex)>: Secures inbound connections.
  • secureOutbound<function(PeerId, duplex, PeerId)>: Secures outbound connections.

Secure Inbound

• const { conn, remotePeer } = await crypto.secureInbound(localPeer, duplex, [remotePeer])

Secures an inbound streaming iterable duplex connection. It returns an encrypted streaming iterable duplex, as well as the PeerId of the remote peer.

Parameters

• localPeer is the PeerId of the receiving peer.
• duplex is the streaming iterable duplex that will be encryption.
• remotePeer is the optional PeerId of the initiating peer, if known. This may only exist during transport upgrades.

Return Value

• <object>
  • conn<duplex>: An encrypted streaming iterable duplex.
  • remotePeer<PeerId>: The PeerId of the remote peer.

Secure Outbound

• const { conn, remotePeer } = await crypto.secureOutbound(localPeer, duplex, remotePeer)

Secures an outbound streaming iterable duplex connection. It returns an encrypted streaming iterable duplex, as well as the PeerId of the remote peer.

Parameters

• localPeer is the PeerId of the receiving peer.
• duplex is the streaming iterable duplex that will be encrypted.
• remotePeer is the PeerId of the remote peer. If provided, implementations should use this to validate the integrity of the remote peer.

Return Value

• <object>
  • conn<duplex>: An encrypted streaming iterable duplex.
  • remotePeer<PeerId>: The PeerId of the remote peer. This should match the remotePeer parameter, and implementations should enforce this.

Crypto Errors

Common crypto errors come with the interface, and can be imported directly. All Errors take an optional message.

const {
  InvalidCryptoExchangeError,
  InvalidCryptoTransmissionError,
  UnexpectedPeerError
} = require('libp2p-interfaces/src/crypto/errors')

const error = new UnexpectedPeerError('a custom error message')
console.log(error.code === UnexpectedPeerError.code) // true

Error Types

• InvalidCryptoExchangeError - Should be thrown when a peer provides data that is insufficient to finish the crypto exchange.
• InvalidCryptoTransmissionError - Should be thrown when an error occurs during encryption/decryption.
• UnexpectedPeerError - Should be thrown when the expected peer id does not match the peer id determined via the crypto exchange.