see on GitHub

Backup Encryption



RavenDB's Security Approach

The encryption of backup files secures data while stored for safe-keeping.
This is just one respect of RavenDB's comprehensive security approach.
Other respects are -

  • Securing data while transferred between server and client
  • Securing data while stored in the database.

These subjects are briefly introduced here, to help you put backup-encryption in context.


Secure Server-Client Communication

You can prevent unauthorized access to your data during transfer, by enabling authentication and Certification of server-client communication.

  • Enable secure communication in advance, during the server setup.
    You can enable it while installing the server either manually or using the setup-wizard.
  • Authenticate with the server.
    Be aware that enabling secure communication will require 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

Database encryption prevents unauthorized access to your data by encrypting it on the server.

  • Secure communication to enable database encryption.
    RavenDB emphasizes the importance of overall security, by allowing the creation of an encrypted database only when server-client communication is secure. If you want to encrypt your database, you need to enable authentication and certification first.

Backup-Encryption Overview

Prerequisites to Encrypting Backups

  • 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.
    You can also generate an encrypted logical backup of an encrypted database using a different encryption key.
  • If you want your snapshot to be encrypted, simply take the snapshot of an encrypted database.

A snapshot is an exact image of the database. If the database is encrypted, so would be its snapshot. If the DB is not encrypted, a snapshot of it wouldn't be either.


Choosing Encryption Mode

Use the same Backup and Restore methods you use to create and restore unencrypted backups.
Pass them a BackupEncryptionSettings structure to determine whether encryption is used, and if so - with which encryption key.

  • BackupEncryptionSettings definition:

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

    BackupEncryptionSettings parameters:

    Parameter Type Functionality
    EncryptionMode enum Set the encryption mode.
    none - Use no encryption (this is the default mode).
    UseProvidedKey - Provide your own encryption key.
    UseDatabaseKey - Use the same key the DB is encrypted with.
    Key string Pass your own encryption key using this parameter

    EncryptionMode definition:

    public enum EncryptionMode
    {
        None,
        UseDatabaseKey,
        UseProvidedKey
    }


The Encryption Key

To encrypt your backup, either use the database's encryption key or choose a new key.

  • Using the database's Key
    If your database is encrypted, you can utilize its existing encryption key for your backup as well.

    //Use the same encryption key as the database
    EncryptionMode = EncryptionMode.UseDatabaseKey

    Both logical-backups and snapshots can use the same key as the database.

  • Using a key of your choice
    You can choose a key other than the database's to encrypt your logical-backup with.

    //Use an encryption key of your choice
    EncryptionMode = EncryptionMode.UseProvidedKey,
    Key = "OI7Vll7DroXdUORtc6Uo64wdAk1W0Db9ExXXgcg5IUs="

    Only a logical-backup can use an encryption-key different than the database's.

    Use this key when creating an encrypted backup of an unencrypted database.

Creating an Encrypted Backup

Creating an Encrypted Logical-Backup

Creating an encrypted logical-backup is nearly similar to creating a non-encrypted one.

  • In addition to the regular backup procedure, take these steps:

  • Code sample: encrypting a backup using the database encryption key.

    var config = new PeriodicBackupConfiguration
    {
        //additional settings here..
        //..
    
        //This is a 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);

  • Code sample: encrypting a backup with an encryption key of your choice -

    BackupEncryptionSettings = new BackupEncryptionSettings
    {
        //Use an encryption key of your choice
        EncryptionMode = EncryptionMode.UseProvidedKey,
        Key = "OI7Vll7DroXdUORtc6Uo64wdAk1W0Db9ExXXgcg5IUs="
    }

  • To create an unencrypted backup:

    • Either let the default setting (EncryptionMode = EncryptionMode.None) do the work for you, or -
    • Explicitly choose EncryptionMode.None.
      BackupEncryptionSettings = new BackupEncryptionSettings
      {
          //No encryption
          EncryptionMode = EncryptionMode.None
      }

You CAN encrypt the backup of an unencrypted database.

Pass the encryption key using EncryptionMode.UseProvidedKey.

//Use an encryption key of your choice
EncryptionMode = EncryptionMode.UseProvidedKey,
Key = "OI7Vll7DroXdUORtc6Uo64wdAk1W0Db9ExXXgcg5IUs="

Default encryption-key

If you don't explicitly state the encryption mode and key, their default value will be -

  • If the database is unencrypted, the backup is unencrypted as well.
  • If the database is encrypted, the backup is encrypted using the database's key.


Creating an Encrypted Snapshot

Default encryption-key

The snapshot of an encrypted database has the same encryption key as the database's.
The snapshot of an unencrypted database is not encrypted.

The incremental backups of an encrypted snapshot are encrypted as well, using the same key.

Restoring an Encrypted Backup

To restore your encrypted backup, pass RestoreBackupOperation the key used to encrypt it.
Pass the key using 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 a Logical-Backup

A database is restored from a logical-backup to its unencrypted form.
If you want to encrypt the restored database, you have to address it explicitly.

  • To encrypt the restored database:
    Pass RestoreBackupOperation an encryption key using restoreConfiguration.EncryptionKey.
    //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 -
  • Choose EncryptionMode.None Explicitly.
    restoreConfiguration.BackupEncryptionSettings = new BackupEncryptionSettings
    {
        //No encryption
        EncryptionMode = EncryptionMode.None
    };

Restoring a Snapshot

There are no special requirements to restoring snapshots.

  • The snapshot of an encrypted database is encrypted with the database's key.
  • The database of an encrypted snapshot is restored to its encrypted form.