rspec-pgp_matchers 0.1.0

data/lib/rspec/pgp_matchers.rb

@@ -0,0 +1,16 @@
+# (c) Copyright 2018 Ribose Inc.
+#
+
+require "rspec/pgp_matchers/version"
+require "rspec/pgp_matchers/gpg_matcher_helper"
+require "rspec/pgp_matchers/be_a_pgp_encrypted_message"
+require "rspec/pgp_matchers/be_a_valid_pgp_signature_of"
+
+module RSpec
+  module PGPMatchers
+    class << self
+      attr_accessor :homedir
+    end
+    # Your code goes here...
+  end
+end

data/lib/rspec/pgp_matchers/be_a_pgp_encrypted_message.rb

@@ -0,0 +1,113 @@
+# (c) Copyright 2018 Ribose Inc.
+#
+
+# A following PGP matcher calls the GPG executable in a subshell, then
+# parses command output.  This is a poor pattern in general, because output
+# messages may subtly change over GPG evolution, and some maintenance work
+# may be required.
+#
+# However, GPG executables do not provide any machine-readable output which
+# could be used instead.  Furthermore, using RNP or GPGME from here is also
+# a poor idea, because this gem is going to be tested against various
+# combinations of software, in some of which that dependency may be unavailable.
+#
+# If parsing the output of GPG commands will become a burden, then the preferred
+# solution is to develop a minimalist validator which, if executed in
+# a subshell, returns some useful machine-readable output.  A validator tool
+# running in a separate process may leverage GPGME, as it won't be exposed
+# outside the validator.  A previous implementation of this matcher may provide
+# some useful ideas.  See commit 2e2bd0da090d7d31ecacc2d1ea6bd3e13479e675.
+#
+# rubocop:disable Metrics/BlockLength
+RSpec::Matchers.define :be_a_pgp_encrypted_message do
+  # rubocop:enable Metrics/BlockLength
+  include RSpec::PGPMatchers::GPGMatcherHelper
+
+  attr_reader :err, :expected_recipients
+
+  match do |encrypted_string|
+    @err = validate_encrypted_message(encrypted_string)
+    @err.nil?
+  end
+
+  chain :containing, :expected_cleartext
+  chain :signed_by, :expected_signer
+
+  chain :encrypted_for do |*recipients|
+    @expected_recipients = [*recipients]
+  end
+
+  failure_message do
+    err
+  end
+
+  # Returns +nil+ if signature is valid, or an error message otherwise.
+  def validate_encrypted_message(encrypted_string)
+    cmd_output = run_gpg_decrypt(encrypted_string)
+    cmd_result = analyse_decrypt_output(*cmd_output)
+
+    if cmd_result[:well_formed_pgp_data]
+      match_constraints(**cmd_result)
+    else
+      msg_no_pgg_data(encrypted_string)
+    end
+  end
+
+  def run_gpg_decrypt(encrypted_string)
+    enc_file = make_tempfile_containing(encrypted_string)
+    cmd = gpg_decrypt_command(enc_file)
+    run_command(cmd)
+  end
+
+  def analyse_decrypt_output(stdout_str, stderr_str, status)
+    {
+      well_formed_pgp_data: (status.exitstatus != 2),
+      recipients: detect_recipients(stderr_str),
+      signature: detect_signers(stderr_str).first,
+      cleartext: stdout_str,
+    }
+  end
+
+  def match_constraints(cleartext:, recipients:, signature:, **_ignored)
+    [
+      (expected_cleartext && match_cleartext(cleartext)),
+      (expected_recipients && match_recipients(recipients)),
+      (expected_signer && match_signature(signature)),
+    ].detect { |x| x }
+  end
+
+  def gpg_decrypt_command(enc_file)
+    homedir_path = Shellwords.escape(RSpec::PGPMatchers.homedir)
+    enc_path = Shellwords.escape(enc_file.path)
+
+    <<~SH
+      gpg \
+      --homedir #{homedir_path} \
+      --no-permission-warning \
+      --decrypt #{enc_path}
+    SH
+  end
+
+  def msg_mismatch(text)
+    "expected given Open PGP message to contain following " +
+      "text:\n#{expected_cleartext}\nbut was:\n#{text}"
+  end
+
+  def msg_no_pgg_data(file_text)
+    "expected given text to be a valid Open PGP encrypted message, " +
+      "but it contains no PGP data, just:\n#{file_text}"
+  end
+
+  def msg_wrong_recipients(recipients)
+    expected_recipients_list = expected_recipients.inspect
+    recipients_list = recipients.inspect
+
+    "expected given Open PGP message to be encrypted for following " +
+      "recipients: #{expected_recipients_list}, but was for: #{recipients_list}"
+  end
+
+  def msg_wrong_signer(actual_signer)
+    "expected singature to be signed by #{expected_signer}, " +
+      "but was actually signed by #{actual_signer}"
+  end
+end

data/lib/rspec/pgp_matchers/be_a_valid_pgp_signature_of.rb

@@ -0,0 +1,95 @@
+# (c) Copyright 2018 Ribose Inc.
+#
+
+# A following PGP matcher calls the GPG executable in a subshell, then
+# parses command output.  This is a poor pattern in general, because output
+# messages may subtly change over GPG evolution.
+#
+# However, GPG executables do not provide any machine-readable output which
+# could be used instead.  Furthermore, using RNP or GPGME from here is also
+# a poor idea, because this gem is going to be tested against various
+# combinations of software, in some of which that dependency may be unavailable.
+#
+# If output parsing will ever become a source of problems, then the preferred
+# solution is to develop a minimalist validator which, if executed in
+# a subshell, returns useful machine-readable output.  A validator tool running
+# in a separate process may leverage GPGME, as it won't be exposed outside
+# the validator.  A previous implementation of this matcher may provide some
+# useful ideas.  See commit 2e2bd0da090d7d31ecacc2d1ea6bd3e13479e675.
+#
+# rubocop:disable Metrics/BlockLength
+RSpec::Matchers.define :be_a_valid_pgp_signature_of do |text|
+  # rubocop:enable Metrics/BlockLength
+  include RSpec::PGPMatchers::GPGMatcherHelper
+
+  attr_reader :err
+
+  match do |signature_string|
+    @err = verify_signature(text, signature_string)
+    @err.nil?
+  end
+
+  chain :signed_by, :expected_signer
+
+  failure_message do
+    err
+  end
+
+  # Returns +nil+ if first signature is valid, or an error message otherwise.
+  def verify_signature(cleartext, signature_string)
+    cmd_output = run_gpg_verify(cleartext, signature_string)
+    cmd_result = analyse_verify_output(*cmd_output)
+
+    if cmd_result[:well_formed_pgp_data]
+      match_constraints(**cmd_result)
+    else
+      msg_no_pgg_data(signature_string)
+    end
+  end
+
+  def run_gpg_verify(cleartext, signature_string)
+    sig_file = make_tempfile_containing(signature_string)
+    data_file = make_tempfile_containing(cleartext)
+    cmd = gpg_verify_command(sig_file, data_file)
+    run_command(cmd)
+  end
+
+  def analyse_verify_output(_stdout_str, stderr_str, status)
+    {
+      well_formed_pgp_data: (status.exitstatus != 2),
+      signature: detect_signers(stderr_str).first,
+    }
+  end
+
+  def match_constraints(signature:, **_ignored)
+    match_signature(signature)
+  end
+
+  def gpg_verify_command(sig_file, data_file)
+    homedir_path = Shellwords.escape(RSpec::PGPMatchers.homedir)
+    sig_path = Shellwords.escape(sig_file.path)
+    data_path = Shellwords.escape(data_file.path)
+
+    <<~SH
+      gpg \
+      --homedir #{homedir_path} \
+      --no-permission-warning \
+      --verify #{sig_path} #{data_path}
+    SH
+  end
+
+  def msg_mismatch(text)
+    "expected given signature to be a valid Open PGP signature " +
+      "of following text:\n#{text}"
+  end
+
+  def msg_no_pgg_data(file_text)
+    "expected given text to be a valid Open PGP signature, " +
+      "but it contains no PGP data, just:\n#{file_text}"
+  end
+
+  def msg_wrong_signer(actual_signer)
+    "expected singature to be signed by #{expected_signer}, " +
+      "but was actually signed by #{actual_signer}"
+  end
+end

data/lib/rspec/pgp_matchers/gpg_matcher_helper.rb

@@ -0,0 +1,63 @@
+# (c) Copyright 2018 Ribose Inc.
+#
+
+require "open3"
+require "tempfile"
+
+module RSpec
+  module PGPMatchers
+    module GPGMatcherHelper
+      def detect_signers(stderr_str)
+        rx = /(?<ok>Good|BAD) signature from .*\<(?<email>[^>]+)\>/
+
+        stderr_str.to_enum(:scan, rx).map do
+          {
+            email: $~["email"],
+            ok: ($~["ok"] == "Good"),
+          }
+        end
+      end
+
+      def detect_recipients(stderr_str)
+        rx = /encrypted with .*\n.*\<(?<email>[^>]+)\>/
+
+        stderr_str.to_enum(:scan, rx).map do
+          $~["email"]
+        end
+      end
+
+      def match_cleartext(cleartext)
+        if cleartext != expected_cleartext
+          msg_mismatch(cleartext)
+        end
+      end
+
+      def match_recipients(recipients)
+        if expected_recipients.sort != recipients.sort
+          msg_wrong_recipients(recipients)
+        end
+      end
+
+      # Checks if signature is valid.  If `expected_signer` is not `nil`, then
+      # it additionally checks if the signature was issued by expected signer.
+      def match_signature(signature)
+        if !signature[:ok]
+          msg_mismatch(text)
+        elsif expected_signer && signature[:email] != expected_signer
+          msg_wrong_signer(signature[:email])
+        end
+      end
+
+      def make_tempfile_containing(file_content)
+        tempfile = Tempfile.new
+        tempfile.write(file_content)
+        tempfile.flush
+      end
+
+      def run_command(cmd)
+        env = { "LC_ALL" => "C" } # Gettext English locale
+        Open3.capture3(env, cmd)
+      end
+    end
+  end
+end

data/lib/rspec/pgp_matchers/version.rb

@@ -0,0 +1,8 @@
+# (c) Copyright 2018 Ribose Inc.
+#
+
+module RSpec
+  module PGPMatchers
+    VERSION = "0.1.0".freeze
+  end
+end

data/rspec-pgp_matchers.gemspec

@@ -0,0 +1,37 @@
+# (c) Copyright 2018 Ribose Inc.
+#
+
+lib = File.expand_path("lib", __dir__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require "rspec/pgp_matchers/version"
+
+Gem::Specification.new do |spec|
+  spec.name          = "rspec-pgp_matchers"
+  spec.version       = RSpec::PGPMatchers::VERSION
+  spec.authors       = ["Ribose Inc."]
+  spec.email         = ["open.source@ribose.com"]
+
+  spec.summary       = "RSpec matchers for testing OpenPGP messages"
+  spec.homepage      = "https://github.com/riboseinc/rspec-pgp_matchers"
+  spec.license       = "MIT"
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added
+  # into git.
+  spec.files         = Dir.chdir(File.expand_path(__dir__)) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      f.match(%r{^(test|spec|features)/})
+    end
+  end
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_runtime_dependency "rspec-expectations", "~> 3.4"
+
+  spec.add_development_dependency "bundler", "~> 1.16"
+  spec.add_development_dependency "gpgme"
+  spec.add_development_dependency "pry", ">= 0.10.3", "< 0.12"
+  spec.add_development_dependency "rake", "~> 12.0"
+  spec.add_development_dependency "rspec", "~> 3.0"
+end

metadata

@@ -0,0 +1,164 @@
+--- !ruby/object:Gem::Specification
+name: rspec-pgp_matchers
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Ribose Inc.
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2018-08-21 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rspec-expectations
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.4'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.4'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.16'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.16'
+- !ruby/object:Gem::Dependency
+  name: gpgme
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: pry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.10.3
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '0.12'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.10.3
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '0.12'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '12.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '12.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+description: 
+email:
+- open.source@ribose.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".editorconfig"
+- ".gitignore"
+- ".hound.yml"
+- ".rspec"
+- ".rubocop.ribose.yml"
+- ".rubocop.tb.yml"
+- ".rubocop.yml"
+- ".travis.yml"
+- Gemfile
+- LICENSE.txt
+- README.adoc
+- Rakefile
+- bin/bundle
+- bin/console
+- bin/rake
+- bin/rspec
+- bin/setup
+- ci/gemfiles/common.gemfile
+- ci/gemfiles/rspec-3.4.gemfile
+- ci/gemfiles/rspec-3.5.gemfile
+- ci/gemfiles/rspec-3.6.gemfile
+- ci/gemfiles/rspec-3.7.gemfile
+- ci/install_gpg_all.sh
+- ci/install_gpg_component.sh
+- lib/rspec/pgp_matchers.rb
+- lib/rspec/pgp_matchers/be_a_pgp_encrypted_message.rb
+- lib/rspec/pgp_matchers/be_a_valid_pgp_signature_of.rb
+- lib/rspec/pgp_matchers/gpg_matcher_helper.rb
+- lib/rspec/pgp_matchers/version.rb
+- rspec-pgp_matchers.gemspec
+homepage: https://github.com/riboseinc/rspec-pgp_matchers
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.7.6
+signing_key: 
+specification_version: 4
+summary: RSpec matchers for testing OpenPGP messages
+test_files: []