Crate encrypted_sled

Source
Expand description

encrypted-sled is an (almost) drop in replacement / wrapper around the amazing sled embedded database. Just configure with an encryption and use normally.

§Examples


let cipher = {
    use chacha20poly1305::{ChaCha20Poly1305, Key, Nonce};
    let mut key = Key::default();
    key.copy_from_slice(b"an example very very secret key.");
    encrypted_sled::EncryptionCipher::<ChaCha20Poly1305, _>::new(
        key,
        encrypted_sled::RandNonce::new(rand::thread_rng()),
        encrypted_sled::EncryptionMode::default(),
    )
};

let db = encrypted_sled::open("my_db", cipher).unwrap();

// insert and get
db.insert(b"yo!", b"v1");
assert_eq!(&db.get(b"yo!").unwrap().unwrap(), b"v1");

// Atomic compare-and-swap.
db.compare_and_swap(
    b"yo!",      // key
    Some(b"v1"), // old value, None for not present
    Some(b"v2"), // new value, None for delete
)
.unwrap();

// Iterates over key-value pairs, starting at the given key.
let scan_key: &[u8] = b"a non-present key before yo!";
let mut iter = db.range(scan_key..).unwrap();
assert_eq!(&iter.next().unwrap().unwrap().0, b"yo!");
assert_eq!(iter.next(), None);

db.remove(b"yo!");
assert_eq!(db.get(b"yo!"), Ok(None));

let other_tree = db.open_tree(b"cool db facts").unwrap();
other_tree.insert(
    b"k1",
    &b"a Db acts like a Tree due to implementing Deref<Target = Tree>"[..]
).unwrap();

§Todos

A few things are still not implemented:

  • TransactionalTrees (e.g. performing a transaction on multiple trees at the same time)
  • Database import/export

A few functions don’t handle encryption/decryption gracefully and therefore may cause corrupted data, so please use at your own risk! Encrypted keys will most likely break these

  • update_and_fetch and fetch_and_update
  • Merge operators

Modules§

transaction
Fully serializable (ACID) multi-Tree transactions

Structs§

Batch
A batch of updates that will be applied atomically to the Tree.
CompareAndSwapError
Compare and swap error.
Config
The sled embedded database! Implements Deref<Target = sled::Tree> to refer to a default keyspace / namespace / bucket.
CountingNonce
A simple nonce which always increments by one
Db
Top-level configuration for the system.
EncryptionCipher
Describes the Key, NonceSequence and EncryptionMode used to encrypt / decrypt the data
EncryptionMode
A descriptor for which data should be encrypted/decrypted
IVec
A buffer that may either be inline or remote and protected by an Arc
Iter
An iterator over keys and values in a Tree.
RandNonce
A simple nonce which randomly generates the next nonce in the sequnce
Subscriber
A subscriber listening on a specified prefix
Tree
A flash-sympathetic persistent lock-free B+ tree.

Enums§

Error
An Error type encapsulating various issues that may come up in the operation of a Db.
Event
An event that happened to a key that a subscriber is interested in.
Mode
The high-level database mode, according to the trade-offs of the RUM conjecture.

Traits§

Encryption
Encryption operations
MergeOperator
A function that may be configured on a particular shared Tree that will be applied as a kind of read-modify-write operator to any values that are written using the Tree::merge method.
NonceSequence
Describes a sequence of nonces, similar to an Iterator

Functions§

open
Opens a Db with a default configuration at the specified path. This will create a new storage directory at the specified path if it does not already exist. You can use the Db::was_recovered method to determine if your database was recovered from a previous instance. You can use Config::create_new if you want to increase the chances that the database will be freshly created.

Type Aliases§

Result
The top-level result type for dealing with fallible operations. The errors tend to be fail-stop, and nested results are used in cases where the outer fail-stop error can have try ? used on it, exposing the inner operation that is expected to fail under normal operation. The philosophy behind this is detailed on the sled blog.