Class: Backup::Encryptor::GPG

Inherits:

Base

Object
Base
Backup::Encryptor::GPG

show all

Defined in:: lib/backup/encryptor/gpg.rb

Overview

The GPG Encryptor allows you to encrypt your final archive using GnuPG, using one of three modes of operation.

First, setup defaults in your `config.rb` file

Configure the #keys Hash using GPG.defaults in your config.rb to specify all valid #recipients and their Public Key.

Backup::Encryptor::GPG.defaults do |encryptor|
  # setup all GnuPG public keys
  encryptor.keys = {}
  encryptor.keys['[email protected]'] = <<-EOS
    # ...public key here...
  EOS
  encryptor.keys['[email protected]'] = <<-EOS
    # ...public key here...
  EOS
end

The optional #gpg_config and #gpg_homedir options would also typically be set using GPG.defaults in config.rb as well.

Then, setup each of your Models

Set the desired #recipients and/or #passphrase (or #passphrase_file) for each Model, depending on the #mode used.

my_backup_01

This archive can only be decrypted using the private key for [email protected]

Model.new(:my_backup_01, 'Backup Job #1') do
  # ... archives, databases, compressor and storage options, etc...
  encrypt_with GPG do |encryptor|
    encryptor.mode = :asymmetric
    encryptor.recipients = '[email protected]'
  end
end

my_backup_02

This archive can only be decrypted using the passphrase “a secret”.

Model.new(:my_backup_02, 'Backup Job #2') do
  # ... archives, databases, compressor and storage options, etc...
  encrypt_with GPG do |encryptor|
    encryptor.mode = :symmetric
    encryptor.passphrase = 'a secret'
  end
end

my_backup_03

This archive may be decrypted using either the private key for [email protected] or [email protected], and may also be decrypted using the passphrase.

Model.new(:my_backup_03, 'Backup Job #3') do
  # ... archives, databases, compressor and storage options, etc...
  encrypt_with GPG do |encryptor|
    encryptor.mode = :both
    encryptor.passphrase = 'a secret'
    encryptor.recipients = ['[email protected]', '[email protected]']
  end
end

Constant Summary collapse

MODES =

[:asymmetric, :symmetric, :both]

Constants included from CLI::Helpers

CLI::Helpers::UTILITY

Instance Attribute Summary collapse

#gpg_config ⇒ String

Specifies the GnuPG configuration to be used.
#gpg_homedir ⇒ String

Set the GnuPG home directory to be used.
#key ⇒ Object deprecated Deprecated.

Use #keys and #recipients.
#keys ⇒ Hash

Specifies a Hash of public key identifiers and their public keys.
#mode ⇒ Symbol

Sets the mode of operation.
#passphrase ⇒ String

Specifies the passphrase to use symmetric encryption.
#passphrase_file ⇒ String

Specifies the passphrase file to use symmetric encryption.
#recipients ⇒ String, Array

Specifies the recipients to use when encrypting the backup archive.

Class Method Summary collapse

.defaults {|config| ... } ⇒ Object

Configures default accessor values for new class instances.
.encrypt_with ⇒ Object private

This is called as part of the procedure run by the Packager.
.initialize(&block) ⇒ Object private

Creates a new instance of Backup::Encryptor::GPG.

Methods inherited from Base

#initialize

Methods included from Configuration::Helpers

included

Constructor Details

This class inherits a constructor from Backup::Encryptor::Base

Dynamic Method Handling

This class handles dynamic methods through the method_missing method in the class Backup::Configuration::Helpers

Instance Attribute Details

#gpg_config ⇒ `String`

Specifies the GnuPG configuration to be used.

This should be given as the text of a gpg.conf file. It will be written to a temporary file, which will be passed to the gpg command to use instead of the gpg.conf found in the GnuPG home directory. This allows you to be certain your preferences are used.

This is especially useful if you’ve also set #gpg_homedir and plan on allowing Backup to automatically create that directory and import all your public keys specified in #keys. In this situation, that folder would not contain any gpg.conf file, so GnuPG would simply use it’s defaults.

While this may be specified on a per-Model basis, you would generally just specify this in the defaults. Leading tabs/spaces are stripped before writing the given string to the temporary configuration file.

Backup::Encryptor::GPG.defaults do |enc|
  enc.gpg_config = <<-EOF
    # safely override preferences set in the receiver's public key(s)
    personal-cipher-preferences TWOFISH AES256 BLOWFISH AES192 CAST5 AES
    personal-digest-preferences SHA512 SHA256 SHA1 MD5
    personal-compress-preferences BZIP2 ZLIB ZIP Uncompressed
    # cipher algorithm for symmetric encryption
    # (if personal-cipher-preferences are not specified)
    s2k-cipher-algo TWOFISH
    # digest algorithm for mangling the symmetric encryption passphrase
    s2k-digest-algo SHA512
  EOF
end

Returns:

(String)

#gpg_homedir ⇒ `String`

Set the GnuPG home directory to be used.

This allows you to specify the GnuPG home directory on the system where Backup will be run, keeping the keyrings used by Backup separate from the default keyrings of the user running Backup. By default, this would be ‘~/.gnupg`.

If a directory is specified here, Backup will create it if needed and ensure the correct permissions are set. All public keys Backup imports would be added to the pubring.gpg file within this directory, and gpg would be given this directory using it’s --homedir option.

Any gpg.conf file located in this directory would also be used by gpg, unless #gpg_config is specified.

The given path will be expanded before use.

Returns:

(String)



164
165
166

# File 'lib/backup/encryptor/gpg.rb', line 164

def gpg_homedir
  @gpg_homedir
end

#key ⇒ `Object`

Deprecated.

Use #keys and #recipients.

# File 'lib/backup/encryptor/gpg.rb', line 222

attr_deprecate :key,
:version => '3.0.26',
:message => "This has been replaced with #keys and #recipients",
:action  => lambda {|klass, val|
  identifier = klass.send(:import_key, 'deprecated :key', val)
  klass.recipients = identifier
}

#keys ⇒ `Hash`

Specifies a Hash of public key identifiers and their public keys.

While not required, it is recommended that all public keys you intend to use be setup in #keys. The best place to do this is in your defaults in config.rb.

Backup::Encryptor::GPG.defaults do |enc|
  enc.keys = {}

  enc.keys['[email protected]'] = <<-EOS
    -----BEGIN PGP PUBLIC KEY BLOCK-----
    Version: GnuPG v1.4.12 (GNU/Linux)

    mQMqBEd5F8MRCACfArHCJFR6nkmxNiW+UE4PAW3bQla9JWFqCwu4VqLkPI/lHb5p
    xHff8Fzy2O89BxD/6hXSDx2SlVmAGHOCJhShx1vfNGVYNsJn2oNK50in9kGvD0+m
    [...]
    SkQEHOxhMiFjAN9q4LuirSOu65uR1bnTmF+Z92++qMIuEkH4/LnN
    =8gNa
    -----END PGP PUBLIC KEY BLOCK-----
  EOS

  enc.keys['[email protected]'] = <<-EOS
    -----BEGIN PGP PUBLIC KEY BLOCK-----
    Version: GnuPG v1.4.12 (GNU/Linux)

    2SlVmAGHOCJhShx1vfNGVYNxHff8Fzy2O89BxD/6in9kGvD0+mhXSDxsJn2oNK50
    kmxNiW+UmQMqBEd5F8MRCACfArHCJFR6qCwu4VqLkPI/lHb5pnE4PAW3bQla9JWF
    [...]
    AN9q4LSkQEHOxhMiFjuirSOu65u++qMIuEkH4/LnNR1bnTmF+Z92
    =8gNa
    -----END PGP PUBLIC KEY BLOCK-----

  EOS
end

All leading spaces/tabs will be stripped from the key, so the above form may be used to set each identifier’s key.

When a public key can not be found for an identifier specified in #recipients, the corresponding public key from this Hash will be imported into pubring.gpg in the GnuPG home directory (#gpg_homedir). Therefore, each key must be the same identifier used in #recipients.

To obtain the public key in ASCII format, use:

$ gpg -a --export [email protected]

See #recipients for information on what may be used as valid identifiers.

Returns:

(Hash)



217
218
219

# File 'lib/backup/encryptor/gpg.rb', line 217

def keys
  @keys
end

#mode ⇒ `Symbol`

Sets the mode of operation.

:asymmetric: In this mode, the final backup archive will be encrypted using the public key(s) specified by the key identifiers in #recipients. The archive may then be decrypted by anyone with a private key that corresponds to one of the public keys used. See #recipients and #keys for more information.
:symmetric: In this mode, the final backup archive will be encrypted using the passphrase specified by #passphrase or #passphrase_file. The archive will be encrypted using the encryption algorithm specified in your GnuPG configuration. See #gpg_config for more information. Anyone with the passphrase may decrypt the archive.
:both: In this mode, both :asymmetric and :symmetric options are used. Meaning that the archive may be decrypted by anyone with a valid private key or by using the proper passphrase.

Parameters:

mode (String, Symbol) —

Sets the mode of operation. (Defaults to :asymmetric)

Returns:

(Symbol) —

mode that was set.

Raises:

(Backup::Errors::Encryptor::GPG::InvalidModeError) —

if mode given is invalid.



102
103
104

# File 'lib/backup/encryptor/gpg.rb', line 102

def mode
  @mode
end

#passphrase ⇒ `String`

Specifies the passphrase to use symmetric encryption.

When #mode is :symmetric or :both, this passphrase will be used to symmetrically encrypt the archive.

Use of this option will override the use of #passphrase_file.

Returns:

(String)



308
309
310

# File 'lib/backup/encryptor/gpg.rb', line 308

def passphrase
  @passphrase
end

#passphrase_file ⇒ `String`

Specifies the passphrase file to use symmetric encryption.

When #mode is :symmetric or :both, this file will be passed to the gpg command line, where gpg will read the first line from this file and use it for the passphrase.

The file path given here will be expanded to a full path.

If #passphrase is specified, #passphrase_file will be ignored. Therefore, if you have set #passphrase in your global defaults, but wish to use #passphrase_file with a specific Model, be sure to clear #passphrase within that model’s configuration.

Backup::Encryptor::GPG.defaults do |enc|
  enc.passphrase = 'secret phrase'
end

Backup::Model.new(:my_backup, 'My Backup') do
  # other directives...
  encrypt_with GPG do |enc|
    enc.mode = :symmetric
    enc.passphrase = nil
    enc.passphrase_file = '/path/to/passphrase.file'
  end
end

Returns:

(String)



338
339
340

# File 'lib/backup/encryptor/gpg.rb', line 338

def passphrase_file
  @passphrase_file
end

#recipients ⇒ `String`, `Array`

Specifies the recipients to use when encrypting the backup archive.

When #mode is set to :asymmetric or :both, the public key for each recipient given here will be used to encrypt the archive. Each recipient will be able to decrypt the archive using their private key.

If there is only one recipient, this may be specified as a String. Otherwise, this should be an Array of Strings. Each String must be a valid public key identifier, and must be the same identifier used to specify the recipient’s public key in #keys. This is so that if a public key is not found for the given identifier, it may be imported from #keys.

Valid identifiers which may be used are as follows:

Key Fingerprint

The key fingerprint is a 40-character hex string, which uniquely identifies a public key. This may be obtained using the following:

$ gpg --fingerprint [email protected]
pub   1024R/4E5E8D8A 2012-07-20
Key fingerprint = FFEA D1DB 201F B214 873E  7399 4A83 569F 4E5E 8D8A
uid                  John Smith <[email protected]>
sub   1024R/92C8DFD8 2012-07-20

Long Key ID

The long Key ID is the last 16-characters of the key’s fingerprint.

The Long Key ID in this example is: 4A83569F4E5E8D8A

$ gpg --keyid-format long -k [email protected]
pub   1024R/4A83569F4E5E8D8A 2012-07-20
uid                          John Smith <[email protected]>
sub   1024R/662F18DB92C8DFD8 2012-07-20

Short Key ID

The short Key ID is the last 8-characters of the key’s fingerprint. This is the default key format seen when listing keys.

The Short Key ID in this example is: 4E5E8D8A

$ gpg -k [email protected]
pub   1024R/4E5E8D8A 2012-07-20
uid                  John Smith <[email protected]>
sub   1024R/92C8DFD8 2012-07-20

Email Address

This must exactly match an email address for one of the UID records associated with the recipient’s public key.

Recipient identifier forms may be mixed, as long as the identifier used here is the same as that used in #keys. Also, all spaces will be stripped from the identifier when used, so the following would be valid.

Backup::Model.new(:my_backup, 'My Backup') do
  encrypt_with GPG do |enc|
    enc.recipients = [
      # John Smith
      '4A83 569F 4E5E 8D8A',
      # Mary Smith
      '[email protected]'
    ]
  end
end

Returns:

(String, Array)



297
298
299

# File 'lib/backup/encryptor/gpg.rb', line 297

def recipients
  @recipients
end

Class Method Details

.defaults {|config| ... } ⇒ `Object`

Configures default accessor values for new class instances.

If all required options are set, then no further configuration would be needed within a Model’s definition when an Encryptor is added. Therefore, the following example is sufficient to encrypt :my_backup:

# Defaults set in config.rb
Backup::Encryptor::GPG.defaults do |encryptor|
  encryptor.keys = {}
  encryptor.keys['[email protected]'] = <<-EOS
    -----BEGIN PGP PUBLIC KEY BLOCK-----
    Version: GnuPG v1.4.12 (GNU/Linux)

    mI0EUBR6CwEEAMVSlFtAXO4jXYnVFAWy6chyaMw+gXOFKlWojNXOOKmE3SujdLKh
    kWqnafx7VNrb8cjqxz6VZbumN9UgerFpusM3uLCYHnwyv/rGMf4cdiuX7gGltwGb
    (...etc...)
    mLekS3xntUhhgHKc4lhf4IVBqG4cFmwSZ0tZEJJUSESb3TqkkdnNLjE=
    =KEW+
    -----END PGP PUBLIC KEY BLOCK-----
  EOS

  encryptor.recipients = '[email protected]'
end

# Encryptor set in the model
Backup::Model.new(:my_backup, 'My Backup') do
  # archives, storage options, etc...
  encrypt_with GPG
end

Yields:

(config) —

OpenStruct object

.encrypt_with ⇒ `Object`

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

This is called as part of the procedure run by the Packager. It sets up the needed options to pass to the gpg command, then yields the command to use as part of the packaging procedure. Once the packaging procedure is complete, it will return so that any clean-up may be performed after the yield. Cleanup is also ensured, as temporary files may hold sensitive data. If no options can be built, the packaging process will be aborted.

# File 'lib/backup/encryptor/gpg.rb', line 419

def encrypt_with
  log!
  prepare

  if mode_options.empty?
    raise Errors::Encryptor::GPG::EncryptionError,
        "Encryption could not be performed for mode '#{ mode }'"
  end

  yield "#{ utility(:gpg) } #{ base_options } #{ mode_options }", '.gpg'

ensure
  cleanup
end

.initialize(&block) ⇒ `Object`

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Creates a new instance of Backup::Encryptor::GPG.

This constructor is not used directly when configuring Backup. Use Model#encrypt_with.

Model.new(:backup_trigger, 'Backup Label') do
  archive :my_archive do |archive|
    archive.add '/some/directory'
  end

  compress_with Gzip

  encrypt_with GPG do |encryptor|
    encryptor.mode = :both
    encryptor.passphrase = 'a secret'
    encryptor.recipients = ['[email protected]', '[email protected]']
  end

  store_with SFTP

  notify_by Mail
end

# File 'lib/backup/encryptor/gpg.rb', line 401

def initialize(&block)
  super

  instance_eval(&block) if block_given?

  @mode ||= :asymmetric
end

Class: Backup::Encryptor::GPG

Overview

First, setup defaults in your config.rb file

Then, setup each of your Models

my_backup_01

my_backup_02

my_backup_03

Constant Summary collapse

Constants included from CLI::Helpers

Instance Attribute Summary collapse

Class Method Summary collapse

Methods inherited from Base

Methods included from Configuration::Helpers

Constructor Details

Dynamic Method Handling

Instance Attribute Details

#gpg_config ⇒ String

#gpg_homedir ⇒ String

#key ⇒ Object

#keys ⇒ Hash

#mode ⇒ Symbol

#passphrase ⇒ String

#passphrase_file ⇒ String

#recipients ⇒ String, Array

Class Method Details

.defaults {|config| ... } ⇒ Object

.encrypt_with ⇒ Object

.initialize(&block) ⇒ Object

First, setup defaults in your `config.rb` file

#gpg_config ⇒ `String`

#gpg_homedir ⇒ `String`

#key ⇒ `Object`

#keys ⇒ `Hash`

#mode ⇒ `Symbol`

#passphrase ⇒ `String`

#passphrase_file ⇒ `String`

#recipients ⇒ `String`, `Array`

.defaults {|config| ... } ⇒ `Object`

.encrypt_with ⇒ `Object`

.initialize(&block) ⇒ `Object`