|
44 | 44 | * [`connectionManager.get`](#connectionmanagerget)
|
45 | 45 | * [`connectionManager.setPeerValue`](#connectionmanagersetpeervalue)
|
46 | 46 | * [`connectionManager.size`](#connectionmanagersize)
|
| 47 | + * [`keychain.createKey`](#keychaincreatekey) |
| 48 | + * [`keychain.renameKey`](#keychainrenamekey) |
| 49 | + * [`keychain.removeKey`](#keychainremovekey) |
| 50 | + * [`keychain.exportKey`](#keychainexportkey) |
| 51 | + * [`keychain.importKey`](#keychainimportkey) |
| 52 | + * [`keychain.importPeer`](#keychainimportpeer) |
| 53 | + * [`keychain.listKeys`](#keychainlistkeys) |
| 54 | + * [`keychain.findKeyById`](#keychainfindkeybyid) |
| 55 | + * [`keychain.findKeyByName`](#keychainfindkeybyname) |
| 56 | + * [`keychain.cms.encrypt`](#keychaincmsencrypt) |
| 57 | + * [`keychain.cms.decrypt`](#keychaincmsdecrypt) |
47 | 58 | * [`metrics.global`](#metricsglobal)
|
48 | 59 | * [`metrics.peers`](#metricspeers)
|
49 | 60 | * [`metrics.protocols`](#metricsprotocols)
|
@@ -75,6 +86,7 @@ Creates an instance of Libp2p.
|
75 | 86 | | [options.connectionManager] | `object` | libp2p Connection Manager configuration |
|
76 | 87 | | [options.datastore] | `object` | must implement [ipfs/interface-datastore](https://github.com/ipfs/interface-datastore) (in memory datastore will be used if not provided) |
|
77 | 88 | | [options.dialer] | `object` | libp2p Dialer configuration
|
| 89 | +| [options.keychain] | [`object`](./CONFIGURATION.md#setup-with-keychain) | keychain configuration | |
78 | 90 | | [options.metrics] | `object` | libp2p Metrics configuration
|
79 | 91 | | [options.peerId] | [`PeerId`][peer-id] | peerId instance (it will be created if not provided) |
|
80 | 92 | | [options.peerStore] | `object` | libp2p PeerStore configuration |
|
@@ -125,6 +137,36 @@ Required keys in the `options` object:
|
125 | 137 |
|
126 | 138 | ## Libp2p Instance Methods
|
127 | 139 |
|
| 140 | +### loadKeychain |
| 141 | + |
| 142 | +Load keychain keys from the datastore, importing the private key as 'self', if needed. |
| 143 | + |
| 144 | +`libp2p.loadKeychain()` |
| 145 | + |
| 146 | +#### Returns |
| 147 | + |
| 148 | +| Type | Description | |
| 149 | +|------|-------------| |
| 150 | +| `Promise` | Promise resolves when the keychain is ready | |
| 151 | + |
| 152 | +#### Example |
| 153 | + |
| 154 | +```js |
| 155 | +const Libp2p = require('libp2p') |
| 156 | + |
| 157 | +// ... |
| 158 | + |
| 159 | +const libp2p = await Libp2p.create({ |
| 160 | + // ... |
| 161 | + keychain: { |
| 162 | + pass: '0123456789pass1234567890' |
| 163 | + } |
| 164 | +}) |
| 165 | + |
| 166 | +// load keychain |
| 167 | +await libp2p.loadKeychain() |
| 168 | +``` |
| 169 | + |
128 | 170 | ### start
|
129 | 171 |
|
130 | 172 | Starts the libp2p node.
|
@@ -1254,6 +1296,283 @@ libp2p.connectionManager.size
|
1254 | 1296 | // 10
|
1255 | 1297 | ```
|
1256 | 1298 |
|
| 1299 | +### keychain.createKey |
| 1300 | + |
| 1301 | +Create a key in the keychain. |
| 1302 | + |
| 1303 | +`libp2p.keychain.createKey(name, type, size)` |
| 1304 | + |
| 1305 | +#### Parameters |
| 1306 | + |
| 1307 | +| Name | Type | Description | |
| 1308 | +|------|------|-------------| |
| 1309 | +| name | `string` | The local key name. It cannot already exist. | |
| 1310 | +| type | `string` | One of the key types; 'rsa' | |
| 1311 | +| size | `number` | The key size in bits. | |
| 1312 | + |
| 1313 | +#### Returns |
| 1314 | + |
| 1315 | +| Type | Description | |
| 1316 | +|------|-------------| |
| 1317 | +| `Promise<{ id, name }>` | Key info object | |
| 1318 | + |
| 1319 | +#### Example |
| 1320 | + |
| 1321 | +```js |
| 1322 | +const keyInfo = await libp2p.keychain.createKey('keyTest', 'rsa', 4096) |
| 1323 | +``` |
| 1324 | + |
| 1325 | +### keychain.renameKey |
| 1326 | + |
| 1327 | +Rename a key in the keychain. |
| 1328 | + |
| 1329 | +`libp2p.keychain.renameKey(oldName, newName)` |
| 1330 | + |
| 1331 | +#### Parameters |
| 1332 | + |
| 1333 | +| Name | Type | Description | |
| 1334 | +|------|------|-------------| |
| 1335 | +| name | `string` | The old local key name. It must already exist. | |
| 1336 | +| type | `string` | The new local key name. It must not already exist. | |
| 1337 | + |
| 1338 | +#### Returns |
| 1339 | + |
| 1340 | +| Type | Description | |
| 1341 | +|------|-------------| |
| 1342 | +| `Promise<{ id, name }>` | Key info object | |
| 1343 | + |
| 1344 | +#### Example |
| 1345 | + |
| 1346 | +```js |
| 1347 | +await libp2p.keychain.createKey('keyTest', 'rsa', 4096) |
| 1348 | +const keyInfo = await libp2p.keychain.renameKey('keyTest', 'keyNewNtest') |
| 1349 | +``` |
| 1350 | + |
| 1351 | +### keychain.removeKey |
| 1352 | + |
| 1353 | +Removes a key from the keychain. |
| 1354 | + |
| 1355 | +`libp2p.keychain.removeKey(name)` |
| 1356 | + |
| 1357 | +#### Parameters |
| 1358 | + |
| 1359 | +| Name | Type | Description | |
| 1360 | +|------|------|-------------| |
| 1361 | +| name | `string` | The local key name. It must already exist. | |
| 1362 | + |
| 1363 | +#### Returns |
| 1364 | + |
| 1365 | +| Type | Description | |
| 1366 | +|------|-------------| |
| 1367 | +| `Promise<{ id, name }>` | Key info object | |
| 1368 | + |
| 1369 | +#### Example |
| 1370 | + |
| 1371 | +```js |
| 1372 | +await libp2p.keychain.createKey('keyTest', 'rsa', 4096) |
| 1373 | +const keyInfo = await libp2p.keychain.removeKey('keyTest') |
| 1374 | +``` |
| 1375 | + |
| 1376 | +### keychain.exportKey |
| 1377 | + |
| 1378 | +Export an existing key as a PEM encrypted PKCS #8 string. |
| 1379 | + |
| 1380 | +`libp2p.keychain.exportKey(name, password)` |
| 1381 | + |
| 1382 | +#### Parameters |
| 1383 | + |
| 1384 | +| Name | Type | Description | |
| 1385 | +|------|------|-------------| |
| 1386 | +| name | `string` | The local key name. It must already exist. | |
| 1387 | +| password | `string` | The password to use. | |
| 1388 | + |
| 1389 | +#### Returns |
| 1390 | + |
| 1391 | +| Type | Description | |
| 1392 | +|------|-------------| |
| 1393 | +| `Promise<string>` | Key as a PEM encrypted PKCS #8 | |
| 1394 | + |
| 1395 | +#### Example |
| 1396 | + |
| 1397 | +```js |
| 1398 | +await libp2p.keychain.createKey('keyTest', 'rsa', 4096) |
| 1399 | +const pemKey = await libp2p.keychain.exportKey('keyTest', 'password123') |
| 1400 | +``` |
| 1401 | + |
| 1402 | +### keychain.importKey |
| 1403 | + |
| 1404 | +Import a new key from a PEM encoded PKCS #8 string. |
| 1405 | + |
| 1406 | +`libp2p.keychain.importKey(name, pem, password)` |
| 1407 | + |
| 1408 | +#### Parameters |
| 1409 | + |
| 1410 | +| Name | Type | Description | |
| 1411 | +|------|------|-------------| |
| 1412 | +| name | `string` | The local key name. It must not exist. | |
| 1413 | +| pem | `string` | The PEM encoded PKCS #8 string. | |
| 1414 | +| password | `string` | The password to use. | |
| 1415 | + |
| 1416 | +#### Returns |
| 1417 | + |
| 1418 | +| Type | Description | |
| 1419 | +|------|-------------| |
| 1420 | +| `Promise<{ id, name }>` | Key info object | |
| 1421 | + |
| 1422 | +#### Example |
| 1423 | + |
| 1424 | +```js |
| 1425 | +await libp2p.keychain.createKey('keyTest', 'rsa', 4096) |
| 1426 | +const pemKey = await libp2p.keychain.exportKey('keyTest', 'password123') |
| 1427 | +const keyInfo = await libp2p.keychain.importKey('keyTestImport', pemKey, 'password123') |
| 1428 | +``` |
| 1429 | + |
| 1430 | +### keychain.importPeer |
| 1431 | + |
| 1432 | +Import a new key from a PeerId. |
| 1433 | + |
| 1434 | +`libp2p.keychain.importPeer(name, peerId)` |
| 1435 | + |
| 1436 | +#### Parameters |
| 1437 | + |
| 1438 | +| Name | Type | Description | |
| 1439 | +|------|------|-------------| |
| 1440 | +| name | `string` | The local key name. It must not exist. | |
| 1441 | +| peerId | ['PeerId'][peer-id] | The PEM encoded PKCS #8 string. | |
| 1442 | + |
| 1443 | +#### Returns |
| 1444 | + |
| 1445 | +| Type | Description | |
| 1446 | +|------|-------------| |
| 1447 | +| `Promise<{ id, name }>` | Key info object | |
| 1448 | + |
| 1449 | +#### Example |
| 1450 | + |
| 1451 | +```js |
| 1452 | +const keyInfo = await libp2p.keychain.importPeer('keyTestImport', peerId) |
| 1453 | +``` |
| 1454 | + |
| 1455 | +### keychain.listKeys |
| 1456 | + |
| 1457 | +List all the keys. |
| 1458 | + |
| 1459 | +`libp2p.keychain.listKeys()` |
| 1460 | + |
| 1461 | +#### Returns |
| 1462 | + |
| 1463 | +| Type | Description | |
| 1464 | +|------|-------------| |
| 1465 | +| `Promise<Array<{ id, name }>>` | Array of Key info | |
| 1466 | + |
| 1467 | +#### Example |
| 1468 | + |
| 1469 | +```js |
| 1470 | +const keyInfos = await libp2p.keychain.listKeys() |
| 1471 | +``` |
| 1472 | + |
| 1473 | +### keychain.findKeyById |
| 1474 | + |
| 1475 | +Find a key by it's id. |
| 1476 | + |
| 1477 | +`libp2p.keychain.findKeyById(id)` |
| 1478 | + |
| 1479 | +#### Parameters |
| 1480 | + |
| 1481 | +| Name | Type | Description | |
| 1482 | +|------|------|-------------| |
| 1483 | +| id | `string` | The universally unique key identifier. | |
| 1484 | + |
| 1485 | +#### Returns |
| 1486 | + |
| 1487 | +| Type | Description | |
| 1488 | +|------|-------------| |
| 1489 | +| `Promise<{ id, name }>` | Key info object | |
| 1490 | + |
| 1491 | +#### Example |
| 1492 | + |
| 1493 | +```js |
| 1494 | +const keyInfo = await libp2p.keychain.createKey('keyTest', 'rsa', 4096) |
| 1495 | +const keyInfo2 = await libp2p.keychain.findKeyById(keyInfo.id) |
| 1496 | +``` |
| 1497 | + |
| 1498 | +### keychain.findKeyByName |
| 1499 | + |
| 1500 | +Find a key by it's name. |
| 1501 | + |
| 1502 | +`libp2p.keychain.findKeyByName(id)` |
| 1503 | + |
| 1504 | +#### Parameters |
| 1505 | + |
| 1506 | +| Name | Type | Description | |
| 1507 | +|------|------|-------------| |
| 1508 | +| id | `string` | The local key name. | |
| 1509 | + |
| 1510 | +#### Returns |
| 1511 | + |
| 1512 | +| Type | Description | |
| 1513 | +|------|-------------| |
| 1514 | +| `Promise<{ id, name }>` | Key info object | |
| 1515 | + |
| 1516 | +#### Example |
| 1517 | + |
| 1518 | +```js |
| 1519 | +const keyInfo = await libp2p.keychain.createKey('keyTest', 'rsa', 4096) |
| 1520 | +const keyInfo2 = await libp2p.keychain.findKeyByName('keyTest') |
| 1521 | +``` |
| 1522 | + |
| 1523 | +### keychain.cms.encrypt |
| 1524 | + |
| 1525 | +Encrypt protected data using the Cryptographic Message Syntax (CMS). |
| 1526 | + |
| 1527 | +`libp2p.keychain.cms.encrypt(name, data)` |
| 1528 | + |
| 1529 | +#### Parameters |
| 1530 | + |
| 1531 | +| Name | Type | Description | |
| 1532 | +|------|------|-------------| |
| 1533 | +| name | `string` | The local key name. | |
| 1534 | +| data | `Buffer` | The data to encrypt. | |
| 1535 | + |
| 1536 | +#### Returns |
| 1537 | + |
| 1538 | +| Type | Description | |
| 1539 | +|------|-------------| |
| 1540 | +| `Promise<Buffer>` | Encrypted data as a PKCS #7 message in DER. | |
| 1541 | + |
| 1542 | +#### Example |
| 1543 | + |
| 1544 | +```js |
| 1545 | +const keyInfo = await libp2p.keychain.createKey('keyTest', 'rsa', 4096) |
| 1546 | +const enc = await libp2p.keychain.cms.encrypt('keyTest', Buffer.from('data')) |
| 1547 | +``` |
| 1548 | + |
| 1549 | +### keychain.cms.decrypt |
| 1550 | + |
| 1551 | +Decrypt protected data using the Cryptographic Message Syntax (CMS). |
| 1552 | +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'. |
| 1553 | + |
| 1554 | +`libp2p.keychain.cms.decrypt(cmsData)` |
| 1555 | + |
| 1556 | +#### Parameters |
| 1557 | + |
| 1558 | +| Name | Type | Description | |
| 1559 | +|------|------|-------------| |
| 1560 | +| cmsData | `string` | The CMS encrypted data to decrypt. | |
| 1561 | + |
| 1562 | +#### Returns |
| 1563 | + |
| 1564 | +| Type | Description | |
| 1565 | +|------|-------------| |
| 1566 | +| `Promise<Buffer>` | Decrypted data. | |
| 1567 | + |
| 1568 | +#### Example |
| 1569 | + |
| 1570 | +```js |
| 1571 | +const keyInfo = await libp2p.keychain.createKey('keyTest', 'rsa', 4096) |
| 1572 | +const enc = await libp2p.keychain.cms.encrypt('keyTest', Buffer.from('data')) |
| 1573 | +const decData = await libp2p.keychain.cms.decrypt(enc) |
| 1574 | +``` |
| 1575 | + |
1257 | 1576 | ### metrics.global
|
1258 | 1577 |
|
1259 | 1578 | A [`Stats`](#stats) object of tracking the global bandwidth of the libp2p node.
|
|
0 commit comments