Composite Key Integration

[felsweg-iota]

• Feature Name: composite-key-integration
• Start Date: (2022-01-19)

Summary

Stronghold contains two major components that secure secret data: The Snapshot file and the entries inside the Vault. Both components and objects are encrypted and decrypted on demand. The composite key shall add an additional layer of security. It shall be used to encrypt and decrypt the keys for the Vault inside the KeyStore itself, as well as have keys related to Snapshots safely stored in a hybrid system consisting of one part in memory and another part on disk.

Motivation

The KeyStore contains all keys for each secret inside the Vault. While the entries inside the Vault are secured by encryption and memory protection, the keys inside the KeyStore are not. This RFC proposes the integration of a secure distribution of a composite key according to the Boojum procedure, providing an interface to transparently de-/encrypt the KeyStore on demand, so that the keys themselves are exposed in plain memory only at a minimum.

Guide-level explanation

We introduce a new type called SecureKey that takes a key for initialization. At a later point in time, the key can be reconstructed from two guarded memory parts fragmented across memory ( another proposal suggest to even distribute parts across memory and persistent storage; making use of non-contiguous memory types).

// importing secure memory manager called `Buffer`
// this type should reflect new capabilities given by the 
// reworked runtime
use crate::memory::Buffer;
use std::sync::{Arc, Mutex}
use zeroize::Zeroize;

pub struct SecureKey {
    x : Arc<Mutex<Buffer>>,
    y : Arc<Mutex<Buffer>>
}

impl SecureKey {

    /// Initializes the internal key fragments, consume the 
    /// provided actual key. The key must have a specific size,
    /// depending on the underlying hashing algorithm. 
    pub fn new<K>(key : K) -> Result<Self, KeyError> where K : Zeroize + AsRef<Vec<u8>> { ... }

    /// `shuffle()` is being called either periodically, or event based. 
    /// Internally it updates the key fragments, so no residual key fragment
    /// is retained in memory   
    fn shuffle(&self) { ... }

    /// `key()` reconstructs the key and returns it as secure memory type
    /// The returned type must implement [`Zeroize`].
    pub fn key() -> Buffer { ... }
}

/// - key store 

/// The Keystore stores all keys to de-/encrypt secrets from the vault
/// Here the `KeyStore` implementation is extended from this 
/// [RFC](https://github.com/iotaledger/stronghold-rfc/blob/RFC/0006/texts/0006-remove-key-from-vault.md). 
pub struct KeyStore {

    /// The master key is being used to de-/encrypt the keys to the vault itself
    master : SecureKey,

    /// A mapping between `VaultId` and the `Key<Provider>`
    /// The allocation of the keys must ensure that memory 
    /// is non-contiguous for the key type
    keys : HashMap<VaultId, Key<Provider>>
}

/// Example implementation of the new keystore
impl KeyStore {

    /// creates a new keystore with a master key
    pub fn new<K>(master : K) -> Self where K : Zeroize + AsRef<Vec<u8>> { ... }

    /// Takes the key out, and automatically decrypts it. 
    /// The key itself should not remain in memory for a long period of time
    /// TODO: this could also be a buffer type, that is still encrypted while taken
    /// out, and needs to be decrypted on demand
    pub fn take(&mut self) -> Option<Vec<u8>> { ... }

    /// Inserts a new key with an associated vault_id
    pub fn insert(&mut self, vault_id : VaultId, key : Key<Provider>) { ... }

    /// Creates a new key with an associated VaultId
    /// They newly created key will be directly encrypted with the master key
    pub fn create_key(&mut self, vault_id : VaultId) { ... }

    /// Clears all keys from the keystore, and optionally sets
    /// a new master key for all keys. This operation must be secure
    /// eg. all keys need to be zeroed and then disposed
    pub fn clear<K>(&mut self, master : Option<K>) -> Self where K : Zeroize + AsRef<Vec<u8>> { ... }
}


impl From<HashMap<VaultId, Key<Provider>>> for KeyStore {

    /// Implement the conversion from `HashMap<CaultId, Key<Provider>>` 
    /// into `KeyStore`. This function call must ensure, that the keys 
    /// themselves are encrypted by the master key
    fn from(former : HashMap<VaultId, Key<Provider>>) -> Self { ... }
}

// some other module, that has a dependency on `KeyStore`

/// 
struct Client { 
    keystore : KeyStore,
    vault : DbView<Provider>
    ...
}

async fn main() -> Result<(), Error> {

    /// The master key remains in memory, to enable
    /// further operation on the snapshot without user interaction
    let master = SecureKey::new(b"plj76vguz6sbmcn78ssehdk_".to_vec());

    // The Client initializes the Vault and the `KeyStore`, so the key itself
    // remains invisible for the user
    let mut client = Client::load(Snapshot::named("known-location"), &master)?;

    // taken from this 
    // [RFc](https://github.com/iotaledger/stronghold-rfc/pull/2)
    let slip10_generate = Slip10Generate::default().write_secret(
        Location::generic(vault_path.clone(), "record-1")
    );

    // execute the procedure
    let _ = client.execute_procedure(slip10_generate)?;


    Ok(())
}

The example above stores the KeyStore and a view of all vaults inside DbView. Accessing and working with secrets is now transparently decrypted and encrypted, whenever a new entry is written into the vault, as well as executing procedures.

Reference-level explanation

The KeyStore allocates at least 2 pages of memory in separate regions of memory, or even distributes the key partitions between memory and disk space. Ideally, the allocated regions themselves are non-contiguous, decreasing the attack surface and increases the amount of effort, that needs to be undertaken in order to reconstruct the key. The KeyStore suggest two method for constantly changing the contents of the key partitions, we call "shuffling": A time bases approach, and an event based approach. Both shall be discussed here:

Time Based Shuffling

The key's partitions are being shuffled on constant time intervals in a separate thread.

pros:

• choosing a small number of intervals ( between 10 - 50ms ), the key's entropy is guaranteed
• the shuffling is done automatically in the background

con:

• induces extra load on the CPU
• if the key's partition are being stored across memory and disk space, a load on disk space is being incurred

Event Based Shuffling

The key's partitions are being shuffled on non-deterministic events, like accessing a vault, or executing a procedure.

pros:

• depending on the number of events, the load on the CPU is reduced

cons:

• if events occur less frequently, the long certain parts of the key's partitions remain the same in memory

Drawbacks

Even though the key's partitions makes it harder to locate the key parts, the parts themselves remain in memory. Further memory protection is needed to avoid the possible to retrieve the key by memory dumps.

Rationale and alternatives

• This design is the best trade-off so far between interactive key provisioning by the user, and storing the key in memory so far
• Other solutions would require the user to store encryption keys either in plain memory, which is unsafe, or employ a systems key chain to store the key itself. The latter would require some knowledge about safely integrating the key to provide for Stronghold operations

Unresolved questions

• How do we implement non-contiguous memory, that spreads across memory and disk space?
• What type shall be used to return the key for operations? One possible option would be to reuse the Guarded-types for safe usage.
• How to we keep backwards compatibility on the Snapshot file format?

Future possibilities

Computing hardware may offer possibilities for open source hardware memory protections, where the key's partitions can be stored.