see on GitHub

Backup Encryption



RavenDB's Security Approach

RavenDB's comprehensive security approach includes -

  • Authentication and Certification
    to secure your data while it is transferred between client and server.
  • Database Encryption
    to secure your data while stored in the database.
  • Backup-Files Encryption
    to secure your data while stored for safe-keeping.

Secure Client-Server Communication

To prevent unauthorized access to your data during transfer, apply the following:

  • Enable secure communication in advance, during the server setup.
    Secure communication can be enabled either manually or using the setup-wizard.
  • Authenticate with the server.
    Secure communication requires clients to certify themselves in order to access RavenDB.
    Client authentication code sample:
    
    // path to the certificate you received during the server setup
    var cert = new X509Certificate2(@"C:\Users\RavenDB\authentication_key\admin.client.certificate.RavenDBdom.pfx");
    
    using (var docStore = new DocumentStore
    {
        Urls = new[] { "https://a.RavenDBdom.development.run" },
        Database = "encryptedDatabase",
        Certificate = cert
    }.Initialize())
    {
        // Backup & Restore procedures here
    }

Database Encryption

Secure the data stored on the server by encrypting your database.

Backup-Encryption Overview

Prerequisites to Encrypting Backups

  • Logical-Backup
    There are no prerequisites to encrypting a Logical-Backup.
    An encrypted logical-backup can be generated for an encrypted database and for a non-encrypted database.
    The encryption key used to generate an encrypted logical-backup of an encrypted database can be different than the original database encryption key.

  • Snapshot
    A snapshot is an exact image of your database.
    If the database is not encrypted, its snapshot wouldn't be either.
    If the database is encrypted, its snapshot would also be encrypted using the database encryption key.
    If you want your snapshot to be encrypted, simply take the snapshot of an encrypted database.


Choosing Encryption Mode & Key

Use the same Backup and Restore methods that are used to create and restore un-encrypted backups.
Specify whether encryption is used, and with which encryption key, in the BackupEncryptionSettings structure defined within the PeriodicBackupConfiguration object.

  • BackupEncryptionSettings definition:

    public class BackupEncryptionSettings
    {
        public EncryptionMode EncryptionMode { get; set; }
        public string Key { get; set; }
    
        public BackupEncryptionSettings()
        {
            Key = null;
            EncryptionMode = EncryptionMode.None;
        }
    }

    BackupEncryptionSettings properties:
    Property Type Functionality
    EncryptionMode enum Set the encryption mode.
    None - Use no encryption (default mode).
    UseDatabaseKey - Use the same key the DB is encrypted with (Logical-Backups & Snapshots).
    UseProvidedKey - Provide your own encryption key (Logical-Backups only).
    Key string Pass your own encryption key using this parameter (Logical-Backup only).
    //Use an encryption key of your choice
    EncryptionMode = EncryptionMode.UseProvidedKey,
    Key = "OI7Vll7DroXdUORtc6Uo64wdAk1W0Db9ExXXgcg5IUs="

    Note: When Key is provided and EncryptionMode is set to useDatabaseKey, the database key is used (and not the provided key).

    EncryptionMode definition:

    public enum EncryptionMode
    {
        None,
        UseDatabaseKey,
        UseProvidedKey
    }

Creating an Encrypted Logical-Backup

An encrypted logical-backup can be created for both encrypted and non-encrypted databases.


For a Non-Encrypted Database

  1. To create a non-encrypted logical-backup -
    Set EncryptionMode = EncryptionMode.None
    Or
    Don't set EncryptionMode & Key at all - Default value is: EncryptionMode.None

  2. To create an encrypted logical-backup, set:

    EncryptionMode = EncryptionMode.UseProvidedKey,
       Key = "a_key_of_your_choice"

For an Encrypted Database

  1. To create a non-encrypted logical-backup -
    Set EncryptionMode = EncryptionMode.None

  2. To create an encrypted logical-backup using the database key:
    Set EncryptionMode = EncryptionMode.UseDatabaseKey
    Or
    Don't set EncryptionMode & Key at all - Default value is: EncryptionMode.UseDatabaseKey

    //Encrypting a logical-backup using the database encryption key
    var config = new PeriodicBackupConfiguration
    {
        //Additional settings here..
        //..
    
        //Set backup type to logical-backup
        BackupType = BackupType.Backup,
    
        BackupEncryptionSettings = new BackupEncryptionSettings
        {
            //Use the same encryption key as the database
            EncryptionMode = EncryptionMode.UseDatabaseKey
        }
    };
    var operation = new UpdatePeriodicBackupOperation(config);
    var result = await docStore.Maintenance.SendAsync(operation);
  3. To create an encrypted logical-backup using your own key, set:

    EncryptionMode = EncryptionMode.UseProvidedKey,
       Key = "a_key_of_your_choice"

Creating an Encrypted Snapshot

An encrypted Snapshot can only be created for an encrypted database.

  • To create a Non-Encrypted Snapshot (for a non-encrypted database) -
    Set EncryptionMode = EncryptionMode.None
    Or
    Don't set EncryptionMode & Key at all - Default value is: EncryptionMode.None

  • To create an Encrypted Snapshot (For an encrypted database) -
    Set EncryptionMode = EncryptionMode.UseDatabaseKey
    Or
    Don't set EncryptionMode & Key at all - Default value is: EncryptionMode.UseDatabaseKey

    var config = new PeriodicBackupConfiguration
    {
        //Additional settings here..
        //..
    
        //Set backup type to snapshot.
        //If the database is encrypted, its snapshot will be encrypted as well.
        BackupType = BackupType.Snapshot,
    
        BackupEncryptionSettings = new BackupEncryptionSettings
        {
            //To encrypt a snapshot, EncryptionMode must be set to EncryptionMode.UseDatabaseKey.  
            //Setting it to other values will generate an InvalidOperationException.  
            EncryptionMode = EncryptionMode.UseDatabaseKey
        }
    };
    var operation = new UpdatePeriodicBackupOperation(config);
    var result = await docStore.Maintenance.SendAsync(operation);

Restoring an Encrypted Backup

To restore an encrypted backup you must provide the key that was used to encrypt it.
Pass the key to RestoreBackupOperation via restoreConfiguration.BackupEncryptionSettings.

// restore encrypted database

var restoreConfiguration = new RestoreBackupConfiguration();

//New database name
restoreConfiguration.DatabaseName = "newEncryptedDatabase";

//Backup-file location
var backupPath = @"C:\Users\RavenDB\2019-01-06-11-11.ravendb-encryptedDatabase-A-snapshot";
restoreConfiguration.BackupLocation = backupPath;

restoreConfiguration.BackupEncryptionSettings = new BackupEncryptionSettings
{
    Key = "OI7Vll7DroXdUORtc6Uo64wdAk1W0Db9ExXXgcg5IUs="
};

var restoreBackupTask = new RestoreBackupOperation(restoreConfiguration);
docStore.Maintenance.Server.Send(restoreBackupTask);

Restoring an encrypted Logical-Backup

A database is restored from a logical-backup to its unencrypted form.
To restore a database and encrypt its contents, you have to address it explicitly.

  • To encrypt the restored database:
    To encrypt the database, pass RestoreBackupOperation an encryption key via restoreConfiguration.EncryptionKey.
    Note: This key can be different than the key that was used to encrypt the logical-backup.

    //Restore the database using the key you encrypted it with
    restoreConfiguration.BackupEncryptionSettings = new BackupEncryptionSettings
    {
        Key = "OI7Vll7DroXdUORtc6Uo64wdAk1W0Db9ExXXgcg5IUs="
    };
    
    //Encrypt the restored database using this key
    restoreConfiguration.EncryptionKey = "1F0K2R/KkcwbkK7n4kYlv5eqisy/pMnSuJvZ2sJ/EKo=";
    
    var restoreBackupTask = new RestoreBackupOperation(restoreConfiguration);
    docStore.Maintenance.Server.Send(restoreBackupTask);
  • To restore an unencrypted logical-backup:
    Either provide no encryption key to activate the default value (EncryptionMode.None), or -
    Set EncryptionMode.None Explicitly.

    restoreConfiguration.BackupEncryptionSettings = new BackupEncryptionSettings
    {
        //No encryption
        EncryptionMode = EncryptionMode.None
    };

Restoring a Snapshot

Restore a snapshot as specified in Restoring an Encrypted Database.

  • The database of an un-encrypted snapshot is restored to its un-encrypted form.
  • The database of an encrypted snapshot is restored to its encrypted form.
    You must provide the database key that was used to encrypt the snapshot.