mirror of
https://github.com/aljazceru/pear-docs.git
synced 2025-12-17 22:44:21 +01:00
106 lines
4.2 KiB
Markdown
106 lines
4.2 KiB
Markdown
# SecretStream
|
|
|
|
SecretStream is used to securely create connections between two peers in Hyperswarm. It is powered by Noise and libsodium's SecretStream. SecretStream can be used as a standalone module to provide encrypted communication between two parties.
|
|
|
|
The SecretStream instance is a Duplex stream that supports usability as a normal stream for standard read/write operations. Furthermore, its payloads are encrypted with libsodium's SecretStream for secure transmission.
|
|
|
|
>[GitHub (SecretStream)](https://github.com/holepunchto/hyperswarm-secret-stream)
|
|
|
|
* [SecretStream](secretstream.md#installation)
|
|
* [Create a new instance](secretstream.md#const-s--new-secretstreamisinitiator-rawstream-options)
|
|
* Basic:
|
|
* Properties:
|
|
* [s.publicKey](secretstream.md#spublickey)
|
|
* [s.remotePublicKey](secretstream.md#sremotepublickey)
|
|
* [s.handshakeHash](secretstream.md#shandshakehash)
|
|
* Methods:
|
|
* [s.start(rawStream, \[options\])](secretstream.md#sstartrawstream-options)
|
|
* [s.setTimeout(ms)](secretstream.md#ssettimeoutms)
|
|
* [s.setKeepAlive(ms)](secretstream.md#ssetkeepalivems)
|
|
* [SecretStream.keyPair(\[seed\])](secretstream.md#const-keypair--secretstreamkeypairseed)
|
|
* Events:
|
|
* [connect](secretstream.md#sonconnect-onconnecthandler)
|
|
|
|
### Installation
|
|
|
|
Install with [npm](https://www.npmjs.com/):
|
|
|
|
```bash
|
|
npm install @hyperswarm/secret-stream
|
|
```
|
|
|
|
### API
|
|
|
|
#### **`const s = new SecretStream(isInitiator, [rawStream], [options])`**
|
|
|
|
Makes a new stream.
|
|
|
|
`isInitiator` is a boolean indicating whether the process is a client or the server.
|
|
|
|
`rawStream` can be set to an underlying transport stream to run the noise stream over.
|
|
|
|
`options` include:
|
|
|
|
| Property | Description | Type |
|
|
| :-------------------: | -------------------------------------------------------------------------- | ----------------------------------------------------- |
|
|
| **`pattern`** | Accept server connections for this topic by announcing it to the DHT | String |
|
|
| **`remotePublicKey`** | PublicKey of the other party | String |
|
|
| **`keyPair`** | Combination of PublicKey and SecretKey | { publicKey, secretKey } |
|
|
| **`handshake`** | To use a handshake performed elsewhere, pass it here | { tx, rx, handshakeHash, publicKey, remotePublicKey } |
|
|
|
|
The SecretStream returned is a Duplex stream to write data to and read data from, it's a normal stream with payloads that are encrypted using the libsodium secretstream.
|
|
|
|
> By default, the above process uses ed25519 for the handshakes.
|
|
|
|
To load the key pair asynchronously, the secret stream also supports passing in a promise instead of the keypair that later resolves to `{ publicKey, secretKey }`. The stream lifecycle will wait for the resolution and auto-destroy the stream if the promise gives an error.
|
|
|
|
#### Properties
|
|
|
|
#### **`s.publicKey`**
|
|
|
|
Gets the local public key.
|
|
|
|
#### **`s.remotePublicKey`**
|
|
|
|
Gets the remote's public key. Populated after `open` is emitted.
|
|
|
|
#### **`s.handshakeHash`**
|
|
|
|
Gets the unique hash of this handshake. Populated after `open` is emitted.
|
|
|
|
#### Methods
|
|
|
|
#### **`s.start(rawStream, [options])`**
|
|
|
|
Starts a SecretStream from a rawStream asynchronously.
|
|
|
|
```javascript
|
|
const s = new SecretStream({
|
|
autoStart: false // call start manually
|
|
})
|
|
|
|
// ... do async stuff or destroy the stream
|
|
|
|
s.start(rawStream, {
|
|
... options from above
|
|
})
|
|
```
|
|
|
|
#### **`s.setTimeout(ms)`**
|
|
|
|
Sets the stream timeout. If no data is received within a `ms` window, the stream is auto-destroyed.
|
|
|
|
#### **`s.setKeepAlive(ms)`**
|
|
|
|
Sends a heartbeat (empty message) every time the socket is idle for `ms` milliseconds.
|
|
|
|
#### **`const keyPair = SecretStream.keyPair([seed])`**
|
|
|
|
Generates an ed25519 key pair.
|
|
|
|
#### Events
|
|
|
|
#### **`s.on('connect', onConnectHandler)`**
|
|
|
|
Emitted when the handshake is fully done. It is safe to write to the stream immediately though, as data is buffered internally before the handshake has been completed.
|