Backup Encryption

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.

• Secure communication to enable database encryption.
  An encrypted database can only be created when the client-server communication is secure.

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
  }

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"

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);

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.