chore: integrate libp2p-keychain into js-libp2p (#633)

Integrates the libp2p-keychain codebase into this repo Co-authored-by: David Dias <[email protected]> Co-authored-by: Richard Schneider <[email protected]> Co-authored-by: Maciej Krüger <[email protected]> Co-authored-by: Victor Bjelkholm <[email protected]> Co-authored-by: Masahiro Saito <[email protected]> Co-authored-by: Alan Shaw <[email protected]> Co-authored-by: Hugo Dias <[email protected]> Co-authored-by: Alberto Elias <[email protected]> Co-authored-by: Alex Potsides <[email protected]> Co-authored-by: Jacob Heun <[email protected]>
libp2p · May 12, 2020 · fc67af6 · fc67af6
1 parent 9eaed58
commit fc67af6
Show file tree

Hide file tree

Showing 14 changed files with 1,704 additions and 1 deletion.
diff --git a/doc/API.md b/doc/API.md
@@ -44,6 +44,17 @@
   * [`connectionManager.get`](#connectionmanagerget)
   * [`connectionManager.setPeerValue`](#connectionmanagersetpeervalue)
   * [`connectionManager.size`](#connectionmanagersize)
+  * [`keychain.createKey`](#keychaincreatekey)
+  * [`keychain.renameKey`](#keychainrenamekey)
+  * [`keychain.removeKey`](#keychainremovekey)
+  * [`keychain.exportKey`](#keychainexportkey)
+  * [`keychain.importKey`](#keychainimportkey)
+  * [`keychain.importPeer`](#keychainimportpeer)
+  * [`keychain.listKeys`](#keychainlistkeys)
+  * [`keychain.findKeyById`](#keychainfindkeybyid)
+  * [`keychain.findKeyByName`](#keychainfindkeybyname)
+  * [`keychain.cms.encrypt`](#keychaincmsencrypt)
+  * [`keychain.cms.decrypt`](#keychaincmsdecrypt)
   * [`metrics.global`](#metricsglobal)
   * [`metrics.peers`](#metricspeers)
   * [`metrics.protocols`](#metricsprotocols)
@@ -75,6 +86,7 @@ Creates an instance of Libp2p.
 | [options.connectionManager] | `object` | libp2p Connection Manager configuration |
 | [options.datastore] | `object` | must implement [ipfs/interface-datastore](https://github.com/ipfs/interface-datastore) (in memory datastore will be used if not provided) |
 | [options.dialer] | `object` | libp2p Dialer configuration
+| [options.keychain] | [`object`](./CONFIGURATION.md#setup-with-keychain) | keychain configuration |
 | [options.metrics] | `object` | libp2p Metrics configuration
 | [options.peerId] | [`PeerId`][peer-id] | peerId instance (it will be created if not provided) |
 | [options.peerStore] | `object` | libp2p PeerStore configuration |
@@ -1254,6 +1266,283 @@ libp2p.connectionManager.size
 // 10
 ```
 
+### keychain.createKey
+
+Create a key in the keychain.
+
+`libp2p.keychain.createKey(name, type, size)`
+
+#### Parameters
+
+| Name | Type | Description |
+|------|------|-------------|
+| name | `string` | The local key name. It cannot already exist. |
+| type | `string` | One of the key types; 'rsa' |
+| size | `number` | The key size in bits. |
+
+#### Returns
+
+| Type | Description |
+|------|-------------|
+| `Promise<{ id, name }>` | Key info object |
+
+#### Example
+
+```js
+const keyInfo = await libp2p.keychain.createKey('keyTest', 'rsa', 4096)
+```
+
+### keychain.renameKey
+
+Rename a key in the keychain.
+
+`libp2p.keychain.renameKey(oldName, newName)`
+
+#### Parameters
+
+| Name | Type | Description |
+|------|------|-------------|
+| name | `string` | The old local key name. It must already exist. |
+| type | `string` | The new local key name. It must not already exist. |
+
+#### Returns
+
+| Type | Description |
+|------|-------------|
+| `Promise<{ id, name }>` | Key info object |
+
+#### Example
+
+```js
+await libp2p.keychain.createKey('keyTest', 'rsa', 4096)
+const keyInfo = await libp2p.keychain.renameKey('keyTest', 'keyNewNtest')
+```
+
+### keychain.removeKey
+
+Removes a key from the keychain.
+
+`libp2p.keychain.removeKey(name)`
+
+#### Parameters
+
+| Name | Type | Description |
+|------|------|-------------|
+| name | `string` | The local key name. It must already exist. |
+
+#### Returns
+
+| Type | Description |
+|------|-------------|
+| `Promise<{ id, name }>` | Key info object |
+
+#### Example
+
+```js
+await libp2p.keychain.createKey('keyTest', 'rsa', 4096)
+const keyInfo = await libp2p.keychain.removeKey('keyTest')
+```
+
+### keychain.exportKey
+
+Export an existing key as a PEM encrypted PKCS #8 string.
+
+`libp2p.keychain.exportKey(name, password)`
+
+#### Parameters
+
+| Name | Type | Description |
+|------|------|-------------|
+| name | `string` | The local key name. It must already exist. |
+| password | `string` | The password to use. |
+
+#### Returns
+
+| Type | Description |
+|------|-------------|
+| `Promise<string>` | Key as a PEM encrypted PKCS #8 |
+
+#### Example
+
+```js
+await libp2p.keychain.createKey('keyTest', 'rsa', 4096)
+const pemKey = await libp2p.keychain.exportKey('keyTest', 'password123')
+```
+
+### keychain.importKey
+
+Import a new key from a PEM encoded PKCS #8 string.
+
+`libp2p.keychain.importKey(name, pem, password)`
+
+#### Parameters
+
+| Name | Type | Description |
+|------|------|-------------|
+| name | `string` | The local key name. It must not exist. |
+| pem | `string` | The PEM encoded PKCS #8 string. |
+| password | `string` | The password to use. |
+
+#### Returns
+
+| Type | Description |
+|------|-------------|
+| `Promise<{ id, name }>` | Key info object |
+
+#### Example
+
+```js
+await libp2p.keychain.createKey('keyTest', 'rsa', 4096)
+const pemKey = await libp2p.keychain.exportKey('keyTest', 'password123')
+const keyInfo = await libp2p.keychain.importKey('keyTestImport', pemKey, 'password123')
+```
+
+### keychain.importPeer
+
+Import a new key from a PeerId.
+
+`libp2p.keychain.importPeer(name, peerId)`
+
+#### Parameters
+
+| Name | Type | Description |
+|------|------|-------------|
+| name | `string` | The local key name. It must not exist. |
+| peerId | ['PeerId'][peer-id] | The PEM encoded PKCS #8 string. |
+
+#### Returns
+
+| Type | Description |
+|------|-------------|
+| `Promise<{ id, name }>` | Key info object |
+
+#### Example
+
+```js
+const keyInfo = await libp2p.keychain.importPeer('keyTestImport', peerId)
+```
+
+### keychain.listKeys
+
+List all the keys.
+
+`libp2p.keychain.listKeys()`
+
+#### Returns
+
+| Type | Description |
+|------|-------------|
+| `Promise<Array<{ id, name }>>` | Array of Key info |
+
+#### Example
+
+```js
+const keyInfos = await libp2p.keychain.listKeys()
+```
+
+### keychain.findKeyById
+
+Find a key by it's id.
+
+`libp2p.keychain.findKeyById(id)`
+
+#### Parameters
+
+| Name | Type | Description |
+|------|------|-------------|
+| id | `string` | The universally unique key identifier. |
+
+#### Returns
+
+| Type | Description |
+|------|-------------|
+| `Promise<{ id, name }>` | Key info object |
+
+#### Example
+
+```js
+const keyInfo = await libp2p.keychain.createKey('keyTest', 'rsa', 4096)
+const keyInfo2 = await libp2p.keychain.findKeyById(keyInfo.id)
+```
+
+### keychain.findKeyByName
+
+Find a key by it's name.
+
+`libp2p.keychain.findKeyByName(id)`
+
+#### Parameters
+
+| Name | Type | Description |
+|------|------|-------------|
+| id | `string` | The local key name. |
+
+#### Returns
+
+| Type | Description |
+|------|-------------|
+| `Promise<{ id, name }>` | Key info object |
+
+#### Example
+
+```js
+const keyInfo = await libp2p.keychain.createKey('keyTest', 'rsa', 4096)
+const keyInfo2 = await libp2p.keychain.findKeyByName('keyTest')
+```
+
+### keychain.cms.encrypt
+
+Encrypt protected data using the Cryptographic Message Syntax (CMS).
+
+`libp2p.keychain.cms.encrypt(name, data)`
+
+#### Parameters
+
+| Name | Type | Description |
+|------|------|-------------|
+| name | `string` | The local key name. |
+| data | `Buffer` | The data to encrypt. |
+
+#### Returns
+
+| Type | Description |
+|------|-------------|
+| `Promise<Buffer>` | Encrypted data as a PKCS #7 message in DER. |
+
+#### Example
+
+```js
+const keyInfo = await libp2p.keychain.createKey('keyTest', 'rsa', 4096)
+const enc = await libp2p.keychain.cms.encrypt('keyTest', Buffer.from('data'))
+```
+
+### keychain.cms.decrypt
+
+Decrypt protected data using the Cryptographic Message Syntax (CMS).
+The keychain must contain one of the keys used to encrypt the data.  If none of the keys exists, an Error is returned with the property 'missingKeys'.
+
+`libp2p.keychain.cms.decrypt(cmsData)`
+
+#### Parameters
+
+| Name | Type | Description |
+|------|------|-------------|
+| cmsData | `string` | The CMS encrypted data to decrypt. |
+
+#### Returns
+
+| Type | Description |
+|------|-------------|
+| `Promise<Buffer>` | Decrypted data. |
+
+#### Example
+
+```js
+const keyInfo = await libp2p.keychain.createKey('keyTest', 'rsa', 4096)
+const enc = await libp2p.keychain.cms.encrypt('keyTest', Buffer.from('data'))
+const decData = await libp2p.keychain.cms.decrypt(enc)
+```
+
 ### metrics.global
 
 A [`Stats`](#stats) object of tracking the global bandwidth of the libp2p node.

diff --git a/doc/CONFIGURATION.md b/doc/CONFIGURATION.md
@@ -20,6 +20,7 @@
       - [Customizing DHT](#customizing-dht)
       - [Setup with Content and Peer Routing](#setup-with-content-and-peer-routing)
       - [Setup with Relay](#setup-with-relay)
+      - [Setup with Keychain](#setup-with-keychain)
       - [Configuring Dialing](#configuring-dialing)
       - [Configuring Connection Manager](#configuring-connection-manager)
       - [Configuring Metrics](#configuring-metrics)
@@ -422,6 +423,35 @@ const node = await Libp2p.create({
 })
 ```
 
+#### Setup with Keychain
+
+Libp2p allows you to setup a secure key chain to manage your keys. The keychain configuration object should have the following properties:
+
+| Name | Type | Description |
+|------|------|-------------|
+| pass | `string` | Passphrase to use in the keychain (minimum of 20 characters). |
+| datastore | `object` | must implement [ipfs/interface-datastore](https://github.com/ipfs/interface-datastore) |
+
+```js
+const Libp2p = require('libp2p')
+const TCP = require('libp2p-tcp')
+const MPLEX = require('libp2p-mplex')
+const SECIO = require('libp2p-secio')
+const LevelStore = require('datastore-level')
+
+const node = await Libp2p.create({
+  modules: {
+    transport: [TCP],
+    streamMuxer: [MPLEX],
+    connEncryption: [SECIO]
+  },
+  keychain: {
+    pass: 'notsafepassword123456789',
+    datastore: new LevelStore('path/to/store')
+  }
+})
+```
+
 #### Configuring Dialing
 
 Dialing in libp2p can be configured to limit the rate of dialing, and how long dials are allowed to take. The below configuration example shows the default values for the dialer.