ssb-private-group-keys

A collection of basic box2 functions for SSB

Usage no npm install needed!

<script type="module">
  import ssbPrivateGroupKeys from 'https://cdn.skypack.dev/ssb-private-group-keys';
</script>

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

Can also be used poBoxKey.easy(poBoxKeys) => makeKey(authorFeedId) => { key, scheme }

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 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
  • 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)
      • NOTE: the format chosen for BFE is guessed based on how the keys were input
        • if opts.fromEd25519 = true was used, it's assumed these are dm keys (format = 0)
        • else it's asssumed these are P.O. Box keys (format = 1)

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.