iostreams 1.11.0 → 2.1.0

data/lib/io_streams/pgp/reader.rb

@@ -3,6 +3,10 @@ require "open3"
 module IOStreams
   module Pgp
     class Reader < IOStreams::Reader
+      def self.option_names
+        %i[passphrase ignore_mdc_error verify_first]
+      end
+
       # Passphrase to use to open the private key to decrypt the received file
       class << self
         attr_writer :default_passphrase
@@ -16,27 +20,59 @@ module IOStreams
 
       # Read from a PGP / GPG file , decompressing the contents as it is read.
       #
+      # SECURITY WARNING:
+      #   By default the decrypted contents are passed to the block as gpg decrypts them,
+      #   before gpg has checked the file's integrity (MDC) and any signature, since those are
+      #   only known once the whole file has been read. When either check fails,
+      #   `IOStreams::Pgp::Failure` is raised after the block has processed the data.
+      #   Do not commit any side effects, such as database updates, until the block returns
+      #   without raising, for example by processing the file within a database transaction.
+      #   Otherwise supply `verify_first: true`.
+      #
       # file_name: [String]
       #   Name of file to read from
       #
       # passphrase: [String]
-      #   Pass phrase for private key to decrypt the file with
-      def self.file(file_name, passphrase: nil)
+      #   Pass phrase for private key to decrypt the file with.
+      #   Not required when the file is signed but not encrypted.
+      #
+      # ignore_mdc_error: [true|false]
+      #   Decrypt files that lack MDC (Modification Detection Code) integrity protection.
+      #   Some legacy/enterprise systems (e.g. Workday) still produce such files, which
+      #   modern GnuPG refuses to decrypt with `gpg: decryption forced to fail!`.
+      #   Only enable this for files from a trusted source: without MDC the decrypted
+      #   contents are not protected against tampering.
+      #   Default: false
+      #
+      # verify_first: [true|false]
+      #   Decrypt the whole file into a temporary file, only readable by the current user,
+      #   and only pass its contents to the block once gpg has checked the file's integrity
+      #   and any signature.
+      #   Requires local disk space for the decrypted contents, which are deleted afterwards,
+      #   and an extra pass over the data.
+      #   Default: false
+      def self.file(file_name, passphrase: nil, ignore_mdc_error: false, verify_first: false, &)
         # Cannot use `passphrase: self.default_passphrase` since it is considered private
         passphrase ||= default_passphrase
-        raise(ArgumentError, "Missing both passphrase and IOStreams::Pgp::Reader.default_passphrase") unless passphrase
 
+        args = []
         # Use --pinentry-mode loopback for all GnuPG versions >= 2.1
-        loopback = IOStreams::Pgp.pgp_version.to_f >= 2.1 ? "--pinentry-mode loopback" : ""
-
+        args += ["--pinentry-mode", "loopback"] if IOStreams::Pgp.pgp_version.to_f >= 2.1
         # Use --no-symkey-cache for GnuPG versions >= 2.4 to avoid caching session keys
-        no_symkey_cache = IOStreams::Pgp.pgp_version.to_f >= 2.4 ? "--no-symkey-cache" : ""
+        args << "--no-symkey-cache" if IOStreams::Pgp.pgp_version.to_f >= 2.4
+        args << "--ignore-mdc-error" if ignore_mdc_error
+        args += ["--batch", "--no-tty", "--yes", "--decrypt"]
+        # Only feed a passphrase when one is supplied; sign-only files need none.
+        args += ["--passphrase-fd", "0"] if passphrase
+        args += ["--", file_name.to_s]
 
-        command  = "#{IOStreams::Pgp.executable} #{loopback} #{no_symkey_cache} --batch --no-tty --yes --decrypt --passphrase-fd 0 #{file_name}"
-        IOStreams::Pgp.logger&.debug { "IOStreams::Pgp::Reader.open: #{command}" }
+        command = IOStreams::Pgp.gpg_command(*args)
+        IOStreams.logger&.debug { "IOStreams::Pgp::Reader.open: #{command.shelljoin}" }
+
+        return decrypt_then_read(command, file_name, passphrase, &) if verify_first
 
         # Read decrypted contents from stdout
-        Open3.popen3(command) do |stdin, stdout, stderr, waith_thr|
+        Open3.popen3(*command) do |stdin, stdout, stderr, waith_thr|
           stdin.puts(passphrase) if passphrase
           stdin.close
           result =
@@ -52,6 +88,23 @@ module IOStreams
           result
         end
       end
+
+      # Decrypts the file into a temporary file, and only yields it once gpg has succeeded.
+      def self.decrypt_then_read(command, file_name, passphrase, &block)
+        Utils.private_temp_file("iostreams_pgp") do |temp_file_name|
+          Open3.popen3(*command) do |stdin, stdout, stderr, waith_thr|
+            stdin.puts(passphrase) if passphrase
+            stdin.close
+            ::File.open(temp_file_name, "wb") { |io| ::IO.copy_stream(stdout, io) }
+            unless waith_thr.value.success?
+              raise(Pgp::Failure, "GPG Failed to decrypt file: #{file_name}: #{stderr.read.chomp}")
+            end
+          end
+
+          ::File.open(temp_file_name, "rb", &block)
+        end
+      end
+      private_class_method :decrypt_then_read
     end
   end
-end
+end

data/lib/io_streams/pgp/writer.rb

@@ -3,6 +3,14 @@ require "open3"
 module IOStreams
   module Pgp
     class Writer < IOStreams::Writer
+      # File descriptor in the gpg process that the signer passphrase is read from.
+      PASSPHRASE_FD = 3
+
+      def self.option_names
+        %i[encrypt recipient import_and_trust_key import_and_trust_level signer signer_passphrase
+           compress compress_level]
+      end
+
       class << self
         # Sign all encrypted files with this users key.
         # Default: Do not sign encrypted files.
@@ -26,18 +34,42 @@ module IOStreams
         @audit_recipient           = nil
       end
 
-      # Write to a PGP / GPG file, encrypting the contents as it is written.
+      # Write to a PGP / GPG file, encrypting and/or signing the contents as it is written.
       #
       # file_name: [String]
       #   Name of file to write to.
       #
+      # encrypt: [true|false]
+      #   Whether to encrypt the file for the supplied recipient(s).
+      #   When set to false the file is signed but not encrypted, in which case a
+      #   :signer must be supplied and :recipient / :import_and_trust_key are ignored.
+      #   Default: true
+      #
       # recipient: [String|Array<String>]
       #   One or more emails of users for which to encrypt the file.
+      #   Ignored when encrypt is false.
       #
       # import_and_trust_key: [String|Array<String>]
       #   One or more pgp keys to import and then use to encrypt the file.
       #   Note: Ascii Keys can contain multiple keys, only the last one in the file is used.
       #
+      # import_and_trust_level: [Integer]
+      #   The owner-trust level to assign to keys supplied via :import_and_trust_key.
+      #     1 : Undefined  (no opinion)
+      #     2 : Never      (do not trust)
+      #     3 : Marginal
+      #     4 : Full
+      #     5 : Ultimate
+      #   Default: 5 : Ultimate
+      #
+      #   SECURITY WARNING:
+      #     Only import and trust keys received from a verified, trusted source.
+      #     The default trust level is `5` (Ultimate), which tells GPG to treat the imported key
+      #     as if it were one of your own keys. An ultimately trusted key is implicitly valid and
+      #     can in turn confer validity on other keys it has signed. Importing an attacker supplied
+      #     key at this level allows that attacker to impersonate other recipients.
+      #     When the key cannot be fully verified, supply a lower `import_and_trust_level`.
+      #
       # signer: [String]
       #   Name of user with which to sign the encypted file.
       #   Default: default_signer or do not sign.
@@ -55,63 +87,112 @@ module IOStreams
       # compress_level: [Integer]
       #   Compression level
       #   Default: 6
+      #
+      # Note: There is intentionally no option here to disable MDC (Modification Detection
+      # Code) integrity protection on the files we produce. The reader exposes
+      # `ignore_mdc_error:` so we can *consume* legacy files that lack MDC (see Reader),
+      # but we never want to *generate* them: MDC is what protects the encrypted contents
+      # against tampering, and modern GnuPG mandates it for current ciphers anyway
+      # (`--disable-mdc` is a no-op unless an obsolete cipher is forced). Omitting MDC on
+      # output would only weaken files we create, with no upside for this library.
       def self.file(file_name,
+                    encrypt: true,
                     recipient: nil,
                     import_and_trust_key: nil,
+                    import_and_trust_level: 5,
                     signer: default_signer,
                     signer_passphrase: default_signer_passphrase,
                     compress: :zip,
-                    compression: nil, # Deprecated
-                    compress_level: 6,
-                    original_file_name: nil)
-
-        raise(ArgumentError, "Requires either :recipient or :import_and_trust_key") unless recipient || import_and_trust_key
-
-        # Backward compatibility
-        compress = compression if compression
+                    compress_level: 6)
+        if encrypt
+          raise(ArgumentError, "Requires either :recipient or :import_and_trust_key") unless recipient || import_and_trust_key
+        elsif !signer
+          raise(ArgumentError, "Requires a :signer when encrypt is false")
+        end
 
         compress_level = 0 if compress == :none
 
-        recipients = Array(recipient)
-        recipients << audit_recipient if audit_recipient
+        recipients =
+          if encrypt
+            collect_recipients(recipient, import_and_trust_key, import_and_trust_level)
+          else
+            []
+          end
 
-        Array(import_and_trust_key).each do |key|
-          recipients << IOStreams::Pgp.import_and_trust(key: key)
-        end
+        # Write to stdin, with the encrypted and/or signed contents being written to the file
+        args = build_args(
+          file_name:         file_name,
+          encrypt:           encrypt,
+          signer:            signer,
+          signer_passphrase: signer_passphrase,
+          compress:          compress,
+          compress_level:    compress_level,
+          recipients:        recipients
+        )
+        command = IOStreams::Pgp.gpg_command(*args)
+        IOStreams.logger&.debug { "IOStreams::Pgp::Writer.open: #{command.shelljoin}" }
 
-        # Write to stdin, with encrypted contents being written to the file
-        command = "#{IOStreams::Pgp.executable} --batch --no-tty --yes --encrypt"
-        command << " --sign --local-user \"#{signer}\"" if signer
+        # Since stdin carries the data, supply the signer passphrase on file descriptor 3
+        # so that it is not visible in the process list.
+        spawn_options = {}
         if signer_passphrase
-          command << " --pinentry-mode loopback" if IOStreams::Pgp.pgp_version.to_f >= 2.1
-          command << " --no-symkey-cache" if IOStreams::Pgp.pgp_version.to_f >= 2.4
-          command << " --passphrase \"#{signer_passphrase}\""
+          passphrase_reader, passphrase_writer = IO.pipe
+          passphrase_writer.puts(signer_passphrase.to_s)
+          passphrase_writer.close
+          spawn_options[PASSPHRASE_FD] = passphrase_reader
         end
-        command << " -z #{compress_level}" if compress_level != 6
-        command << " --compress-algo #{compress}" unless compress == :none
-        recipients.each { |address| command << " --recipient \"#{address}\"" }
-        command << " -o \"#{file_name}\""
-
-        IOStreams::Pgp.logger&.debug { "IOStreams::Pgp::Writer.open: #{command}" }
 
         result = nil
-        Open3.popen2e(command) do |stdin, out, waith_thr|
+        Open3.popen2e(*command, spawn_options) do |stdin, out, waith_thr|
+          # Only the gpg process needs the passphrase.
+          passphrase_reader&.close
           begin
             stdin.binmode
             result = yield(stdin)
             stdin.close
           rescue Errno::EPIPE
             # Ignore broken pipe because gpg terminates early due to an error
-            ::File.delete(file_name) if ::File.exist?(file_name)
+            ::FileUtils.rm_f(file_name)
             raise(Pgp::Failure, "GPG Failed writing to encrypted file: #{file_name}: #{out.read.chomp}")
           end
           unless waith_thr.value.success?
-            ::File.delete(file_name) if ::File.exist?(file_name)
+            ::FileUtils.rm_f(file_name)
             raise(Pgp::Failure, "GPG Failed to create encrypted file: #{file_name}: #{out.read.chomp}")
           end
         end
         result
+      ensure
+        passphrase_reader&.close
+      end
+
+      def self.build_args(file_name:, encrypt:, signer:, signer_passphrase:, compress:, compress_level:, recipients:)
+        args = ["--batch", "--no-tty", "--yes"]
+        args << "--encrypt" if encrypt
+        args += ["--sign", "--local-user", signer.to_s] if signer
+        if signer_passphrase
+          args += ["--pinentry-mode", "loopback"] if IOStreams::Pgp.pgp_version.to_f >= 2.1
+          args << "--no-symkey-cache" if IOStreams::Pgp.pgp_version.to_f >= 2.4
+          args += ["--passphrase-fd", PASSPHRASE_FD.to_s]
+        end
+        args += ["-z", compress_level.to_s] if compress_level != 6
+        args += ["--compress-algo", compress.to_s] unless compress == :none
+        recipients.each { |address| args += ["--recipient", address.to_s] }
+        args += ["-o", file_name.to_s]
+        args
+      end
+      private_class_method :build_args
+
+      def self.collect_recipients(recipient, import_and_trust_key, import_and_trust_level)
+        recipients = Array(recipient)
+        recipients << audit_recipient if audit_recipient
+
+        Array(import_and_trust_key).each do |key|
+          # Encrypt to the imported key's fingerprint, since its email address could match another key in the keyring.
+          recipients << IOStreams::Pgp.import_and_trust_recipient(key: key, trust_level: import_and_trust_level)
+        end
+        recipients
       end
+      private_class_method :collect_recipients
     end
   end
-end
+end