enmail 0.1.0 → 0.2.0

data/ci/install_json_c.sh

@@ -0,0 +1,32 @@
+#!/bin/bash
+
+# (c) Copyright 2018 Ribose Inc.
+#
+
+# Based on:
+# https://github.com/riboseinc/ruby-rnp/blob/52d6113458cb095cf7811/ci/install.sh
+
+set -eux
+
+: "${CORES:=2}"
+: "${MAKE:=make}"
+
+jsonc_build="${DEPS_BUILD_DIR}/json-c"
+
+if [ ! -e "${JSONC_PREFIX}/lib/libjson-c.so" ] && \
+	 [ ! -e "${JSONC_PREFIX}/lib/libjson-c.dylib" ]; then
+
+	 if [ -d "${jsonc_build}" ]; then
+		 rm -rf "${jsonc_build}"
+	 fi
+
+	mkdir -p "${jsonc_build}"
+	pushd ${jsonc_build}
+	wget https://s3.amazonaws.com/json-c_releases/releases/json-c-0.12.1.tar.gz -O json-c.tar.gz
+	tar xzf json-c.tar.gz --strip 1
+
+	autoreconf -ivf
+	env CFLAGS="-fno-omit-frame-pointer -g" ./configure --prefix="${JSONC_PREFIX}"
+	${MAKE} -j${CORES} install
+	popd
+fi

data/ci/install_rnp.sh

@@ -0,0 +1,31 @@
+#!/bin/bash
+
+# (c) Copyright 2018 Ribose Inc.
+#
+
+# Based on:
+# https://github.com/riboseinc/ruby-rnp/blob/52d6113458cb095cf7811/ci/install.sh
+
+set -eux
+
+: "${CORES:=2}"
+: "${MAKE:=make}"
+
+rnp_build="${DEPS_BUILD_DIR}/rnp"
+
+if [ ! -e "${RNP_PREFIX}/lib/librnp.so" ] && \
+	 [ ! -e "${RNP_PREFIX}/lib/librnp.dylib" ]; then
+
+	git clone https://github.com/riboseinc/rnp ${rnp_build}
+	pushd "${rnp_build}"
+	git checkout "$RNP_VERSION"
+	cmake \
+		-DCMAKE_BUILD_TYPE=RelWithDebInfo \
+		-DBUILD_SHARED_LIBS=yes \
+		-DBUILD_TESTING=no \
+		-DCMAKE_PREFIX_PATH="${BOTAN_PREFIX};${JSONC_PREFIX}" \
+		-DCMAKE_INSTALL_PREFIX="${RNP_PREFIX}" \
+		.
+	${MAKE} -j${CORES} install
+	popd
+fi

data/docs/GPGMEAdapter.adoc

@@ -0,0 +1,68 @@
+= GPGME Adapter Guide
+
+`GPGME` adapter provides OpenPGP-compliant cryptography via
+https://gnupg.org/software/gpgme/index.html[GnuPG Made Easy] library.
+
+== Dependencies
+
+This adapter requries two additional pieces of software to be installed:
+
+1. GnuPG, version 2.2
+2. `https://rubygems.org/gems/gpgme[gpgme]` gem
+
+== Options
+
+Following adapter-specific options are supported:
+
+`signer`::
+Optional.  User id or e-mail which identifies key which will be used for message
+signing.  By default, first address from mail's From field is used.
+`key_password`::
+Optional.  Password for signer's key.  Must be a string.
+
+== Non-standard home directory location
+
+GnuPG home directory is a place where configuration, keyrings, etc. are stored.
+By default, GnuPG home directory is located in `$HOME/.gnupg`.  You can change
+it in a following way:
+
+[source,ruby]
+----
+::GPGME::Engine.home_dir = 'path/to/home_dir'
+----
+
+Be advised that this setting is global.  Hence, if you use GPGME outside EnMail
+as well, your other logic will be affected.  One possible workaround is to sign
+e-mails in a different process.  This should be fairly easy to achieve in Rails,
+as mailing is often handed to some kind of background job processor which runs
+in its own process.  Nevertheless, consider switching to RNP adapter if this
+limitation poses a problem.
+
+== Using `gpg.conf`
+
+GPGME API accepts little configuration options.  Instead, it reads preferences
+from a `gpg.conf` file located in GnuPG home directory (usually `$HOME/.gnupg`).
+You may override defaults there, i.e. set preferred keys or algorithms.
+Refer to GnuPG documentation for
+https://www.gnupg.org/documentation/manuals/gnupg/GPG-Configuration.html[more
+information about configuration files], or for
+https://www.gnupg.org/documentation/manuals/gnupg/GPG-Options.html[list of
+available options].  Also, you will find some nice example `gpg.conf` in this
+https://stackoverflow.com/a/34923350/304175[Stack Overflow answer].
+
+== Native extensions
+
+The `gpgme` gem includes C extensions.
+
+== Issue tracker
+
+Bugs, feature requests, and other issues are tracked with `adapter: gpgme`
+label: https://github.com/riboseinc/enmail/issues?q=is%3Aissue+is%3Aopen+label%3A%22adapter%3A+gpgme%22
+
+== External links
+
+* https://tools.ietf.org/html/rfc1847[RFC 1847 "Security Multiparts for MIME"]
+* https://tools.ietf.org/html/rfc3156[RFC 3156 "MIME Security with OpenPGP"]
+* https://gnupg.org[GNU Privacy Guard home site]
+* https://gnupg.org/software/gpgme/index.html[GPGME (GnuPG Made Easy) library home site]
+* https://github.com/ueno/ruby-gpgme[Ruby bindings for GPGME library]

data/docs/RNPAdapter.adoc

@@ -0,0 +1,45 @@
+= RNP Adapter Guide
+
+`RNP` adapter provides OpenPGP-compliant cryptography via
+https://www.rnpgp.com/[RNP] library.
+
+== Dependencies
+
+This adapter requries two additional pieces of software to be installed:
+
+1. RNP library, version 0.9.2 or newer
+2. `https://rubygems.org/gems/rnp[rnp]` gem, version 1.0.1 or newer
+
+== Options
+
+Following adapter-specific options are supported:
+
+`homedir`::
+Optional.  Path to RNP home directory, which contains public and secret
+keyrings.  In most situations, RNP is able to read GnuPG home directories,
+hence it's common to set it to `<your_home_directory>/.gpg`.  Defaults to
+`<your_home_directory>/.rnp`.
+`signer`::
+Optional.  User id or e-mail which identifies key which will be used for message
+signing.  By default, first address from mail's From field is used.
+`key_password`::
+Optional.  Password for signer's key.  Can be a string or proc, see
+`rnp` gem documentation for `Rnp#password_provider=`.
+
+== Native extensions
+
+The `rnp` gem depends on `https://github.com/ffi/ffi[ffi]` gem, which includes
+native extensions.
+
+== Issue tracker
+
+Bugs, feature requests, and other issues are tracked with `adapter: rnp`
+label: https://github.com/riboseinc/enmail/issues?q=is%3Aissue+is%3Aopen+label%3A%22adapter%3A+rnp%22
+
+== External links
+
+* https://tools.ietf.org/html/rfc1847[RFC 1847 "Security Multiparts for MIME"]
+* https://tools.ietf.org/html/rfc3156[RFC 3156 "MIME Security with OpenPGP"]
+* https://www.rnpgp.com[RNP library home site]
+* https://github.com/riboseinc/rnp[RNP library on GitHub]
+* https://github.com/riboseinc/ruby-rnp[Ruby bindings for RNP library]

data/enmail.gemspec

@@ -1,16 +1,21 @@
 # coding: utf-8
-lib = File.expand_path("../lib", __FILE__)
+
+# (c) Copyright 2018 Ribose Inc.
+#
+
+lib = File.expand_path("lib", __dir__)
 $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
 require "enmail/version"
+require "enmail/dependency_constraints"
 
 Gem::Specification.new do |spec|
   spec.name          = "enmail"
   spec.version       = EnMail::VERSION
-  spec.authors       = ["Ronald Tse"]
-  spec.email         = ["ronald.tse@ribose.com"]
+  spec.authors       = ["Ribose Inc."]
+  spec.email         = ["open.source@ribose.com"]
 
-  spec.summary       = %q{Encrypted Email in Ruby}
-  spec.description   = %q{Encrypted Email in Ruby}
+  spec.summary       = "Encrypted Email in Ruby"
+  spec.description   = "Encrypted Email in Ruby"
   spec.homepage      = "https://github.com/riboseinc/enmail"
   spec.license       = "MIT"
 
@@ -22,10 +27,18 @@ Gem::Specification.new do |spec|
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ["lib"]
 
+  # There is no reason for 2.6.4 to be a minimum supported version of Mail,
+  # except for that this gem was never tested against older versions.
+  # Mail 2.6.4 has been released on March 23, 2016, hence should be considered
+  # old enough.  Nevertheless, pull requests which extend compatibility will be
+  # accepted.
   spec.add_dependency "mail", "~> 2.6.4"
 
-  spec.add_development_dependency "bundler", "~> 1.14"
-  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "bundler", ">= 1.14", "< 3.0"
+  spec.add_development_dependency "gpgme", *EnMail::DependencyConstraints::GPGME
+  spec.add_development_dependency "pry", ">= 0.10.3", "< 0.12"
+  spec.add_development_dependency "rake", ">= 10", "< 13"
+  spec.add_development_dependency "rnp", *EnMail::DependencyConstraints::RNP
   spec.add_development_dependency "rspec", "~> 3.0"
-  spec.add_development_dependency "pry", "~>0.10.3"
+  spec.add_development_dependency "rspec-pgp_matchers", "~> 0.1.1"
 end

data/lib/enmail.rb

@@ -1,7 +1,28 @@
-require "enmail/key"
-require "enmail/config"
-require "enmail/certificate_finder"
+# (c) Copyright 2018 Ribose Inc.
+#
+
+require "mail"
+
+require "enmail/version"
+require "enmail/dependency_constraints"
+
+require "enmail/helpers/message_manipulation"
+require "enmail/helpers/rfc1847"
+require "enmail/helpers/rfc3156"
+
+require "enmail/adapters/base"
+require "enmail/adapters/gpgme"
+require "enmail/adapters/rnp"
+
+require "enmail/extensions/message_transport_encoding_restrictions"
 
 module EnMail
-  # Your code goes here...
+  module_function
+
+  def protect(mode, message, adapter:, **options)
+    adapter_obj = adapter.new(options)
+    adapter_obj.public_send mode, message
+  end
 end
+
+Mail::Message.prepend EnMail::Extensions::MessageTransportEncodingRestrictions

data/lib/enmail/adapters/base.rb

@@ -0,0 +1,14 @@
+# (c) Copyright 2018 Ribose Inc.
+#
+
+module EnMail
+  module Adapters
+    class Base
+      attr_reader :options
+
+      def initialize(options)
+        @options = options
+      end
+    end
+  end
+end

data/lib/enmail/adapters/gpgme.rb

@@ -0,0 +1,81 @@
+# (c) Copyright 2018 Ribose Inc.
+#
+
+module EnMail
+  module Adapters
+    # Secures e-mails according to {RFC 3156 "MIME Security with
+    # OpenPGP"}[https://tools.ietf.org/html/rfc3156].
+    #
+    # This adapter uses {GnuPG Made Easy
+    # (GPGME)}[https://www.gnupg.org/software/gpgme/index.html] library via
+    # interface provided by {gpgme gem}[https://github.com/ueno/ruby-gpgme].
+    class GPGME < Base
+      include Helpers::MessageManipulation
+      include Helpers::RFC1847
+      include Helpers::RFC3156
+
+      def initialize(*args)
+        require_relative "gpgme_requirements"
+        super
+      end
+
+      private
+
+      def compute_signature(text, signer)
+        plain = ::GPGME::Data.new(text)
+        output = ::GPGME::Data.new
+        mode = ::GPGME::SIG_MODE_DETACH
+        hash_algorithm = nil
+
+        with_ctx(password: options[:key_password]) do |ctx|
+          signer_keys = ::GPGME::Key.find(:secret, signer, :sign)
+          ctx.add_signer(*signer_keys)
+
+          begin
+            ctx.sign(plain, output, mode)
+            hash_algorithm_num = ctx.sign_result.signatures[0].hash_algo
+            hash_algorithm = ::GPGME.hash_algo_name(hash_algorithm_num)
+          rescue ::GPGME::Error::UnusableSecretKey => exc
+            # TODO Copy-pasted from GPGME gem.  Needs any test coverage.
+            exc.keys = ctx.sign_result.invalid_signers
+            raise exc
+          end
+        end
+
+        output.seek(0)
+
+        ["pgp-#{hash_algorithm.downcase}", output.to_s]
+      end
+
+      def encrypt_string(text, recipients)
+        build_crypto.encrypt(text, recipients: recipients)
+      end
+
+      def sign_and_encrypt_string(text, signer, recipients)
+        build_crypto.encrypt(
+          text,
+          sign: true,
+          signers: [signer],
+          recipients: recipients,
+          password: options[:key_password],
+        )
+      end
+
+      def build_crypto
+        ::GPGME::Crypto.new(default_gpgme_options)
+      end
+
+      def with_ctx(options, &block)
+        ctx_options = default_gpgme_options.merge(options)
+        ::GPGME::Ctx.new(ctx_options, &block)
+      end
+
+      def default_gpgme_options
+        {
+          armor: true,
+          pinentry_mode: ::GPGME::PINENTRY_MODE_LOOPBACK,
+        }
+      end
+    end
+  end
+end

data/lib/enmail/adapters/gpgme_requirements.rb

@@ -0,0 +1,3 @@
+gem "gpgme", *EnMail::DependencyConstraints::GPGME
+
+require "gpgme"

data/lib/enmail/adapters/rnp.rb

@@ -0,0 +1,109 @@
+# (c) Copyright 2018 Ribose Inc.
+#
+
+module EnMail
+  module Adapters
+    # Secures e-mails according to {RFC 3156 "MIME Security with
+    # OpenPGP"}[https://tools.ietf.org/html/rfc3156].
+    #
+    # This adapter uses {RNP}[https://www.rnpgp.com/] library via
+    # {ruby-rnp gem}[https://github.com/riboseinc/ruby-rnp].
+    #
+    # NOTE: `Rnp` instances are not thread-safe, and neither this adapter is.
+    # Any adapter instance should be accessed by at most one thread at a time.
+    class RNP < Base
+      include Helpers::MessageManipulation
+      include Helpers::RFC1847
+      include Helpers::RFC3156
+
+      attr_reader :rnp
+
+      def initialize(*args)
+        require_relative "rnp_requirements"
+        super
+        @rnp = build_rnp_and_load_keys
+      end
+
+      private
+
+      def compute_signature(text, signer)
+        signer_key = find_key_for(signer, need_secret: true)
+
+        signature = rnp.detached_sign(
+          signers: [signer_key],
+          input: build_input(text),
+          armored: true,
+          hash: hash_algorithm,
+        )
+
+        ["pgp-#{hash_algorithm.downcase}", signature]
+      end
+
+      def encrypt_string(text, recipients)
+        recipient_keys =
+          recipients.map { |r| find_key_for(r, need_public: true) }
+
+        rnp.encrypt(
+          recipients: recipient_keys,
+          input: build_input(text),
+          armored: true,
+        )
+      end
+
+      def sign_and_encrypt_string(text, signer, recipients)
+        signer_key = find_key_for(signer, need_secret: true)
+        recipient_keys =
+          recipients.map { |r| find_key_for(r, need_public: true) }
+
+        rnp.encrypt_and_sign(
+          recipients: recipient_keys,
+          signers: signer_key,
+          input: build_input(text),
+          armored: true,
+          hash: hash_algorithm,
+        )
+      end
+
+      def find_key_for(email, need_public: false, need_secret: false)
+        rnp.each_keyid do |keyid|
+          key = rnp.find_key(keyid: keyid)
+          next if need_public && !key.public_key_present?
+          next if need_secret && !key.secret_key_present?
+
+          key.each_userid do |userid|
+            return key if userid.include?(email)
+          end
+        end
+        nil
+      end
+
+      def build_input(text)
+        ::Rnp::Input.from_string(text)
+      end
+
+      def build_rnp_and_load_keys
+        public_info, secret_info = homedir_info.values_at(:public, :secret)
+
+        rnp = Rnp.new(public_info[:format], secret_info[:format])
+
+        [public_info, secret_info].each do |keyring_info|
+          input = ::Rnp::Input.from_path(keyring_info[:path])
+          rnp.load_keys(format: keyring_info[:format], input: input)
+        end
+
+        rnp.password_provider = options[:key_password]
+
+        rnp
+      end
+
+      def homedir_info
+        @homedir_info ||=
+          ::Rnp.homedir_info(options[:homedir] || Rnp.default_homedir)
+      end
+
+      def hash_algorithm
+        "SHA512"
+      end
+    end
+  end
+end