sliday_backup 0.1

data/lib/sliday_backup/encryptor/base.rb

@@ -0,0 +1,29 @@
+# encoding: utf-8
+
+module SlidayBackup
+  module Encryptor
+    class Base
+      include Utilities::Helpers
+      include Config::Helpers
+
+      def initialize
+        load_defaults!
+      end
+
+      private
+
+      ##
+      # Return the encryptor name, with SlidayBackup namespace removed
+      def encryptor_name
+        self.class.to_s.sub('SlidayBackup::', '')
+      end
+
+      ##
+      # Logs a message to the console and log file to inform
+      # the client that SlidayBackup is encrypting the archive
+      def log!
+        Logger.info "Using #{ encryptor_name } to encrypt the archive."
+      end
+    end
+  end
+end

data/lib/sliday_backup/encryptor/gpg.rb

@@ -0,0 +1,747 @@
+# encoding: utf-8
+
+module SlidayBackup
+  module Encryptor
+    ##
+    # 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.
+    #
+    #   SlidayBackup::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, 'SlidayBackup 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, 'SlidayBackup 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, 'SlidayBackup 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
+    #
+    class GPG < Base
+      class Error < SlidayBackup::Error; end
+
+      MODES = [:asymmetric, :symmetric, :both]
+
+      ##
+      # 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 [SlidayBackup::Errors::Encryptor::GPG::InvalidModeError]
+      #   if mode given is invalid.
+      #
+      attr_reader :mode
+      def mode=(mode)
+        @mode = mode.to_sym
+        raise Error, "'#{ @mode }' is not a valid mode." unless MODES.include?(@mode)
+      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 SlidayBackup 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.
+      #
+      #   SlidayBackup::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]
+      attr_accessor :gpg_config
+
+      ##
+      # Set the GnuPG home directory to be used.
+      #
+      # This allows you to specify the GnuPG home directory on the system
+      # where SlidayBackup will be run, keeping the keyrings used by SlidayBackup separate
+      # from the default keyrings of the user running SlidayBackup.
+      # By default, this would be +`~/.gnupg`+.
+      #
+      # If a directory is specified here, SlidayBackup will create it if needed
+      # and ensure the correct permissions are set. All public keys SlidayBackup
+      # 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]
+      attr_accessor :gpg_homedir
+
+      ##
+      # 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+.
+      #
+      #   SlidayBackup::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]
+      attr_accessor :keys
+
+      ##
+      # 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.
+      #
+      #   SlidayBackup::Model.new(:my_backup, 'My SlidayBackup') 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]
+      attr_accessor :recipients
+
+      ##
+      # 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]
+      attr_accessor :passphrase
+
+      ##
+      # 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.
+      #
+      #   SlidayBackup::Encryptor::GPG.defaults do |enc|
+      #     enc.passphrase = 'secret phrase'
+      #   end
+      #
+      #   SlidayBackup::Model.new(:my_backup, 'My SlidayBackup') 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]
+      attr_accessor :passphrase_file
+
+      ##
+      # 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
+      #   SlidayBackup::Encryptor::GPG.defaults do |encryptor|
+      #     encryptor.keys = {}
+      #     encryptor.keys['joe@example.com'] = <<-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 = 'joe@example.com'
+      #   end
+      #
+      #   # Encryptor set in the model
+      #   SlidayBackup::Model.new(:my_backup, 'My SlidayBackup') do
+      #     # archives, storage options, etc...
+      #     encrypt_with GPG
+      #   end
+      #
+      # @!scope class
+      # @see Config::Helpers::ClassMethods#defaults
+      # @yield [config] OpenStruct object
+      # @!method defaults
+
+      ##
+      # Creates a new instance of SlidayBackup::Encryptor::GPG.
+      #
+      # This constructor is not used directly when configuring SlidayBackup.
+      # Use {Model#encrypt_with}.
+      #
+      #   Model.new(:backup_trigger, 'SlidayBackup 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
+      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
+      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
+
+      private
+
+      ##
+      # Remove any temporary directories and reset all instance variables.
+      #
+      def prepare
+        FileUtils.rm_rf(@tempdirs, :secure => true) if @tempdirs
+        @tempdirs = []
+        @base_options = nil
+        @mode_options = nil
+        @user_recipients = nil
+        @user_keys = nil
+        @system_identifiers = nil
+      end
+      alias :cleanup :prepare
+
+      ##
+      # Returns the options needed for the gpg command line which are
+      # not dependant on the #mode. --no-tty supresses output of certain
+      # messages, like the "Reading passphrase from file descriptor..."
+      # messages during symmetric encryption
+      #
+      def base_options
+        @base_options ||= begin
+          opts = ['--no-tty']
+          path = setup_gpg_homedir
+          opts << "--homedir '#{ path }'" if path
+          path = setup_gpg_config
+          opts << "--options '#{ path }'" if path
+          opts.join(' ')
+        end
+      end
+
+      ##
+      # Setup the given :gpg_homedir if needed, ensure the proper permissions
+      # are set, and return the directory's path. Otherwise, return false.
+      #
+      # If the GnuPG files do not exist, trigger their creation by requesting
+      # --list-secret-keys. Some commands, like for symmetric encryption, will
+      # issue messages about their creation on STDERR, which generates unwanted
+      # warnings in the log. This way, if any of these files are created here,
+      # we will get those messages on STDOUT for the log, without the actual
+      # secret key listing which we don't care about.
+      #
+      def setup_gpg_homedir
+        return false unless gpg_homedir
+
+        path = File.expand_path(gpg_homedir)
+        FileUtils.mkdir_p(path)
+        FileUtils.chown(Config.user, nil, path)
+        FileUtils.chmod(0700, path)
+
+        unless %w{ pubring.gpg secring.gpg trustdb.gpg }.
+            all? {|name| File.exist? File.join(path, name) }
+          run("#{ utility(:gpg) } --homedir '#{ path }' -K 2>&1 >/dev/null")
+        end
+
+        path
+
+      rescue => err
+        raise Error.wrap(
+            err, "Failed to create or set permissions for #gpg_homedir")
+      end
+
+      ##
+      # Write the given #gpg_config to a tempfile, within a tempdir, and
+      # return the file's path to be given to the gpg --options argument.
+      # If no #gpg_config is set, return false.
+      #
+      # This is required in order to set the proper permissions on the
+      # directory containing the tempfile. The tempdir will be removed
+      # after the packaging procedure is completed.
+      #
+      # Once written, we'll call check_gpg_config to make sure there are
+      # no problems that would prevent gpg from running with this config.
+      # If any errors occur during this process, we can not proceed.
+      # We'll cleanup to remove the tempdir (if created) and raise an error.
+      #
+      def setup_gpg_config
+        return false unless gpg_config
+
+        dir = Dir.mktmpdir('backup-gpg_config', Config.tmp_path)
+        @tempdirs << dir
+        file = Tempfile.open('backup-gpg_config', dir)
+        file.write gpg_config.gsub(/^[[:blank:]]+/, '')
+        file.close
+
+        check_gpg_config(file.path)
+
+        file.path
+
+      rescue => err
+        cleanup
+        raise Error.wrap(err, "Error creating temporary file for #gpg_config.")
+      end
+
+      ##
+      # Make sure the temporary GnuPG config file created from #gpg_config
+      # does not have any syntax errors that would prevent gpg from running.
+      # If so, raise the returned error message.
+      # Note that Cli::Helpers#run may also raise an error here.
+      #
+      def check_gpg_config(path)
+        ret = run(
+          "#{ utility(:gpg) } --options '#{ path }' --gpgconf-test 2>&1"
+        ).chomp
+        raise ret unless ret.empty?
+      end
+
+      ##
+      # Returns the options needed for the gpg command line to perform
+      # the encryption based on the #mode.
+      #
+      def mode_options
+        @mode_options ||= begin
+          s_opts = symmetric_options if mode != :asymmetric
+          a_opts = asymmetric_options if mode != :symmetric
+          [s_opts, a_opts].compact.join(' ')
+        end
+      end
+
+      ##
+      # Process :passphrase or :passphrase_file and return the command line
+      # options to perform symmetric encryption. If no :passphrase is
+      # specified, or an error occurs creating a temporary file for it, then
+      # try to use :passphrase_file if it's set.
+      # If the option can not be set, log a warning and return nil.
+      #
+      def symmetric_options
+        path = setup_passphrase_file
+        unless path || passphrase_file.to_s.empty?
+          path = File.expand_path(passphrase_file.to_s)
+        end
+
+        if path && File.exist?(path)
+          "-c --passphrase-file '#{ path }'"
+        else
+          Logger.warn("Symmetric encryption options could not be set.")
+          nil
+        end
+      end
+
+      ##
+      # Create a temporary file, within a tempdir, to hold the :passphrase and
+      # return the file's path. If an error occurs, log a warning.
+      # Return false if no :passphrase is set or an error occurs.
+      #
+      def setup_passphrase_file
+        return false if passphrase.to_s.empty?
+
+        dir = Dir.mktmpdir('backup-gpg_passphrase', Config.tmp_path)
+        @tempdirs << dir
+        file = Tempfile.open('backup-gpg_passphrase', dir)
+        file.write passphrase.to_s
+        file.close
+
+        file.path
+
+      rescue => err
+        Logger.warn Error.wrap(err, "Error creating temporary passphrase file.")
+        false
+      end
+
+      ##
+      # Process :recipients, importing their public key from :keys if needed,
+      # and return the command line options to perform asymmetric encryption.
+      # Log a warning and return nil if no valid recipients are found.
+      #
+      def asymmetric_options
+        if user_recipients.empty?
+          Logger.warn "No recipients available for asymmetric encryption."
+          nil
+        else
+          # skip trust database checks
+          "-e --trust-model always " +
+              user_recipients.map {|r| "-r '#{ r }'" }.join(' ')
+        end
+      end
+
+      ##
+      # Returns an Array of the public key identifiers the user specified
+      # in :recipients. Each identifier is 'cleaned' so that exact matches
+      # can be performed. Then each is checked to ensure it will find a
+      # public key that exists in the system's public keyring.
+      # If the identifier does not match an existing key, the public key
+      # associated with the identifier in :keys will be imported for use.
+      # If no key can be found in the system or in :keys for the identifier,
+      # a warning will be issued; as we will attempt to encrypt the backup
+      # and proceed if at all possible.
+      #
+      def user_recipients
+        @user_recipients ||= begin
+          [recipients].flatten.compact.map do |identifier|
+            identifier = clean_identifier(identifier)
+            if system_identifiers.include?(identifier)
+              identifier
+            else
+              key = user_keys[identifier]
+              if key
+                # will log a warning and return nil if the import fails
+                import_key(identifier, key)
+              else
+                Logger.warn(
+                  "No public key was found in #keys for '#{ identifier }'"
+                )
+                nil
+              end
+            end
+          end.compact
+        end
+      end
+
+      ##
+      # Returns the #keys hash set by the user with all identifiers
+      # (Hash keys) 'cleaned' for exact matching. If the cleaning process
+      # creates duplicate keys, the user will be warned.
+      #
+      def user_keys
+        @user_keys ||= begin
+          _keys = keys || {}
+          ret = Hash[_keys.map {|k,v| [clean_identifier(k), v] }]
+          Logger.warn(
+            "Duplicate public key identifiers were detected in #keys."
+          ) if ret.keys.count != _keys.keys.count
+          ret
+        end
+      end
+
+      ##
+      # Cleans a public key identifier.
+      # Strip out all spaces, upcase non-email identifiers,
+      # and wrap email addresses in <> to perform exact matching.
+      #
+      def clean_identifier(str)
+        str = str.to_s.gsub(/[[:blank:]]+/, '')
+        str =~ /@/ ? "<#{ str.gsub(/(<|>)/,'') }>" : str.upcase
+      end
+
+      ##
+      # Import the given public key and return the 16 character Key ID.
+      # If the import fails, return nil.
+      # Note that errors raised by Cli::Helpers#run may also be rescued here.
+      #
+      def import_key(identifier, key)
+        file = Tempfile.open('backup-gpg_import', Config.tmp_path)
+        file.write(key.gsub(/^[[:blank:]]+/, ''))
+        file.close
+        ret = run(
+          "#{ utility(:gpg) } #{ base_options } " +
+          "--keyid-format 0xlong --import '#{ file.path }' 2>&1"
+        )
+        file.delete
+
+        keyid = ret.match(/ 0x(\w{16})/).to_a[1]
+        raise "GPG Returned:\n#{ ret.gsub(/^\s*/, '  ') }" unless keyid
+        keyid
+
+      rescue => err
+        Logger.warn Error.wrap(
+            err, "Public key import failed for '#{ identifier }'")
+        nil
+      end
+
+      ##
+      # Parse the information for all the public keys found in the public
+      # keyring (based on #gpg_homedir setting) and return an Array of all
+      # identifiers which could be used to specify a valid key.
+      #
+      def system_identifiers
+        @system_identifiers ||= begin
+          skip_key = false
+          data = run(
+            "#{ utility(:gpg) } #{ base_options } " +
+            "--with-colons --fixed-list-mode --fingerprint"
+          )
+          data.lines.map do |line|
+            line.strip!
+
+            # process public key record
+            if line =~ /^pub:/
+              validity, keyid, capabilities =
+                  line.split(':').values_at(1, 4, 11)
+              # skip keys marked as revoked ('r'), expired ('e'),
+              # invalid ('i') or disabled ('D')
+              if validity[0,1] =~ /(r|e|i)/ || capabilities =~ /D/
+                skip_key = true
+                next nil
+              else
+                skip_key = false
+                # return both the long and short id
+                next [keyid[-8..-1], keyid]
+              end
+            else
+              # wait for the next valid public key record
+              next nil if skip_key
+
+              # process UID records for the current public key
+              if line =~ /^uid:/
+                validity, userid = line.split(':').values_at(1, 9)
+                # skip records marked as revoked ('r'), expired ('e')
+                # or invalid ('i')
+                if validity !~ /(r|e|i)/
+                  # return the last email found in user id string,
+                  # since this includes user supplied comments.
+                  # return nil if no email found.
+                  email, str = nil, userid
+                  while match = str.match(/<.+?@.+?>/)
+                    email, str = match[0], match.post_match
+                  end
+                  next email
+                end
+              # return public key's fingerprint
+              elsif line =~ /^fpr:/
+                next line.split(':')[9]
+              end
+
+              nil # ignore any other lines
+            end
+          end.flatten.compact
+        end
+      end
+
+    end
+  end
+end