E3DB Library Core Concepts

Tozny provides a variety of open source libraries and SDKs to perform storage, retrieval, and crypto operations. The libraries are very straightforward, and the following basic concepts will aid in your understanding of the system:

  • E3DB is a JSON Object store: The each record is a set of name/value pairs that you interact with in your native language.
  • Crypto happens in the client library: The value of each field is encrypted separately. Encryption and decryption always happen in the client libraries, not on the server. That’s what’s so great about end-to-end encryption.
  • E3DB Clients: Are any system with a set of E3DB keys. They each have their own client_id, which is a random unique identifier. Create clients in the admin console.
  • Forms: Are a kind of public “bucket” that untrusted parties can write data to. You can create a form in the admin console and include your form token in your HTML code.
  • Record: A record in E3DB is a set of name/value pairs plus metadata. Think of it like a JSON object.
  • Metadata: Records have metadata like content type and the client_id of the writer, as well as free-form tags that can be used to organize or query your data.
  • Content type: A string representing the type of this data. This can be anything that makes sense for your use. For instance a social network might have content types like “friends”, “timeline”, and “account”.
  • Writing: Writing a record is as simple as constructing it, e.g. with a set of name/value pairs and calling the write method. This encrypts the data on the client, transfers it to the server, and returns a record_id.
  • Reading: You can read a record with a record_id, or after querying. While reading, the data looks like a set of name/value pairs and metadata. For instance, in Java it’s a Map. Under the hood, the data is transferred from the server and decrypted in the client.
  • Updating: We provide an atomic update function that lets you safely modify a record. It will fail if the record has been modified since last read.
  • Querying: You can ask E3DB to return a set of records to the client and iterate through that. You can query based on various metadata like content type.
  • Sharing: An E3DB client can share a set of records (e.g. based on their content type) with another client. For instance, a social network might share its timeline data between two users. A cryptographic key exchange occurs to enable this efficiently for a large or small number of clients and data.
  • Publish / Subscribe: A client can subscribe to events relating to a record or a content type so that you receive notifications about new records or changes to records. This uses efficient websockets.
  • Profiles: Your servers, users, developers, and apps can each have multiple “profiles”. That is to say that a given system can have multiple E3DB Clients with their multiple sets of keys. Generally, profiles are stored in ~/.tozny/profile1 ~/.tozny/profile2, etc. Developers might use profiles to distinguish among dev, staging, and production clients. Users might use profiles to distinguish among work and personal clients.