The GPG Encryptor allows you to encrypt your final archive using GnuPG, using one of three {mode modes} of operation.
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.
Set the desired {recipients} and/or {passphrase} (or {passphrase_file}) for each {Model}, depending on the {mode} used.
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
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
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
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]
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]
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]
Sets the mode of operation.
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.
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.
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.
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]
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]
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:
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
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
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
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]
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
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
@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|
Generated with the Darkfish Rdoc Generator 2.