# ssb-private-group-keys

> A collection of basic box2 functions for SSB

Latest version **1.1.2** (published 2023-02-16) · LGPL-3.0-only license · 0 weekly downloads

## Install

```sh
npm install ssb-private-group-keys
pnpm add ssb-private-group-keys
yarn add ssb-private-group-keys
bun add ssb-private-group-keys
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.1.2 |
| Published | 2023-02-16 |
| First published | 2021-08-09 |
| Weekly downloads | 0 |
| License | LGPL-3.0-only |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 5 |
| Unpacked size | 33.6 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 2 |
| Author | mixmix |
| Maintainers | powersource, arj03, staltz, mixmix, cel |

## Links

- npm: https://www.npmjs.com/package/ssb-private-group-keys
- Repository: https://github.com/ssbc/ssb-private-group-keys
- Issues: https://github.com/ssbc/ssb-private-group-keys/issues
- npm.io page: https://npm.io/package/ssb-private-group-keys

## Dependencies (5)

- [ssb-bfe](https://npm.io/package/ssb-bfe.md) ^3.5.0
- [envelope-js](https://npm.io/package/envelope-js.md) ^1.3.2
- [futoin-hkdf](https://npm.io/package/futoin-hkdf.md) ^1.5.1
- [sodium-universal](https://npm.io/package/sodium-universal.md) ^3.1.0
- [private-group-spec](https://npm.io/package/private-group-spec.md) ^1.1.3

## Recent versions

- 1.1.2 (latest) — 2023-02-16
- 1.1.1 — 2022-11-03
- 1.1.0 — 2022-11-03
- 1.0.0 — 2022-07-22
- 0.4.1 — 2022-05-26
- 0.4.0 — 2021-10-28
- 0.3.0 — 2021-09-01
- 0.2.0 — 2021-08-16
- 0.1.0 — 2021-08-09

## README

# ssb-private-group-keys

Basic helper functions implementing the [private-group] spec.

Currently supports classic & bendy butt feed types.

## API

### `directMessageKey(x_dh_secret, x_dh_public, x_feed_id, y_dh_public, y_feed_id) => { key, scheme }`

Create a shared key for communication between your feed and _another_ feed.

If you are _encrypting_ a DM, `x` is your feed, and `y` is the person you are DM'ing.
If you are _decrypting_ a DM, `x` is your feed, and `y` is the message author's.
  - NOTE: this is only for the case that the author is someone else, if you're the author, use your `own_key`

- `x_dh_secret`, `x_dh_public` are feed x's diffie-hellman keys
- `x_feed_id` is the feedId of `x`
- `y_dh_public` is feed y's diffie-hellman public key
- `y_feed_id` is the feedId of `y`

All inputs are [BFE] style buffers.

The output is a `key` (buffer) and associated `scheme` (string) which can be passed into an envelope `key_slot`


#### `directMessageKey.easy(myKeys) => makeKey(feedId) => { key, scheme }`

Convenience function which wraps `directMessageKey`

---

### `poBoxKey(x_dh_secret, x_dh_public, x_id, y_dh_public, y_id) => { key, scheme }`

If you are _encrypting_ to a P.O. Box, then `x` is your feed, and `y` is the P.O. Box.
If you are _decrypting_ a message sent to a P.O. Box, then `x` is the P.O. Box, and `y` is the message author's feed.

- `x_dh_secret`, `x_dh_public` are x's diffie-hellman keys
- `x_id` is the BFE id of `x`
- `y_dh_public` is y's diffie-hellman public key
- `y_id` is the BFE id of `y`

All inputs are [BFE] style buffers.

The output is a `key` (buffer) and associated `scheme` (string) which can be passed into an envelope `key_slot`


#### `poBoxKey.easy(myKeys) => makeKey(poboxId) => { key, scheme }`

Convenience function which wraps `poBoxKey`


---

### `new SecretKey(length?) => secretKey`

Create a secret key that can be used for the group or message key.

methods:
- `secretKey.toBuffer() => buffer` return raw buffer with the key data in it
- `secretKey.toString() => string` returns a `base64` encoded string of the key

### `new SecretKey(buffer) => secretKey`

An alternative way to use the constructor, in case you already have the group
key bytes as a buffer, is to pass the buffer as the argument. This simply
"embodies" the group key as a `SecretKey` instance, it doesn't generate anything
new.

---

### `new DiffieHellmanKeys(keys?, opts?) => dhKeys`

_alias: `DHKeys`_

where:
- `keys` *Object* (optional)
    - is a pair of keys `{ public, secret? }`, each a Buffer or base64 encoded String
        - `public` is required, `secret` is optional
    - if not provided, you are expected to call `dhKeys.generate()` to generate a keypair
- `opts` *Object* (optional)
    - `opts.fromEd25519` *Boolean* sets whether the keys are ed25519 signing keys you would like converted to curve25519 encryption keys.
        - default: `false`
    - `opts.format` *Integer* sets whether the BFE "format" of the encryption key type
        - if `opts.fromEd25519 = true` was used, it's assumed these are dm keys (`format = 0`)
        - else format is not set, which is fine as long as you don't call `dhKeys.toBFE()`
- `dhKeys` *DiffieHellmanKeys instance* with methods:
    - `dhKeys.generate() => dhKeys` - generates public and private dh keys
    - `dhKeys.toBuffer() => { public: Buffer, secret: Buffer }` - returns the raw keys as Buffers
    - `dhKeys.toBFE() => { public: BFE, secret: BFE }` - return [BFE] encodings of the keys (as Buffers)

### `DiffieHellmanKeys.scalarMult(A, B) => result`

A class method for creating shared encryption keys.
- `A` a DHKeys instance, must include `secret` key
- `B` a DHKeys instance
- `result` *Buffer* the result of the scalarMult
    - only useful in advanced cases to conserve memory

NOTE:
- method also takes appropriately shaped objects, see source code.
- there's an advanced signature if you need to conserve memory `(A, B, result) => result`


---

## History

This library was originally extracted from [ssb-tribes].

[private-group]: https://github.com/ssbc/private-group-spec
[ssb-tribes]: https://github.com/mixmix/ssb-tribes
[BFE]: https://github.com/ssb-ngi-pointer/ssb-binary-field-encodings-spec

---
_Source: https://npm.io/package/ssb-private-group-keys · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._