Proposal for the Trusted Private Network feature

docs/trusted-private-network.md

@@ -0,0 +1,84 @@
+# Trusted Private Network
+
+This document describes the Trusted Private Network feature of IPFS.
+
+### Table of Contents
+- [Overview](#overview)
+- [Trust Manager](#trust-manager)
+- [Trust Manager Implementations](#trust-manager-implementations)
+- [DefaultTrustManager](#defaulttrustmanager)
+- [SimpleTrustManager](#simpletrustmanager)
+- [PluginTrustManager](#plugintrustmanager)
+
+### Overview
+
+Trusted Private Network is a feature that enables setting up a private network of IPFS peers on the internet.
+
+By default, an IPFS peer allows any other IPFS peer on the internet to connect and query documents. A peer can also be configured to allow connections only from trusted IPFS peers. If all trusted peers are configured this way, the set of trusted IPFS peers becomes a private IPFS network.
+
+### Trust Manager
+
+Trust Manager is the component that manages trust in IPFS. At the time of establishing connection to another peer, IPFS checks with the Trust Manager if the other peer is trusted.
+
+Trust Manager functionality is specified by the TrustManager interface:
+
+```
+type TrustManager interface {
+
+	// Checks if the peer is trusted.
+	IsTrustedPeer(exchange []byte) (bool, error)
+
+	// Returns the list of trusted peers.
+	GetTrustedPeers() ([]string, error)
+}
+```
+
+```IsTrustedPeer``` accepts data received from the other peer during the first phase of connection handshake. If the other peer is trusted, ```true``` is returned.
+
+```GetTrustedPeers``` returns the list of trusted peers. ```TrustManager``` implementation can return either the full list of trusted peers, or just a subset required for the bootstrap process (initial set of known peers).
+
+### Trust Manager Implementations
+
+IPFS comes with three Trust Managers:
+- DefaultTrustManager - preserves the open nature of IPFS, trusting everyone.
+- SimpleTrustManager - allows defining the list of trusted peers in local configuration file.
+- PluginTrustManager - allows plugging in a custom ```TrustManager``` without changing and recompiling IPFS code.
+
+Trust Manager used by a deployment is specified by the ```TrustManagetType``` entry in IPFS configuration.
+
+### DefaultTrustManager
+
+To use DefaultTrustManager, put the following line in IPFS configuration:
+
+```
+"TrustManagerType": "DefaultTrustManager"
+```
+
+This configuration is generated by IPFS for new installations. As usual, communication handshake will succeed with any peer which presents its public key (identity) and can prove it holds the corresponding private key.
+
+### SimpleTrustManager
+
+To use SimpleTrustManager, put the following lines in IPFS configuration:
+
+```
+"TrustManagerType": "SimpleTrustManager",
+"TrustedPeers": [
+    // put here an array of public keys belonging to trusted peers
+  ]
+```
+Note that the list of trusted peers has to match the list of bootstrap peers, at least partially.
+
+It is important to understand that, if any trusted peer uses default configuration (to accept connections from any IPFS peer on the internet), the network privacy will be broken; the peer that uses default configuration will allow uncontrolled access to any locally cached documents, some of which may originate from other peers on the "private" network.
+
+### PluginTrustManager
+
+```PluginTrustManager``` allows plugging in a custom ```TrustManager```, without changing and recompiling IPFS code. This allows one to develop a ```Trustmanager``` that is more secure and feature rich than ```SimpleTrustManager```. For example, trusted network could be managed by a dedicated server, and the peers would trust only the peers registered with the management server, with issued security token, and so on.
+
+As golang currently doesn't support dynamic linking, golang plugins cannot execute within the main process (IPFS in this case). ```PluginTrustManager``` uses Hashicorp's go-plugin (https://github.com/hashicorp/go-plugin) to start a custom ```TrustManager``` in a subprocess. IPFS communicates with the plugin over RPC.
+
+To use PluginTrustManager, put the following lines in IPFS configuration:
+
+```
+"TrustManagerType": "PluginTrustManager",
+// more details, TBD
+```