diff --git a/package.json b/package.json index 6277a9c4d..1c1cd43d1 100644 --- a/package.json +++ b/package.json @@ -51,6 +51,7 @@ }, "devDependencies": { "aegir": "^20.4.1", + "it-handshake": "^1.0.0", "it-pair": "^1.0.0", "it-pipe": "^1.0.1", "peer-info": "^0.17.0" diff --git a/src/crypto/README.md b/src/crypto/README.md new file mode 100644 index 000000000..7d15a5e7a --- /dev/null +++ b/src/crypto/README.md @@ -0,0 +1,96 @@ +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](https://github.com/libp2p/js-libp2p-secio) + +## Table of Contents +- [interface-crypto](#interface-crypto) + - [Table of Contents](#table-of-contents) + - [Using the Test Suite](#using-the-test-suite) + - [API](#api) + - [Secure Inbound](#secure-inbound) + - [Secure Outbound](#secure-outbound) + - [Crypto Errors](#crypto-errors) + - [Error Types](#error-types) + +## Using the Test Suite + +You can also check out the [internal test suite](../../test/crypto/compliance.spec.js) to see the setup in action. + +```js +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`: The protocol id of the crypto module. + - `secureInbound`: Secures inbound connections. + - `secureOutbound`: Secures outbound connections. + +### Secure Inbound + +- `const { conn, remotePeer } = await crypto.secureInbound(localPeer, duplex, [remotePeer])` + +Secures an inbound [streaming iterable duplex][iterable-duplex] connection. It returns an encrypted [streaming iterable duplex][iterable-duplex], as well as the [PeerId][peer-id] of the remote peer. + +**Parameters** +- `localPeer` is the [PeerId][peer-id] of the receiving peer. +- `duplex` is the [streaming iterable duplex][iterable-duplex] that will be encryption. +- `remotePeer` is the optional [PeerId][peer-id] of the initiating peer, if known. This may only exist during transport upgrades. + +**Return Value** +- `` + - `conn`: An encrypted [streaming iterable duplex][iterable-duplex]. + - `remotePeer`: The [PeerId][peer-id] of the remote peer. + +### Secure Outbound + +- `const { conn, remotePeer } = await crypto.secureOutbound(localPeer, duplex, remotePeer)` + +Secures an outbound [streaming iterable duplex][iterable-duplex] connection. It returns an encrypted [streaming iterable duplex][iterable-duplex], as well as the [PeerId][peer-id] of the remote peer. + +**Parameters** +- `localPeer` is the [PeerId][peer-id] of the receiving peer. +- `duplex` is the [streaming iterable duplex][iterable-duplex] that will be encrypted. +- `remotePeer` is the [PeerId][peer-id] of the remote peer. If provided, implementations **should** use this to validate the integrity of the remote peer. + +**Return Value** +- `` + - `conn`: An encrypted [streaming iterable duplex][iterable-duplex]. + - `remotePeer`: The [PeerId][peer-id] of the remote peer. This **should** match the `remotePeer` parameter, and implementations should enforce this. + +[peer-id]: https://github.com/libp2p/js-peer-id +[iterable-duplex]: https://gist.github.com/alanshaw/591dc7dd54e4f99338a347ef568d6ee9#duplex-it + +## Crypto Errors + +Common crypto errors come with the interface, and can be imported directly. All Errors take an optional message. + +```js +const { + UnexpectedPeerError +} = require('libp2p-interfaces/src/crypto/errors') + +const error = new UnexpectedPeerError('a custom error message') +console.log(error.code === UnexpectedPeerError.code) // true +``` + +### Error Types + +- `UnexpectedPeerError` - Should be thrown when the expected peer id does not match the peer id determined via the crypto exchange diff --git a/src/crypto/errors.js b/src/crypto/errors.js new file mode 100644 index 000000000..378448220 --- /dev/null +++ b/src/crypto/errors.js @@ -0,0 +1,16 @@ +'use strict' + +class UnexpectedPeerError extends Error { + constructor (message = 'Unexpected Peer') { + super(message) + this.code = UnexpectedPeerError.code + } + + static get code () { + return 'ERR_UNEXPECTED_PEER' + } +} + +module.exports = { + UnexpectedPeerError +} diff --git a/src/crypto/tests/index.js b/src/crypto/tests/index.js new file mode 100644 index 000000000..aa858d9ec --- /dev/null +++ b/src/crypto/tests/index.js @@ -0,0 +1,102 @@ +/* eslint-env mocha */ +'use strict' + +const duplexPair = require('it-pair/duplex') +const pipe = require('it-pipe') +const peers = require('../../utils/peers') +const { UnexpectedPeerError } = require('../errors') +const PeerId = require('peer-id') +const { collect } = require('streaming-iterables') +const chai = require('chai') +const expect = chai.expect +chai.use(require('dirty-chai')) + +module.exports = (common) => { + describe('interface-crypto', () => { + let crypto + let localPeer + let remotePeer + let mitmPeer + + before(async () => { + [ + crypto, + localPeer, + remotePeer, + mitmPeer + ] = await Promise.all([ + common.setup(), + PeerId.createFromJSON(peers[0]), + PeerId.createFromJSON(peers[1]), + PeerId.createFromJSON(peers[2]) + ]) + }) + + after(() => common.teardown && common.teardown()) + + it('has a protocol string', () => { + expect(crypto.protocol).to.exist() + expect(crypto.protocol).to.be.a('string') + }) + + it('it wraps the provided duplex connection', async () => { + const [localConn, remoteConn] = duplexPair() + + const [ + inboundResult, + outboundResult + ] = await Promise.all([ + crypto.secureInbound(remotePeer, localConn), + crypto.secureOutbound(localPeer, remoteConn, remotePeer) + ]) + + // Echo server + pipe(inboundResult.conn, inboundResult.conn) + + // Send some data and collect the result + const input = Buffer.from('data to encrypt') + const result = await pipe( + [input], + outboundResult.conn, + // Convert BufferList to Buffer via slice + (source) => (async function * toBuffer () { + for await (const chunk of source) { + yield chunk.slice() + } + })(), + collect + ) + + expect(result).to.eql([input]) + }) + + it('should return the remote peer id', async () => { + const [localConn, remoteConn] = duplexPair() + + const [ + inboundResult, + outboundResult + ] = await Promise.all([ + crypto.secureInbound(remotePeer, localConn), + crypto.secureOutbound(localPeer, remoteConn, remotePeer) + ]) + + // Inbound should return the initiator (local) peer + expect(inboundResult.remotePeer.id).to.eql(localPeer.id) + // Outbound should return the receiver (remote) peer + expect(outboundResult.remotePeer.id).to.eql(remotePeer.id) + }) + + it('inbound connections should verify peer integrity if known', async () => { + const [localConn, remoteConn] = duplexPair() + + await Promise.all([ + crypto.secureInbound(remotePeer, localConn, mitmPeer), + crypto.secureOutbound(localPeer, remoteConn, remotePeer) + ]).then(expect.fail, (err) => { + expect(err).to.exist() + expect(err).to.have.property('code', UnexpectedPeerError.code) + }) + }) + }) +} diff --git a/test/utils/peers.js b/src/utils/peers.js similarity index 100% rename from test/utils/peers.js rename to src/utils/peers.js diff --git a/test/connection/compliance.spec.js b/test/connection/compliance.spec.js index fd4f994d1..d12a87158 100644 --- a/test/connection/compliance.spec.js +++ b/test/connection/compliance.spec.js @@ -3,7 +3,7 @@ const tests = require('../../src/connection/tests') const { Connection } = require('../../src/connection') -const peers = require('../utils/peers') +const peers = require('../../src/utils/peers') const PeerId = require('peer-id') const multiaddr = require('multiaddr') const pair = require('it-pair') diff --git a/test/crypto/compliance.spec.js b/test/crypto/compliance.spec.js new file mode 100644 index 000000000..e050e9761 --- /dev/null +++ b/test/crypto/compliance.spec.js @@ -0,0 +1,13 @@ +/* eslint-env mocha */ +'use strict' + +const tests = require('../../src/crypto/tests') +const mockCrypto = require('./mock-crypto') + +describe('compliance tests', () => { + tests({ + setup () { + return mockCrypto + } + }) +}) diff --git a/test/crypto/mock-crypto.js b/test/crypto/mock-crypto.js new file mode 100644 index 000000000..6d2ee8247 --- /dev/null +++ b/test/crypto/mock-crypto.js @@ -0,0 +1,75 @@ +'use strict' + +const PeerId = require('peer-id') +const handshake = require('it-handshake') +const duplexPair = require('it-pair/duplex') +const pipe = require('it-pipe') +const { UnexpectedPeerError } = require('../../src/crypto/errors') + +// A basic transform that does nothing to the data +const transform = () => { + return (source) => (async function * () { + for await (const chunk of source) { + yield chunk + } + })() +} + +module.exports = { + protocol: 'insecure', + secureInbound: async (localPeer, duplex, expectedPeer) => { + // 1. Perform a basic handshake. + const shake = handshake(duplex) + shake.write(localPeer.id) + const remoteId = await shake.read() + const remotePeer = new PeerId(remoteId.slice()) + shake.rest() + + if (expectedPeer && expectedPeer.id !== remotePeer.id) { + throw new UnexpectedPeerError() + } + + // 2. Create your encryption box/unbox wrapper + const wrapper = duplexPair() + const encrypt = transform() // Use transform iterables to modify data + const decrypt = transform() + + pipe( + wrapper[0], // We write to wrapper + encrypt, // The data is encrypted + shake.stream, // It goes to the remote peer + decrypt, // Decrypt the incoming data + wrapper[0] // Pipe to the wrapper + ) + + return { + conn: wrapper[1], + remotePeer + } + }, + secureOutbound: async (localPeer, duplex, remotePeer) => { + // 1. Perform a basic handshake. + const shake = handshake(duplex) + shake.write(localPeer.id) + const remoteId = await shake.read() + shake.rest() + + // 2. Create your encryption box/unbox wrapper + const wrapper = duplexPair() + const encrypt = transform() + const decrypt = transform() + + pipe( + wrapper[0], // We write to wrapper + encrypt, // The data is encrypted + shake.stream, // It goes to the remote peer + decrypt, // Decrypt the incoming data + wrapper[0] // Pipe to the wrapper + ) + + return { + conn: wrapper[1], + remotePeer: new PeerId(remoteId.slice()) + } + } +}