kappa-private v2.0.1

kappa-private

Use private-box to send encrypted messages between kappa-core feeds. Converts ed25519 signing keys to curve25519 keys for Diffie-Hellman. Heavily inspired by ssb-private

Encryption can be done manually, as in the second example, or using an encoder which you pass to kappa-core.

If you use the encoder, messages must be objects, and for any object with a recipients property containing an array of feed keys represented as hex encoded strings, the message will be encrypted to those public keys.

Examples

As a custom encoder for hypercore

const KappaPrivate = require('.')
const kappa = require('kappa-core')

const storage = './exampleKappaCore'

// the first time we run we dont get know our secret key
// we can instantiate the encoder without one, but we will
// not be able to decrypt message until we set it.
const kappaPrivate = KappaPrivate()
const core = kappa(storage, { valueEncoding: kappaPrivate.encoder() })

core.writer('local1', (err, feed1) => {
  if (err) throw err
  feed1.ready(() => {
    // pass secretKey to the encoder
    kappaPrivate.secretKey = feed1.secretKey

    core.writer('local2', (err, feed2) => {
      if (err) throw err
      feed2.ready(() => {
        // adding a recipients property with an array of feed ids
        // means it will be encrypted to those feeds
        var message = {
          dog: 'woof',
          recipients: [feed1.key.toString('hex'), feed2.key.toString('hex')]
        }

        feed1.append(message, (err, seq) => {
          if (err) throw err
          feed1.get(seq, (err, message) => {
            if (err) throw err
            console.log(message) // the message in plaintext
          })
        })
      })
    })
  })
})

Doing the encryption manually

const { box, unbox } = require('.')

var core = kappa('./example', { valueEncoding: 'json' })

var message = { dog: 'woof' }

core.writer('local1', (err, feed1) => {
  feed1.append({ foo: 1 }, (err, seq) => {
    core.writer('local2', (err, feed2) => {
      const boxedMsg = box(message, [ feed1.key ])
      feed2.append(boxedMsg)
      console.log('unboxed: ', unbox(boxedMsg, feed1.secretKey)) 
      console.log(unbox(boxedMsg, feed1.secretKey) === message) // true
    })
  })
})

API

const KappaPrivate = require('kappa-private') const kappaPrivate = KappaPrivate(secretKey)

Return an instance of KappaPrivate. secretKey, if given, secretKey is an optional 32 byte buffer used to decrypt messages. If the secret key is not yet known (such as when instantiating kappa-core for the first time) it can be passed in later by setting the .secretKey property.

If the secret key is not given at all, messages will be encrypted but not decrypted.

kappaPrivate.encoder() returns an encoder compatible with hypercore.

Messages will be encrypted to given recipients if they are JSON objects containing a property recipients. This should be an array of public key feeds encoded as hex strings. All other messages will be published unencrypted.

box(message, recipients)

Encrypt a message to up to 7 recipients. Returns a string with the encrypted message encoded as base64

• message is an object containing data to be encrypted
• recipients is an array of up to 7 buffers, the ed25519 public signing keys of recipients

unbox(cyphertext, secretKey)

Attempt to decrupt a message with a given secret key. If successful, returns an object containing the message data.

• cyphertext a string containing a base64 encoded encrypted message produced by box
• secretKey a buffer containing the secret ed25519 signing key

isBoxedMessage(message)

• returns true if given something that looks like a message encrypted using this module.