jo/pouch-box

Asymmetric encrypted PouchDB, powered by NaCl's curve25519-xsalsa20-poly1305.

pouch-box

Asymmetric encrypted PouchDB, powered by NaCl's curve25519-xsalsa20-poly1305.

DARC

• Decentralized authentication
• Access control per document
• Revocation per session (account)
• Change session key (eg. when the key was derived from a password this enables password change)

pouch-box uses TweetNaCl.js, a port of TweetNaCl / NaCl to JavaScript for modern browsers and Node.js by Dmitry Chestnykh (@dchest).

The use of this widely ported cryptography library makes it possible to implement this encryption schema in other, possibly more secure platforms, for example with Python and CouchDB.

⚠️ Only to play around! Not yet ready for production use.

Installation

pouch-box is hosted on npm.

Node

Install via npm install pouch-box

var PouchDB = require('pouchdb')
PouchDB.plugin(require('pouch-box'))

Browser

Use the browserified build.

<script src="pouchdb.js"></script>
<script src="pouch-box.js"></script>

Usage

var db = new PouchDB('mydb')

var keyPair = require('tweetnacl').box.keyPair()
// {
//   secretKey: 'smsDNnqeT40IfAwDw0+6x5WzDRYFv0492O/JW/s8tT0=',
//   publicKey: 'sAUGULAT5q2g6gzNMuBX1tkY/FsnoiLA/tv2XmmU2Dg='
// }

db.box(keyPair)
  .then(function(permit) {
    // db is encrypted with `permit.databaseKey` now :P
    //
    // You can query docs which you can decrypt via
    // db.query('box/receivers', {
    //   key: permit.receiver(),
    //   reduce: false,
    //   include_docs: true
    // })
  })

// and later...
db.closeBox()

Details

pouch-box uses three keys: session keys, database keys and document keys:

Session Key

The session keypair is a Curve25519 keypair from NaCl crypto_box. Session keys are not stored in the database, but a permit is created which allows the owner of the session key to decrypt the database key and grant access.

An session keypair looks like this, when encoded as base64:

{
  "secretKey": "smsDNnqeT40IfAwDw0+6x5WzDRYFv0492O/JW/s8tT0=",
  "publicKey": "sAUGULAT5q2g6gzNMuBX1tkY/FsnoiLA/tv2XmmU2Dg="
}

The keypair above can be created in node with tweetnacl:

var nacl = require('tweetnacl')

var sessionKeyPair = nacl.box.keyPair()

{
  secretKey: nacl.util.encodeBase64(sessionKeyPair.secretKey),
  publicKey: nacl.util.encodeBase64(sessionKeyPair.publicKey)
}

Database Key

A database can have one or more database keys. The private database key is stored encrypted in permit documents.

{
  "secretKey": "LCvM/keRcO00AguI5aBX+tY0UfIb7n5w294JJZ2i1XU=",
  "publicKey": "2XiwPX1U6pKPitmhyeubV9g4YYxtIxNfMNE6B5keEmg="
}

The keys are both 32 bytes long. They are based on Curve25519 and created with the NaCl crypto_box crypto_box_keypair function.

The keypair above was created similar to session key generation by the following statements:

var nacl = require('tweetnacl')

var databaseKeyPair = nacl.box.keyPair()

{
  secretKey: nacl.util.encodeBase64(databaseKeyPair.secretKey),
  publicKey: nacl.util.encodeBase64(databaseKeyPair.publicKey)
}

Permit: permit/<permit-id>

A permit contains the database secret key, encrypted with the public session key. Decoupling of session and database keys allows the account holder to change its keys and also enables the use of different public key algorithms for session keys.

The schema of the permit varies between the chosen algorithms. By now only curve25519-xsalsa20-poly1305 is supported. This may change in the future.

The permit id is the base64 encoded public session key, prefixed with permit/.

In order to create the database permit we

1. Create an ephemeral key pair
2. Create a nonce
3. Encrypt the database secret key with nonce, public session key and ephemeral secret key

{
  "_id": "permit/sAUGULAT5q2g6gzNMuBX1tkY/FsnoiLA/tv2XmmU2Dg=",
  "type": "curve25519-xsalsa20-poly1305",
  "createdAt": "2015-03-18T01:29:46.764Z",
  "ephemeral": "RxYOHMWUri/8+aVUDodcocOhTBakV5BckIU9kdeFwSo=",
  "nonce": "Le1AvMAvjkVy3mn1knnmovY36lYk028K",
  "encryptedKey": "7aX5QPyU7OABMFD6YZJF8akTqiNnP4LN9CetpsW/37LgRdl5DPuPtoUiahCMGbCq"
}

var nacl = require('tweetnacl')

var sessionKeyPair = nacl.box.keyPair.fromSecretKey(
  nacl.util.decodeBase64('smsDNnqeT40IfAwDw0+6x5WzDRYFv0492O/JW/s8tT0=')
)
var databaseKeyPair = nacl.box.keyPair.fromSecretKey(
  nacl.util.decodeBase64('LCvM/keRcO00AguI5aBX+tY0UfIb7n5w294JJZ2i1XU=')
)
var permitEphemeralKeyPair = nacl.box.keyPair()
var permitNonce = nacl.randomBytes(nacl.box.nonceLength)

{
  _id: 'permit/' + nacl.util.encodeBase64(sessionKeyPair.publicKey),
  type: 'curve25519-xsalsa20-poly1305',
  createdAt: new Date(),
  ephemeral: nacl.util.encodeBase64(permitEphemeralKeyPair.publicKey),
  nonce: nacl.util.encodeBase64(permitNonce),
  encryptedKey: nacl.util.encodeBase64(nacl.box(
    databaseKeyPair.secretKey,
    permitNonce,
    sessionKeyPair.publicKey,
    permitEphemeralKeyPair.secretKey
  ))
}

Document

Each document is encrypted with its own key. For each database key which was given access to the document a permit is included in the meta document. This empowers the owner to grant access to other accounts on a per document basis.

Each document has its own key which is used together with Nacl secret-key authenticated encryption. The key consists of 32 random bytes.

In order to create the doc permit we

1. Create an ephemeral key pair
2. Create a nonce
3. Encrypt the document key with nonce, public database key and ephemeral secret key

{
  "_id" : "a069f1041735910cf8f613d20000116b",
  "box": {
    "ephemeral" : "PuiUBvQY+7ZFPXXUQ1N2eNE9tgPgIkT1uWj9rpShwXY=",
    "nonce": "zGDblW4Ov8sMKG3YcV/BISueH+REtDr3",
    "receivers": {
      "2XiwPX1U6pKPitmhyeubV9g4YYxtIxNfMNE6B5keEmg=": {
        "nonce": "pSquTTn+/I7REorstK6hSYeKizajtu65",
        "encryptedKey": "GXEfX7V3IwA0izAAJ3HIRCzxDFIUfxMq82QO49ITwKzbi+S+5TanJ/9ubmxOUyBh"
      }
    },
    "cipher": "D9xRZl+/k0gvdBx33CGKaGfLTH731T6jhkMXfh9GfVxETGmTcpzqSJNQ42GPzsafycpdSd7ZTTWBO2vXu06dCha/X8P8C+F6Po+LeerJhKgG"
  }
}

var nacl = require('tweetnacl')
var pouchdb = require('pouchdb')

var databaseKeyPair = nacl.box.keyPair.fromSecretKey(
  nacl.util.decodeBase64('LCvM/keRcO00AguI5aBX+tY0UfIb7n5w294JJZ2i1XU=')
)
var ephemeralKeyPair = nacl.box.keyPair()
var ephemeralNonce = nacl.randomBytes(nacl.box.nonceLength)
var key = nacl.randomBytes(nacl.secretbox.keyLength)
var nonce = nacl.randomBytes(nacl.secretbox.nonceLength)

{
  _id: pouchdb.utils.uuid(32),
  box: {
    ephemeral: nacl.util.encodeBase64(ephemeralKeyPair.publicKey),
    nonce: nacl.util.encodeBase64(ephemeralNonce),
    receivers: {
      [nacl.util.encodeBase64(databaseKeyPair.publicKey)]: {
        nonce: nacl.util.encodeBase64(nonce),
        encryptedKey: nacl.util.encodeBase64(nacl.box(
          key,
          nonce,
          databaseKeyPair.publicKey,
          ephemeralKeyPair.secretKey
        ))
      }
    },
    cipher: nacl.util.encodeBase64(nacl.secretbox(
      nacl.util.decodeUTF8(JSON.stringify({
        text: 'A secure text.',
        createdAt: new Date()
      )),
      nonce,
      key
    ))
  }
}

Testing

npm test

pouch-box's Issues

resolve permit conflicts

Add receivers

nacl lib access

Would it be possible to export nacl methods as extra methods ( pouch utils ? ). The library is already in there, would be nice not to have to dupe it.

Security considerations

Hi there :)

Currently I am using the following setup:

• one user per couch
• session key derived by your session algorithm to pass to DB creation which in turn generates DB key/pass.

However, I would like the couch admin never to have the possibility of decrypting a user encrypted document not meant for him/her. The only way I see this work is by adding another password for the database itself, independent of login/password that could appear in couchdb logs.

Any thoughts appreciated :)

--troks

Change db key selection strategy

Currently the db key which has the most docs encrypted with is choosen as resolve target.

I just thought that maybe we should always choose the remote key, supposed we know what the remote key is.

reduce browserify build size