Encryptors

Encryptors

Currently supported encryptors:

• OpenSSL
• GPG

Examples

The following examples should be placed in your Backup configuration file.

Model.new(:my_backup, 'My Backup') do
  # examples go here...
end

OpenSSL

Create a password-protected backup file with my_password as the password.

encrypt_with OpenSSL do |encryption|
  encryption.password = 'my_password'
  encryption.base64   = true
  encryption.salt     = true
end

Or if you prefer to read the password from a file on the filesystem:

encrypt_with OpenSSL do |encryption|
  encryption.password_file = '/path/to/password/file'
  encryption.base64        = true
  encryption.salt          = true
end

This will encrypt your backup file using OpenSSL. Ensure OpenSSL is installed on your machine. It usually is by default. Additional options you can set are the encryption.base64 and encryption.salt, both are booleans. encryption.base64 makes encrypted backups readable in text editors, emails, etc. encryption.salt (enabled by default) improves the security. OpenSSL encrypts the backups using the 256bit AES encryption cipher.

Decrypting OpenSSL

To decrypt an OpenSSL encrypted backup file, "Backup" provides a CLI command for doing so.

$ backup decrypt --encryptor openssl --base64 --salt --password-file <path/to/password/file> \
    --in <encrypted_file> --out <decrypted_file>

If you set the encryption.base64 to false, then don't use the --base64 flag when decrypting. Once you run this command you will be prompted for the password you specified in the Backup configuration file. When you fill in the correct password, the backup file will be decrypted to the location you specified with the --out option. You can also use --password-file to provide the password.

GPG

To use GPG you need to have a GPG encryption (public, private) key pair.

To generate a new GPG key to use with the Backup gem, issue the following command:

$ gpg --gen-key

And follow the instructions. Usually the defaults are fine. Once the keys have been generated you may issue the following commands to confirm they were successfully created.

$ gpg --list-keys
$ gpg --list-secret-keys

If you see your keys in the list, it means it successfully generated the keys. Be sure to store your private key in a safe place, otherwise you will not be able to decrypt your backups.

Now, in order to get the long (public) key which you need to paste in to the Backup configuration file, issue the following command:

$ gpg -a --export [EMAIL]

EMAIL being the email you specified when generating the keys.

Now copy/paste the key into the Backup configuration file, making sure to assign the key to the email address you used to create the key, and specify that email address as the recipient.

encrypt_with GPG do |encryption|
  encryption.keys = {}
  encryption.keys['joe@example.com'] = <<-KEY
    -----BEGIN PGP PUBLIC KEY BLOCK-----
    Version: GnuPG v1.4.11 (Darwin)

        [ Your GPG Public Key Here ]
    -----END PGP PUBLIC KEY BLOCK-----
  KEY
  encryption.recipients = 'joe@example.com'
end

The above is a simple example of using the GPG Encryptor to asymmetrically encrypt your backup using a single GPG public/private keypair. However, it also supports multiple recipients, as well as symmetric encryption or a combination of both. For example, the following backup could be decrypted using either user's private key or the passphrase:

encrypt_with GPG do |encryption|
  encryption.keys = {}
  encryption.keys['joe@example.com'] = <<-KEY
    -----BEGIN PGP PUBLIC KEY BLOCK-----
    Version: GnuPG v1.4.11 (Darwin)

        [ Joe's GPG Public Key Here ]
    -----END PGP PUBLIC KEY BLOCK-----
  KEY
  encryption.keys['mary@example.com'] = <<-KEY
    -----BEGIN PGP PUBLIC KEY BLOCK-----
    Version: GnuPG v1.4.11 (Darwin)

        [ Mary's GPG Public Key Here ]
    -----END PGP PUBLIC KEY BLOCK-----
  KEY
  encryption.recipients = ['joe@example.com', 'mary@example.com']
  encryption.passphrase = 'secret passphrase'
  encryption.mode = :both
end

Other advanced options are also available. For more detailed instructions, see the documentation in the encryptor in lib/backup/encryptor/gpg.rb or online at http://rubydoc.info/gems/backup/Backup/Encryptor/GPG

Decrypting GPG

Assuming you still have your GPG keys on your machine and want to decrypt a backup file, you can do so by issuing the following command:

$ backup decrypt --encryptor gpg --in <encrypted_file> --out <decrypted_file>

You will then be prompted for your password (the password you specified when generating your gpg keys). If you fill in the password correctly, the target backup will be decrypted to the path specified with the --out option.

Note

Only one Encryptor may be configured for each Model.

Also, note that adding an Encryptor will result in the final backup archive being encrypted before it is split (if split). See the Technical Overview for details.

Default Configuration

If you are planning to encrypt multiple backups, especially with GPG, your configuration file may become extremely verbose and long. If you are using the same GPG key(s) to encrypt multiple backups, it is a good idea to setup all the GPG keys you will be using in Backup's default configuration.

Encryptor::GPG.defaults do |encryption|
  encryption.keys = {}

  encryption.keys['joe@example.com'] = <<-KEY
    -----BEGIN PGP PUBLIC KEY BLOCK-----
    Version: GnuPG v1.4.11 (Darwin)

    [ Joe's GPG Public Key Here ]
    -----END PGP PUBLIC KEY BLOCK-----
  KEY

  encryption.keys['mary@example.com'] = <<-KEY
    -----BEGIN PGP PUBLIC KEY BLOCK-----
    Version: GnuPG v1.4.12 (GNU/Linux)

    [ Mary's GPG Public Key Here ]
    -----END PGP PUBLIC KEY BLOCK-----
  KEY

  # Specify the default recipients for all backups (optional)
  encryption.recipients = ['joe@example.com', 'mary@example.com']
end

So now, every time you wish to encrypt a backup with GPG and the above GPG keys, all you have to add in to your configuration file is the following:

encrypt_with GPG

Or, you can override the default recipients to use specific GPG keys:

encrypt_with GPG do |encryption|
  encryption.recipients = 'mary@example.com'

  # To add recipients to defaults, set your defaults as an Array:
  #   encryption.recipients = ['admin@example.com']
  # Then use:
  #   encryption.recipients += ['mary@example.com', 'support@email.com']

end

You can set defaults for OpenSSL by using:

Encryptor::OpenSSL.defaults do |encryption|
  encryption.password = 'default_password'
  encryption.base64   = true
  encryption.salt     = true
end