rspec-pgp_matchers 0.1.2 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c1ede8d3cd2fbc6cea19ba3d0c1dbce8cf0b390239869beec38fe4f6da3e607b
-  data.tar.gz: 6b090779819012e1697e460e78a41cc85d4eaa1687e24441a136f268ebc29c61
+  metadata.gz: 4715837cead4425a9b36c7f7b722d5d64c0910e0987a8ea1c8b56b5c06ef1372
+  data.tar.gz: 713c60d3e6196483f586ec1026eec5b3a4d05155e3540f8207bb24ad116ed711
 SHA512:
-  metadata.gz: f30291f6f0f4eb68a1e3d42e5bdab7208722f4998a0d8e0c17edae16e903fb031864c94005c816aca76b8b52ad6b22b8b240c23708302f94f17220a34517f9be
-  data.tar.gz: 9e49089ab7d42085d1ac94d6807a83408010ba4c17665cb70040b12febb41f301f43cdd4d630f1c463450fdf7028bc7663064d2a78ad351c6bb0a052ee92d3db
+  metadata.gz: ec96116566ec3b4bded4fd3b78566ae567a4d6d69fce22b9b9d8627f4767ffde79b729613e185f4bbb9f10df91e8422df7a7e19ba2255d96ea098ef5d96f0faa
+  data.tar.gz: 8e6d0397bbe146ec9804074a3455a5cb51f3e2cb60eae25f0464748d6c5a1e92a7e9fb83d431afa22907e34e4a940fe1d8f03aba18852752254d434f3028e0c7

data/.travis.yml

@@ -1,12 +1,11 @@
-dist: trusty
+dist: bionic
 language: ruby
-sudo: true
 
 rvm:
-  - "2.3"
-  - "2.4"
-  - "2.5"
   - "2.6"
+  - "2.5"
+  - "2.4"
+  - "2.3"
   - "ruby-head"
 
 env:

data/.yardopts

@@ -0,0 +1,4 @@
+-
+README.adoc
+LICENSE.txt
+PROTECTED_KEYS.adoc

data/PROTECTED_KEYS.adoc

@@ -0,0 +1,99 @@
+= Working with passphrase-protected keys
+
+It is recommended not to use passphrase-protected keys with this gem.
+Remember, `RSpec::PGPMatchers` are meant for testing, therefore there is
+no security trade-off involved.  Nevertheless, passphrase-protected keys are
+supported as well.  With some hassle, though…
+
+IMPORTANT: This guide was written for GnuPG 2.2.  Other versions may require
+a different set of configuration options.
+
+== Passing the passphrase in gpg.conf
+
+This is the easier option, however it will work only if you use the same
+passphrase for all the keys.
+
+1. Write GnuPG options to a config file located at `<pgp/home/path>/gpg.conf`:
++
+----
+yes
+batch
+no-tty
+use-agent
+pinentry-mode loopback
+passphrase <passphrase>
+----
+
+2. Write GnuPG Agent options to a config file located at
+`<pgp/home/path>/gpg-agent.conf`:
++
+----
+allow-loopback-pinentry
+----
+
+3. If GnuPG Agent was running, reload it to pick the updated configuration:
++
+----
+gpgconf --homedir <pgp/home/path> --reload gpg-agent
+----
+
+== Passphrase presetting
+
+This is the recommended and more comprehensive solution, though also bit more
+complicated.
+
+1. Write GnuPG options to a config file located at `<pgp/home/path>/gpg.conf`:
++
+----
+yes
+batch
+no-tty
+use-agent
+----
+
+2. Write GnuPG Agent options to a config file located at
+`<pgp/home/path>/gpg-agent.conf`:
++
+----
+allow-preset-passphrase
+----
+
+3. If GnuPG Agent was running, reload it to pick the updated configuration:
++
+----
+gpgconf --homedir <pgp/home/path> --reload gpg-agent
+----
+
+4. Obtain keygrips of password-protected keys you want to use:
++
+----
+gpg --homedir <pgp/home/path> --list-keys --with-keygrip
+----
++
+Note that sometimes you will need a subkey's keygrip rather than primary key's
+one.  Subkeys are typically used for message encryption, but can be used for
+signing as well.
+
+5. Preset passwords for keys:
++
+----
+gpg-preset-passphrase --homedir <pgp/home/path> --preset --passphrase <passphrase> <keygrip>
+----
++
+or (will read passphrase from standard input):
++
+----
+gpg-preset-passphrase --homedir <pgp/home/path> --preset <keygrip>
+----
++
+Note that `gpg-preset-passphrase` is not in `PATH` on some systems.
+For instance, when GnuPG is installed on MacOS via Homebrew, it is located at
+`/usr/local/opt/gnupg/libexec`, which is not in `PATH` by default.
+
+== Resources
+
+* The GNU Privacy Guard Manual:
+** https://gnupg.org/documentation/manuals/gnupg/GPG-Options.html#GPG-Options[GPG options]
+** https://gnupg.org/documentation/manuals/gnupg/Agent-Options.html#Agent-Options[GPG Agent options]
+** https://www.gnupg.org/documentation/manuals/gnupg/gpg_002dpreset_002dpassphrase.html#gpg_002dpreset_002dpassphrase[GPG Preset Passphrase tool]
+* "link:https://wincent.com/wiki/Using_gpg-agent_on_OS_X[Using gpg-agent on OS X]" on wincent.com -- main source of inspiration for above writing

data/README.adoc

@@ -1,5 +1,7 @@
 = RSpec::PGPMatchers
 
+ifdef::env-yard[:relfileprefix: file.]
+
 image:https://img.shields.io/gem/v/rspec-pgp_matchers.svg[
 	Gem Version, link="https://rubygems.org/gems/rspec-pgp_matchers"]
 image:https://img.shields.io/travis/riboseinc/rspec-pgp_matchers/master.svg[
@@ -111,6 +113,27 @@ RSpec::PGPMatchers::GPGRunner.run_verify("cleartext", "signature_string")
 In all above cases, a triple consisting of captured standard output, captured
 standard error, and `Process::Status` instance is returned.
 
+=== Working with passphrase-protected keys
+
+Consider using unprotected keys in your tests.  It will save you a lot of
+hassle.  However, passphrase-protected keys are also supported.  See
+`<<PROTECTED_KEYS.adoc#,PROTECTED_KEYS.adoc>>` for details.
+
+=== Unusual GnuPG executable name
+
+By default, this gem assumes that GnuPG executable is named `gpg`, and that
+it is in `$PATH`.  This behaviour can be changed, for example:
+
+[source,ruby]
+----
+RSpec::PGPMatchers.gpg_executable = "gpg2" # different executable name
+RSpec::PGPMatchers.gpg_executable = "/opt/gpg/bin/gpg" # absolute path
+RSpec::PGPMatchers.gpg_executable = "../gpg/bin/gpg" # relative path
+----
+
+Avoid hardcoding values.  Usually, setting a proper `$PATH` environment variable
+is better than assigning an absolute path to `gpg_executable` attribute.
+
 == Development
 
 After checking out the repo, run `bin/setup` to install dependencies.

data/bin/console

@@ -7,8 +7,8 @@ require "rspec/pgp_matchers"
 # with your gem easier. You can also use a different console, if you like.
 
 # (If you use this, don't forget to add pry to your Gemfile!)
-# require "pry"
-# Pry.start
+require "pry"
+Pry.start
 
-require "irb"
-IRB.start(__FILE__)
+# require "irb"
+# IRB.start(__FILE__)

data/ci/gemfiles/rspec-3.4.gemfile

@@ -1,5 +1,3 @@
-# rubocop:disable Security/Eval
-eval File.read(File.expand_path("common.gemfile", __dir__))
-# rubocop:enable Security/Eval
+eval_gemfile "common.gemfile"
 
 gem "rspec-expectations", "~> 3.4.0"

data/ci/gemfiles/rspec-3.5.gemfile

@@ -1,5 +1,3 @@
-# rubocop:disable Security/Eval
-eval File.read(File.expand_path("common.gemfile", __dir__))
-# rubocop:enable Security/Eval
+eval_gemfile "common.gemfile"
 
 gem "rspec-expectations", "~> 3.5.0"

data/ci/gemfiles/rspec-3.6.gemfile

@@ -1,5 +1,3 @@
-# rubocop:disable Security/Eval
-eval File.read(File.expand_path("common.gemfile", __dir__))
-# rubocop:enable Security/Eval
+eval_gemfile "common.gemfile"
 
 gem "rspec-expectations", "~> 3.6.0"

data/ci/gemfiles/rspec-3.7.gemfile

@@ -1,5 +1,3 @@
-# rubocop:disable Security/Eval
-eval File.read(File.expand_path("common.gemfile", __dir__))
-# rubocop:enable Security/Eval
+eval_gemfile "common.gemfile"
 
 gem "rspec-expectations", "~> 3.7.0"

data/lib/rspec/pgp_matchers.rb

@@ -1,6 +1,7 @@
 # (c) Copyright 2018 Ribose Inc.
 #
 
+require "rspec/expectations"
 require "rspec/pgp_matchers/version"
 require "rspec/pgp_matchers/gpg_matcher_helper"
 require "rspec/pgp_matchers/gpg_runner"
@@ -9,9 +10,34 @@ require "rspec/pgp_matchers/be_a_valid_pgp_signature_of"
 
 module RSpec
   module PGPMatchers
+    @gpg_executable = "gpg"
+
     class << self
+      # Name of the GnuPG executable or path to that executable.  Defaults to
+      # +gpg+.
+      #
+      # Absolute and relative paths are allowed, but usually setting +$PATH+
+      # environment variable is a better idea.
+      #
+      # @return [String] executable name or absolute or relative path to that
+      #   executable
+      attr_accessor :gpg_executable
+
+      # Path to the OpenPGP home directory.  Defaults to +nil+ and must be set
+      # prior using the matchers.
+      #
+      # Given directory may be initialized with other tool than GnuPG, e.g. RNP,
+      # but it must be in a format which is readable by GnuPG.  Also,
+      # if specified directory is empty, then it will be initialized by GnuPG
+      # at first use, it must exist though.  Nevertheless, the latter case is
+      # not very practical, as the OpenPGP home directory created this way
+      # contains no keys.
+      #
+      # It is recommended to have a dedicated PGP home directory just for
+      # testing, so that test keys are separated from regular ones.
+      #
+      # @return [String] absolute or relative path to the OpenPGP home directory
       attr_accessor :homedir
     end
-    # Your code goes here...
   end
 end

data/lib/rspec/pgp_matchers/gpg_matcher_helper.rb

@@ -6,6 +6,10 @@ require "tempfile"
 
 module RSpec
   module PGPMatchers
+    # A collection of utility methods to be included in matchers.  Mostly for
+    # extracting information from GnuPG output.
+    #
+    # @api private
     module GPGMatcherHelper
       extend Forwardable
 

data/lib/rspec/pgp_matchers/gpg_runner.rb

@@ -6,21 +6,39 @@ require "tempfile"
 
 module RSpec
   module PGPMatchers
+    # A helper module for executing GnuPG commands.
     module GPGRunner
       class << self
+        # Executes arbitrary GnuPG command.
+        #
+        # @param gpg_cmd [String] command to run
+        # @return [Array] tuple +[stdout, stderr, status]+
+        #   like in stdlib's {Open3.capture3}
+        #
+        # @example
+        #   # Will list all GnuPG keys
+        #   run_command("--list-keys")
+        #   # Will list keys and their keygrips
+        #   run_command("--list-keys --with-keygrip")
         def run_command(gpg_cmd)
           env = { "LC_ALL" => "C" } # Gettext English locale
 
+          gpg_executable = Shellwords.escape(RSpec::PGPMatchers.gpg_executable)
           homedir_path = Shellwords.escape(RSpec::PGPMatchers.homedir)
 
           Open3.capture3(env, <<~SH)
-            gpg \
+            #{gpg_executable} \
             --homedir #{homedir_path} \
             --no-permission-warning \
             #{gpg_cmd}
           SH
         end
 
+        # Decrypts a message.
+        #
+        # @param encrypted_string [String] encrypted message
+        # @return [Array] tuple +[stdout, stderr, status]+
+        #   like in stdlib's {Open3.capture3}
         def run_decrypt(encrypted_string)
           enc_file = make_tempfile_containing(encrypted_string)
           cmd = gpg_decrypt_command(enc_file)
@@ -29,6 +47,12 @@ module RSpec
           File.unlink(enc_file.path)
         end
 
+        # Verifies a signature.
+        #
+        # @param cleartext [String] message in clear text
+        # @param signature_string [String] signature
+        # @return [Array] tuple +[stdout, stderr, status]+
+        #   like in stdlib's {Open3.capture3}
         def run_verify(cleartext, signature_string)
           sig_file = make_tempfile_containing(signature_string)
           data_file = make_tempfile_containing(cleartext)

data/lib/rspec/pgp_matchers/version.rb

@@ -3,6 +3,6 @@
 
 module RSpec
   module PGPMatchers
-    VERSION = "0.1.2".freeze
+    VERSION = "0.2.0".freeze
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rspec-pgp_matchers
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.2.0
 platform: ruby
 authors:
 - Ribose Inc.
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2019-01-12 00:00:00.000000000 Z
+date: 2019-09-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec-expectations
@@ -114,8 +114,10 @@ files:
 - ".rspec"
 - ".rubocop.yml"
 - ".travis.yml"
+- ".yardopts"
 - Gemfile
 - LICENSE.txt
+- PROTECTED_KEYS.adoc
 - README.adoc
 - Rakefile
 - bin/bundle
@@ -154,8 +156,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubyforge_project: 
-rubygems_version: 2.7.6
+rubygems_version: 3.0.3
 signing_key: 
 specification_version: 4
 summary: RSpec matchers for testing OpenPGP messages