Class | Backup::Encryptor::GPG |
In: |
lib/backup/encryptor/gpg.rb
|
Parent: | Base |
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
MODES | = | [:asymmetric, :symmetric, :both] |
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.
@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:
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
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