OrbitDB Simple Encryption

Fork of @orbitdb/simple-encryption that adds experimental encrypted-database detection via isDatabaseEncrypted.
This fork is intended as a temporary workaround and may be removed once orbitdb/simple-encryption#1 is merged or a better upstream solution is available.

NOTE This encryption module is not audited in any way for security and is intended for demonstration purposes only.

Install

This project uses npm and nodejs.

npm i @le-space/orbitdb-simple-encryption

Usage

To implement encryption within your database, create an encryption object and pass it to OrbitDB's open function:

import { createOrbitDB } from '@orbitdb/core'
import SimpleEncryption from '@le-space/orbitdb-simple-encryption'


// Instantiate encryption for either data, replication or both.
const replication = await SimpleEncryption({ password: 'hello' })
const data = await SimpleEncryption({ password: 'world' })

const encryption = { data, replication }

// Set up OrbitDB. See https://github.com/orbitdb/orbitdb/blob/main/docs/GETTING_STARTED.md for more information if you are unfamiliar with OrbitDB.
const db = await orbitdb.open('db-encrypted', { encryption })

When replicating a database, initiate the same encryption configuration and pass it to open:

import { createOrbitDB } from '@orbitdb/core'
import SimpleEncryption from '@le-space/orbitdb-simple-encryption' 


// Instantiate encryption for either data, replication or both.
const replication = await SimpleEncryption({ password: 'hello' })
const data = await SimpleEncryption({ password: 'world' })

const encryption = { data, replication }

const dbAddress = '0x0' // the address of the remote database. 

// Set up OrbitDB. See https://github.com/orbitdb/orbitdb/blob/main/docs/GETTING_STARTED.md for more information if you are unfamiliar with OrbitDB.
const db = await orbitdb.open(dbAddress, { encryption })

Detecting Encrypted Databases

The isDatabaseEncrypted() function helps detect if a database is encrypted when it has been opened without any encryption options. It currently detects encryption in two main ways:

• Data-only encryption: db.all() succeeds, entries exist, but their value fields are undefined (while hash is present).
• Replication and/or data encryption: db.all() throws a TypeError such as Cannot read properties of undefined (reading 'value') because OrbitDB cannot decrypt the underlying log entries.

import SimpleEncryption, { isDatabaseEncrypted } from '@le-space/orbitdb-simple-encryption'

// Try opening database without encryption
const db = await orbitdb.open(address, {})

// Check if it's encrypted
const isEncrypted = await isDatabaseEncrypted(db)

if (isEncrypted) {
  // Application-specific flow: ask user for password / config
  const password = await promptForPassword()

  // Depending on how the DB was created, you may need:
  // - data encryption only
  // - replication encryption only
  // - or both
  const replication = await SimpleEncryption({ password })
  const data = await SimpleEncryption({ password })

  await db.close()

  // Example: open with both replication and data encryption
  const encryptedDb = await orbitdb.open(address, {
    encryption: { replication, data }
  })
}

Contributing

Take a look at our organization-wide Contributing Guide. You'll find most of your questions answered there. Some questions may be answered in the FAQ, as well.

If you want to code but don't know where to start, check out the issues labelled "help wanted".

License

MIT OrbitDB Community