enmail 0.1.0 → 0.2.0

data/.travis.yml

@@ -1,5 +1,88 @@
-sudo: false
+dist: xenial
+sudo: required
 language: ruby
+
 rvm:
-  - 2.4.1
-before_install: gem install bundler -v 1.14.6
+  - 2.6
+  - 2.5
+  - 2.4
+  - 2.3
+  - ruby-head
+
+env:
+  global:
+    - EXPECT_GPG_VERSION="2.2"
+    - GPG_VERSION="latest"
+    - RNP_VERSION="master"
+
+    - DEPS_BUILD_DIR="${TRAVIS_BUILD_DIR}/build"
+    - DEPS_PREFIX="${TRAVIS_BUILD_DIR}/opt"
+    - BOTAN_PREFIX="${DEPS_PREFIX}/botan"
+    - JSONC_PREFIX="${DEPS_PREFIX}/json-c"
+    - RNP_PREFIX="${DEPS_PREFIX}/rnp"
+    - GPG_PREFIX="${DEPS_PREFIX}/gpg"
+
+    # Be aware of differences between LD_LIBRARY_PATH and LD_RUN_PATH.
+    # - http://osr507doc.sco.com/en/tools/ccs_linkedit_dynamic_dirsearch.html
+    # - https://www.hpc.dtu.dk/?page_id=1180
+    #
+    # You should be careful when attempting to replicate following in your
+    # setup, because setting LD_LIBRARY_PATH is often a bad idea.  Nevertheless,
+    # it is okay here in Travis, and actually any attempt to change these led me
+    # to linking failures.  Side note: I am not a Linux expert, and you may be
+    # more lucky.
+    #
+    # I'd be happy to get rid of LD_LIBRARY_PATH eventually in some future
+    # pull request.
+    - LD_LIBRARY_PATH="${BOTAN_PREFIX}/lib:${JSONC_PREFIX}/lib:${RNP_PREFIX}/lib"
+    - LD_RUN_PATH="${GPG_PREFIX}/lib"
+
+    - PATH="${RNP_PREFIX}/bin:${GPG_PREFIX}/bin:${PATH}"
+
+    # Many of these are supported only in few GPG components, hence bunch of
+    # harmless warnings typically shows up.
+    - >
+      GPG_CONFIGURE_OPTS="--disable-doc --enable-pinentry-curses
+      --disable-pinentry-emacs --disable-pinentry-gtk2 --disable-pinentry-gnome3
+      --disable-pinentry-qt --disable-pinentry-qt4 --disable-pinentry-qt5
+      --disable-pinentry-tqt --disable-pinentry-fltk
+      --prefix=${GPG_PREFIX}
+      --with-libgpg-error-prefix=${GPG_PREFIX}
+      --with-libassuan-prefix=${GPG_PREFIX}
+      --with-libgpg-error-prefix=${GPG_PREFIX}
+      --with-libgcrypt-prefix=${GPG_PREFIX}
+      --with-libassuan-prefix=${GPG_PREFIX}
+      --with-ksba-prefix=${GPG_PREFIX}
+      --with-npth-prefix=${GPG_PREFIX}"
+
+before_install:
+  - mkdir -p ${DEPS_PREFIX}
+  - pushd ci/gpg
+  - >
+    ./install_gpg_all.sh
+    --suite-version "${GPG_VERSION}"
+    --build-dir "${DEPS_BUILD_DIR}/gpg"
+    --configure-opts "${GPG_CONFIGURE_OPTS}"
+    --folding-style travis
+  - popd
+  - pushd ci
+  - ./install_botan.sh
+  - ./install_json_c.sh
+  - ./install_rnp.sh
+  - popd
+  - gem install bundler -v "~> 2.0"
+
+before_script:
+  - bundle exec rake pgp_keys:generate
+  - bundle exec rake pgp_keys:list
+
+script:
+  - bundle exec rspec --format documentation --profile 200
+
+matrix:
+  include:
+    - env: TEST_WITHOUT_RNP="1"
+    - env: TEST_WITHOUT_GPGME="1"
+
+  allow_failures:
+    - rvm: ruby-head

data/.yardopts

@@ -0,0 +1,6 @@
+-
+README.adoc
+CODE_OF_CONDUCT.md
+LICENSE.txt
+docs/GPGMEAdapter.adoc
+docs/RNPAdapter.adoc

data/Gemfile

@@ -1,4 +1,13 @@
-source 'https://rubygems.org'
+# (c) Copyright 2018 Ribose Inc.
+#
+
+source "https://rubygems.org"
 
 # Specify your gem's dependencies in enmail.gemspec
 gemspec
+
+gem "codecov", require: false, group: :test
+gem "simplecov", require: false, group: :test
+
+gem "gpgme", install_if: -> { !ENV["TEST_WITHOUT_GPGME"] }
+gem "rnp", install_if: -> { !ENV["TEST_WITHOUT_RNP"] }

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2018 Ribose Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.adoc

@@ -0,0 +1,150 @@
+= EnMail
+
+ifdef::env-github[]
+image:https://img.shields.io/gem/v/enmail.svg[
+	Gem Version, link="https://rubygems.org/gems/enmail"]
+image:https://img.shields.io/travis/riboseinc/enmail/master.svg[
+	Build Status, link="https://travis-ci.org/riboseinc/enmail/branches"]
+image:https://img.shields.io/codecov/c/github/riboseinc/enmail.svg[
+	Test Coverage, link="https://codecov.io/gh/riboseinc/enmail"]
+image:https://img.shields.io/codeclimate/maintainability/riboseinc/enmail.svg[
+	"Code Climate", link="https://codeclimate.com/github/riboseinc/enmail"]
+endif::[]
+
+EnMail (encrypted mail) signs or encrypts correspondence sent via the Ruby
+https://rubygems.org/gems/mail[mail] gem.
+
+EnMail has open architecture.  Multiple adapters are supported, and new ones
+can be implemented with ease.  Currently, GPGME and RNP adapters are available
+out of the box.  Both implement OpenPGP standard.
+
+== Basic usage
+
+Given some e-mail:
+
+[source,ruby]
+----
+mail = Mail.new
+mail.from = "Very Myself <me@example.com>"
+mail.to = "Someone Else <someone@example.com>"
+mail.subject = "It is very important"
+mail.body = "Or, whatever"
+
+adapter = ::EnMail::Adapters::RNP
+
+# sign message
+EnMail.protect :sign, mail, adapter: adapter
+
+# encrypt message
+EnMail.protect :encrypt, mail, adapter: adapter
+
+# sign and encrypt message
+EnMail.protect :sign_and_encrypt_encapsulated, mail, adapter: adapter
+
+# or
+EnMail.protect :sign_and_encrypt_combined, mail, adapter: adapter
+----
+
+== Adapters
+
+.Adapter features comparison
+[options="header"]
+|=======
+|                    | GPGME    | RNP
+| Protocol           | Open PGP | Open PGP
+| Supporting library | https://gnupg.org/software/gpgme/index.html[GnuPG Made Easy] | https://www.rnpgp.com/[RNP]
+| Native extensions  | yes      | yes, from https://github.com/ffi/ffi[FFI]
+| Sign               | yes      | yes
+| Encrypt            | yes      | yes
+| Sign and encrypt   | yes, encapsulated and combined | yes, encapsulated and combined
+| Password-protected keys | yes, password must be a String | yes, password must be a String or Proc
+| Bugs, issues and feature requests | https://github.com/riboseinc/enmail/issues?q=is%3Aissue+is%3Aopen+label%3A%22adapter%3A+gpgme%22[See GitHub] | https://github.com/riboseinc/enmail/issues?q=is%3Aissue+is%3Aopen+label%3A%22adapter%3A+rnp%22[See GitHub]
+|=======
+
+See adapter-specific guides for details:
+
+ifdef::env-browser,env-github[]
+* <<docs/GPGMEAdapter.adoc#,GPGME>>
+* <<docs/RNPAdapter.adoc#,RNP>>
+endif::[]
+ifndef::env-browser,env-github[]
+* {file:docs/GPGMEAdapter.adoc}
+* {file:docs/RNPAdapter.adoc}
+endif::[]
+
+== Development
+
+=== Setup
+
+Clone the repository.
+
+[source,sh]
+----
+git clone https://github.com/riboseinc/enmail
+----
+
+NOTE: GnuPG will create UNIX sockets in the `<project_root>/tmp/pgp_home`
+directory.  Be advised that paths to UNIX sockets have limited length (about 100
+characters).  Therefore, please ensure that path to directory you are cloning
+repository into is less than 50 characters long, or you may experience weird
+errors.
+
+Setup your environment.
+
+[source,sh]
+----
+bin/setup
+----
+
+Above one will take a short while.  As the final step, tests will be run
+in order to prove your setup's correctness.
+
+=== Regenerating OpenPGP keys
+
+If you ever need to regenerate your development OpenPGP keys, execute:
+
+[source,sh]
+----
+bundle exec rake pgp_keys:regenerate
+----
+
+NOTE: Always run tests after pulling new changes from the upstream.  If they
+fail, it's likely that OpenPGP keys should be regenerated.
+
+=== Submodules
+
+GnuPG is installed in Travis CI via scripts maintained in a sister repository
+https://github.com/riboseinc/gpg-build-scripts[riboseinc/gpg-build-scripts],
+and included here as a Git submodule.  Learn more about submodules from
+https://blog.github.com/2016-02-01-working-with-submodules/[The GitHub Blog].
+
+=== Contributing
+
+First, thank you for contributing! We love pull requests from everyone.
+By participating in this project, you hereby grant
+https://www.ribose.com[Ribose Inc.] the right to grant or transfer an
+unlimited number of non exclusive licenses or sub-licenses to third
+parties, under the copyright covering the contribution to use the
+contribution by all means.
+
+Here are a few technical guidelines to follow:
+
+1.  Open an https://github.com/riboseinc/enmail/issues[issue] to discuss
+    a new feature.
+2.  Write tests to support your new feature.
+3.  Make sure the entire test suite passes locally and on CI.
+4.  Open a Pull Request.
+5.  After receiving feedback, perform
+    https://help.github.com/articles/about-git-rebase/[an interactive rebase]
+    on your branch, in order to create a series of cohesive commits with
+    descriptive messages.
+6.  Party!
+
+== Credits
+
+This gem is developed, maintained and funded by
+https://www.ribose.com[Ribose Inc.]
+
+== License
+
+This gem is licensed under MIT license.

data/Rakefile

@@ -1,6 +1,125 @@
+# (c) Copyright 2018 Ribose Inc.
+#
+
 require "bundler/gem_tasks"
 require "rspec/core/rake_task"
 
+require "tempfile"
+
 RSpec::Core::RakeTask.new(:spec)
 
 task :default => :spec
+
+namespace :pgp_keys do
+  def init_homedir_if_missing
+    return if Dir.exists?(TMP_PGP_HOME)
+
+    FileUtils.mkdir_p(TMP_PGP_HOME)
+
+    File.write(File.join(TMP_PGP_HOME, "gpg.conf"), <<~GPGCONF)
+      personal-digest-preferences SHA512
+    GPGCONF
+
+    File.write(File.join(TMP_PGP_HOME, "gpg-agent.conf"), <<~AGENTCONF)
+      default-cache-ttl 0
+    AGENTCONF
+  end
+
+  def execute_gpg(*options)
+    init_homedir_if_missing
+    common_options = ["--no-permission-warning", "--homedir", TMP_PGP_HOME]
+    cmd = ["gpg", *common_options, *options]
+    system(*cmd)
+  end
+
+  # Available parameters for unattended GPG key generation are described here:
+  # https://www.gnupg.org/documentation/manuals/gnupg/Unattended-GPG-key-generation.html
+  def generate_pgp_keys(key_params)
+    Tempfile.create("gnupg-key-params") do |key_params_file|
+      key_params_file.write(key_params)
+      key_params_file.close
+      execute_gpg("--batch", "--gen-key", in: key_params_file.path)
+    end
+  end
+
+  desc "Lists keys in tmp/pgp_home"
+  task :list => :prepare do
+    execute_gpg "--list-keys"
+  end
+
+  desc "Stops all GPG daemons, and deletes tmp/pgp_home"
+  task :clear => :prepare do
+    if File.exists?(TMP_PGP_HOME)
+      system "gpgconf", "--homedir", TMP_PGP_HOME, "--kill", "all"
+      FileUtils.remove_entry_secure TMP_PGP_HOME
+    end
+  end
+
+  desc "Clears tmp/pgp_home, and generates new set of keys"
+  task :regenerate => %i[clear generate]
+
+  desc "Generates keys in tmp/pgp_home"
+  task :generate => :prepare do
+    # Key pairs without password
+    generate_pgp_keys(<<~KEY_PARAMS)
+      %no-protection
+      Key-Type: RSA
+      Key-Usage: sign, cert
+      Key-Length: 2048
+      Subkey-Type: RSA
+      Subkey-Length: 2048
+      Subkey-Usage: encrypt
+      Name-Real: Some Arbitrary Key
+      Name-Email: whatever@example.test
+      Name-Comment: Without passphrase
+      Expire-Date: 0
+    KEY_PARAMS
+
+    generate_pgp_keys(<<~KEY_PARAMS)
+      %no-protection
+      Key-Type: RSA
+      Key-Usage: sign, cert
+      Key-Length: 2048
+      Subkey-Type: RSA
+      Subkey-Length: 2048
+      Subkey-Usage: encrypt
+      Name-Real: Cato Elder
+      Name-Email: cato.elder@example.test
+      Name-Comment: Without passphrase
+      Expire-Date: 0
+    KEY_PARAMS
+
+    generate_pgp_keys(<<~KEY_PARAMS)
+      %no-protection
+      Key-Type: RSA
+      Key-Usage: sign, cert
+      Key-Length: 2048
+      Subkey-Type: RSA
+      Subkey-Length: 2048
+      Subkey-Usage: encrypt
+      Name-Real: Roman Senate
+      Name-Email: senate@example.test
+      Name-Comment: Without passphrase
+      Expire-Date: 0
+    KEY_PARAMS
+
+    # Password-protected key pairs
+    generate_pgp_keys(<<~KEY_PARAMS)
+      Key-Type: RSA
+      Key-Usage: sign, cert
+      Key-Length: 2048
+      Subkey-Type: RSA
+      Subkey-Length: 2048
+      Subkey-Usage: encrypt
+      Name-Real: Cato Elder
+      Name-Email: cato.elder+pwd@example.test
+      Name-Comment: Password-protected
+      Expire-Date: 0
+      Passphrase: 1234
+    KEY_PARAMS
+  end
+end
+
+task :prepare do
+  require_relative "./spec/support/0_tmp_pgp_home"
+end

data/bin/rspec

@@ -1,5 +1,6 @@
 #!/usr/bin/env ruby
 # frozen_string_literal: true
+
 #
 # This file was generated by Bundler.
 #

data/bin/setup

@@ -3,6 +3,23 @@ set -euo pipefail
 IFS=$'\n\t'
 set -vx
 
+########################################
+#      Installing required gems...     #
+########################################
+
 bundle install
 
-# Do any other automated setup that you need to do here
+########################################
+#       Generating Open PGP keys       #
+#             with GnuPG...            #
+########################################
+
+bundle exec rake pgp_keys:generate pgp_keys:list
+
+########################################
+#          Validating setup...         #
+#     (tests should pass as long as    #
+#            they do in CI)            #
+########################################
+
+bundle exec rspec

data/ci/install_botan.sh

@@ -0,0 +1,28 @@
+#!/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}"
+
+botan_build="${DEPS_BUILD_DIR}/botan"
+
+if [ ! -e "${BOTAN_PREFIX}/lib/libbotan-2.so" ] && \
+	 [ ! -e "${BOTAN_PREFIX}/lib/libbotan-2.dylib" ]; then
+
+	if [ -d "${botan_build}" ]; then
+		rm -rf "${botan_build}"
+	fi
+
+	git clone --depth 1 https://github.com/randombit/botan "${botan_build}"
+	pushd "${botan_build}"
+	./configure.py --prefix="${BOTAN_PREFIX}" --with-debug-info --cxxflags="-fno-omit-frame-pointer"
+	${MAKE} -j${CORES} install
+	popd
+fi