Class/Module Index [+]

Quicksearch

Backup::Encryptor::GPG

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

First, setup defaults in your config.rb file

Configure the {keys} Hash using {.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['joe@example.com'] = <<-EOS
    # ...public key here...
  EOS
  encryptor.keys['mary@example.com'] = <<-EOS
    # ...public key here...
  EOS
end

The optional {gpg_config} and {gpg_homedir} options would also typically be set using {.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 joe@example.com

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 = 'joe@example.com'
  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 joe@example.com or mary@example.com, 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 = ['joe@example.com', 'mary@example.com']
  end
end

Constants

MODES

Attributes

gpg_config[RW]

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

@see gpg_homedir @return [String]

gpg_homedir[RW]

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.

@return [String]

keys[RW]

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['joe@example.com'] = <<-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['mary@example.com'] = <<-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 joe@example.com

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

@return [Hash]

mode[R]

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.

@param mode [String, Symbol] Sets the mode of operation.

(Defaults to +:asymmetric+)

@return [Symbol] mode that was set. @raise [Backup::Errors::Encryptor::GPG::InvalidModeError]

if mode given is invalid.
passphrase[RW]

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}.

@return [String]

passphrase_file[RW]

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

@return [String]

recipients[RW]

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 john.smith@example.com
pub   1024R/4E5E8D8A 2012-07-20
Key fingerprint = FFEA D1DB 201F B214 873E  7399 4A83 569F 4E5E 8D8A
uid                  John Smith <john.smith@example.com>
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 john.smith@example.com
pub   1024R/4A83569F4E5E8D8A 2012-07-20
uid                          John Smith <john.smith@example.com>
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 john.smith@example.com
pub   1024R/4E5E8D8A 2012-07-20
uid                  John Smith <john.smith@example.com>
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
      'mary.smith@example.com'
    ]
  end
end

@return [String, Array]

Public Class Methods

new(&block) click to toggle source

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 = ['joe@example.com', 'mary@example.com']
  end

  store_with SFTP

  notify_by Mail
end

@api private

# File lib/backup/encryptor/gpg.rb, line 401
def initialize(&block)
  super

  instance_eval(&block) if block_given?

  @mode ||= :asymmetric
end

Public Instance Methods

encrypt_with() click to toggle source

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.

@api private

# File lib/backup/encryptor/gpg.rb, line 419
def encrypt_with
  log!
  prepare

  if mode_options.empty?
    raise Error, "Encryption could not be performed for mode '#{ mode }'"
  end

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

ensure
  cleanup
end
key click to toggle source

@deprecated Use {keys} and {recipients}. @!attribute key

# 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|
mode=(mode) click to toggle source
# File lib/backup/encryptor/gpg.rb, line 104
def mode=(mode)
  @mode = mode.to_sym
  raise Error, "'#{ @mode }' is not a valid mode." unless MODES.include?(@mode)
end

[Validate]

Generated with the Darkfish Rdoc Generator 2.