duckdb::EncryptionEngine Class Reference

Static Public Member Functions
static const_data_ptr_t	GetKeyFromCache (DatabaseInstance &db, const string &key_name)
	General key management wrapper functions.
static bool	ContainsKey (DatabaseInstance &db, const string &key_name)
static void	AddKeyToCache (DatabaseInstance &db, data_ptr_t key, const string &key_name, bool wipe=true)
static string	AddKeyToCache (DatabaseInstance &db, data_ptr_t key)
static void	AddTempKeyToCache (DatabaseInstance &db)
static void	EncryptBlock (AttachedDatabase &attached_db, const string &key_id, FileBuffer &block, FileBuffer &temp_buffer_manager, uint64_t delta)
	Encryption Functions.
static void	DecryptBlock (AttachedDatabase &attached_db, const string &key_id, data_ptr_t internal_buffer, uint64_t block_size, uint64_t delta)
static void	EncryptTemporaryBuffer (DatabaseInstance &db, data_ptr_t buffer, idx_t buffer_size, data_ptr_t metadata)
static void	DecryptTemporaryBuffer (DatabaseInstance &db, data_ptr_t buffer, idx_t buffer_size, data_ptr_t metadata)

Constructor & Destructor Documentation

EncryptionEngine()

duckdb::EncryptionEngine::EncryptionEngine

(

)

                                   {
}

~EncryptionEngine()

duckdb::EncryptionEngine::~EncryptionEngine

(

)

                                    {
}

Member Function Documentation

GetKeyFromCache()

const_data_ptr_t duckdb::EncryptionEngine::GetKeyFromCache ( DatabaseInstance &  db, const string &  key_name  )

static

General key management wrapper functions.

                                                                                               {
    auto &keys = EncryptionKeyManager::Get(db);
    return keys.GetKey(key_name);
}

Here is the caller graph for this function:

ContainsKey()

bool duckdb::EncryptionEngine::ContainsKey ( DatabaseInstance &  db, const string &  key_name  )

static

                                                                               {
    auto &keys = EncryptionKeyManager::Get(db);
    return keys.HasKey(key_name);
}

AddKeyToCache() [1/2]

void duckdb::EncryptionEngine::AddKeyToCache ( DatabaseInstance &  db, data_ptr_t  key, const string &  key_name, bool  wipe = true  )

static

                                                                                                            {
    auto &keys = EncryptionKeyManager::Get(db);
    if (!keys.HasKey(key_name)) {
        keys.AddKey(key_name, key);
    } else {
        duckdb_mbedtls::MbedTlsWrapper::AESStateMBEDTLS::SecureClearData(key,
                                                                         MainHeader::DEFAULT_ENCRYPTION_KEY_LENGTH);
    }
}

AddKeyToCache() [2/2]

string duckdb::EncryptionEngine::AddKeyToCache ( DatabaseInstance &  db, data_ptr_t  key  )

static

                                                                           {
    auto &keys = EncryptionKeyManager::Get(db);
    const auto key_id = keys.GenerateRandomKeyID();
 
    if (!keys.HasKey(key_id)) {
        keys.AddKey(key_id, key);
    } else {
        duckdb_mbedtls::MbedTlsWrapper::AESStateMBEDTLS::SecureClearData(key,
                                                                         MainHeader::DEFAULT_ENCRYPTION_KEY_LENGTH);
    }
 
    return key_id;
}

AddTempKeyToCache()

void duckdb::EncryptionEngine::AddTempKeyToCache ( DatabaseInstance &  db )

static

Add a temporary key to the cache

                                                             {
    const auto length = MainHeader::DEFAULT_ENCRYPTION_KEY_LENGTH;
    data_t temp_key[length];
 
    // we cannot generate temporary keys with read-only enabled
    auto metadata = make_uniq<EncryptionStateMetadata>(EncryptionTypes::GCM, length, EncryptionTypes::V0_1);
    auto encryption_state = db.GetEncryptionUtil(false)->CreateEncryptionState(std::move(metadata));
    encryption_state->GenerateRandomData(temp_key, length);
 
    string key_id = "temp_key";
    AddKeyToCache(db, temp_key, key_id);
}

Here is the caller graph for this function:

EncryptBlock()

void duckdb::EncryptionEngine::EncryptBlock ( AttachedDatabase &  attached_db, const string &  key_id, FileBuffer &  block, FileBuffer &  temp_buffer_manager, uint64_t  delta  )

static

Encryption Functions.

store the nonce at the start of the block

encrypt the data including the checksum

Finalize and extract the tag

store the generated tag behind the nonce (but still at the beginning of the block)

                                                                                     {
    auto &db = attached_db.GetDatabase();
    data_ptr_t block_offset_internal = temp_buffer_manager.InternalBuffer();
    auto encrypt_key = GetKeyFromCache(db, key_id);
    auto version = attached_db.GetStorageManager().GetEncryptionVersion();
    auto cipher = attached_db.GetStorageManager().GetCipher();
    auto metadata = make_uniq<EncryptionStateMetadata>(cipher, MainHeader::DEFAULT_ENCRYPTION_KEY_LENGTH, version);
    auto encryption_state = db.GetEncryptionUtil(attached_db.IsReadOnly())->CreateEncryptionState(std::move(metadata));
 
    EncryptionTag tag;
    EncryptionNonce nonce(cipher, version);
    encryption_state->GenerateRandomData(nonce.data(), nonce.size());
 
    memcpy(block_offset_internal, nonce.data(), nonce.size());
    encryption_state->InitializeEncryption(nonce, encrypt_key);
 
    auto checksum_offset = block.InternalBuffer() + delta;
    auto encryption_checksum_offset = block_offset_internal + delta;
    auto size = block.size + Storage::DEFAULT_BLOCK_HEADER_SIZE;
 
    auto aes_res = encryption_state->Process(checksum_offset, size, encryption_checksum_offset, size);
 
    if (aes_res != size) {
        throw IOException("Block encryption failure: in- and output size differ (%llu/%llu)", size, aes_res);
    }
 
    encryption_state->Finalize(block.InternalBuffer() + delta, 0, tag.data(), tag.size());
 
    memcpy(block_offset_internal + nonce.size(), tag.data(), tag.size());
}

Here is the call graph for this function:

DecryptBlock()

void duckdb::EncryptionEngine::DecryptBlock ( AttachedDatabase &  attached_db, const string &  key_id, data_ptr_t  internal_buffer, uint64_t  block_size, uint64_t  delta  )

static

initialize encryption state

load the stored nonce and tag

Initialize the decryption

decrypt the block including the checksum

check the tag

                                                                         {
    auto &db = attached_db.GetDatabase();
    auto version = attached_db.GetStorageManager().GetEncryptionVersion();
    auto cipher = attached_db.GetStorageManager().GetCipher();
    auto metadata = make_uniq<EncryptionStateMetadata>(cipher, MainHeader::DEFAULT_ENCRYPTION_KEY_LENGTH, version);
    auto decrypt_key = GetKeyFromCache(db, key_id);
    auto encryption_state = db.GetEncryptionUtil(attached_db.IsReadOnly())->CreateEncryptionState(std::move(metadata));
 
    EncryptionTag tag;
    EncryptionNonce nonce(cipher, version);
    memcpy(nonce.data(), internal_buffer, nonce.size());
    memcpy(tag.data(), internal_buffer + nonce.size(), tag.size());
 
    encryption_state->InitializeDecryption(nonce, decrypt_key);
 
    auto checksum_offset = internal_buffer + delta;
    auto size = block_size + Storage::DEFAULT_BLOCK_HEADER_SIZE;
 
    auto aes_res = encryption_state->Process(checksum_offset, size, checksum_offset, size);
 
    if (aes_res != block_size + Storage::DEFAULT_BLOCK_HEADER_SIZE) {
        throw IOException("Block decryption failure: in- and output size differ (%llu/%llu)", size, aes_res);
    }
 
    encryption_state->Finalize(internal_buffer + delta, 0, tag.data(), tag.size());
}

Here is the call graph for this function:

EncryptTemporaryBuffer()

void duckdb::EncryptionEngine::EncryptTemporaryBuffer ( DatabaseInstance &  db, data_ptr_t  buffer, idx_t  buffer_size, data_ptr_t  metadata  )

static

store the nonce at the start of metadata buffer

Finalize and extract the tag

store the generated tag after consequetively the nonce

                                                                   {
    if (!ContainsKey(db, "temp_key")) {
        AddTempKeyToCache(db);
    }
 
    auto temp_key = GetKeyFromCache(db, "temp_key");
    // we cannot encrypt temp buffers in read-only mode
    auto encryption_util = db.GetEncryptionUtil(false);
    // we hard-code GCM here for now, it's the safest and we don't know what is configured here
    auto state_metadata = make_uniq<EncryptionStateMetadata>(
        EncryptionTypes::GCM, MainHeader::DEFAULT_ENCRYPTION_KEY_LENGTH, EncryptionTypes::V0_1);
    auto encryption_state = encryption_util->CreateEncryptionState(std::move(state_metadata));
 
    // zero-out the metadata buffer
    memset(metadata, 0, DEFAULT_ENCRYPTED_BUFFER_HEADER_SIZE);
 
    EncryptionTag tag;
    EncryptionNonce nonce(EncryptionTypes::CipherType::GCM, EncryptionTypes::V0_1);
 
    encryption_state->GenerateRandomData(nonce.data(), nonce.size());
 
    memcpy(metadata, nonce.data(), nonce.size());
    encryption_state->InitializeEncryption(nonce, temp_key);
 
    auto aes_res = encryption_state->Process(buffer, buffer_size, buffer, buffer_size);
 
    if (aes_res != buffer_size) {
        throw IOException("Temporary buffer encryption failure: in- and output size differ (%llu/%llu)", buffer_size,
                          aes_res);
    }
 
    encryption_state->Finalize(buffer, 0, tag.data(), tag.size());
 
    memcpy(metadata + nonce.size(), tag.data(), tag.size());
 
    // check if tag is correctly stored
    D_ASSERT(memcmp(tag.data(), metadata + nonce.size(), tag.size()) == 0);
}

Here is the call graph for this function:

DecryptTemporaryBuffer()

void duckdb::EncryptionEngine::DecryptTemporaryBuffer ( DatabaseInstance &  db, data_ptr_t  buffer, idx_t  buffer_size, data_ptr_t  metadata  )

static

initialize encryption state

                                                                   {
    auto encryption_util = db.GetEncryptionUtil(false);
    auto temp_key = GetKeyFromCache(db, "temp_key");
    auto state_metadata = make_uniq<EncryptionStateMetadata>(
        EncryptionTypes::GCM, MainHeader::DEFAULT_ENCRYPTION_KEY_LENGTH, EncryptionTypes::EncryptionVersion::V0_1);
    auto encryption_state = encryption_util->CreateEncryptionState(std::move(state_metadata));
 
    DecryptBuffer(*encryption_state, temp_key, buffer, buffer_size, metadata);
}

Here is the call graph for this function:

---

The documentation for this class was generated from the following file:

• external/duckdb/duckdb.cpp