hkp_client 0.1.0

data/.rubocop.yml

@@ -0,0 +1,26 @@
+# This project follows the Ribose OSS style guide.
+# https://github.com/riboseinc/oss-guides
+# All project-specific additions and overrides should be specified in this file.
+
+inherit_from:
+  # Thoughtbot's style guide from: https://github.com/thoughtbot/guides
+  - ".rubocop.tb.yml"
+  # Overrides from Ribose
+  - ".rubocop.ribose.yml"
+AllCops:
+  DisplayCopNames: false
+  StyleGuideCopsOnly: false
+  TargetRubyVersion: 2.3
+Rails:
+  Enabled: false
+
+Style/EmptyCaseCondition:
+  Enabled: false
+
+Style/TrailingCommaInArguments:
+  Exclude:
+    # RSpec expectations can easily go multiline.  And sometimes, it's all not
+    # about multiple arguments, but more about & or | operators.  Comma placed
+    # after a single method argument which spans across many lines is confusing,
+    # not helpful.  Hence, I'm disabling this cop for all specs.
+    - "spec/**/*"

data/.travis.yml

@@ -0,0 +1,17 @@
+dist: trusty
+language: ruby
+sudo: false
+
+before_install:
+  - gem install bundler -v 1.16.1
+
+rvm:
+  - 2.5
+  - 2.4
+  - 2.3
+  - 2.2
+  - ruby-head
+
+matrix:
+  allow_failures:
+    - rvm: ruby-head

data/Gemfile

@@ -0,0 +1,9 @@
+source "https://rubygems.org"
+
+git_source(:github) { |repo_name| "https://github.com/#{repo_name}" }
+
+# Specify your gem's dependencies in hkp_client.gemspec
+gemspec
+
+gem "codecov", require: false, group: :test
+gem "simplecov", require: false, group: :test

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,168 @@
+HKP Client
+==========
+
+image:https://img.shields.io/gem/v/hkp_client.svg["Gem Version", link="https://rubygems.org/gems/hkp_client"]
+image:https://img.shields.io/travis/riboseinc/hkp_client/master.svg["Build Status", link="https://travis-ci.org/riboseinc/hkp_client"]
+image:https://img.shields.io/codecov/c/github/riboseinc/hkp_client.svg["Test Coverage", link="https://codecov.io/gh/riboseinc/hkp_client"]
+image:https://img.shields.io/codeclimate/maintainability/riboseinc/hkp_client.svg["Maintainability", link="https://codeclimate.com/github/riboseinc/hkp_client/maintainability"]
+
+:source-highlighter: pygments
+
+HKP Client is a minimalist HKP (OpenPGP HTTP Keyserver Protocol) client, which
+queries PGP public keyservers, and downloads public keys.  It does not support
+submitting keys to keyserver.
+
+NOTE: This gem registers +hkp+, and +hkps+ URI schemes (adds them to
++URI.scheme_list+).
+
+Usage
+-----
+
+Searching
+~~~~~~~~~
+
+Searching by some criteria.  Returns search results as an array of arrays.
+
+For exact searches, an +exact+ option can be set to true.  The meaning of
+"exact" is not defined by standard, and may be ignored by servers.
+
+[source,lang=ruby]
+--------------------------------------------------------------------------------
+HkpClient.search "linus@example.com"
+HkpClient.search "linus@example.com", exact: true
+--------------------------------------------------------------------------------
+
+Search operations returns an array of hashes.  In this case, it is a one-element
+array:
+
+[source,lang=ruby]
+--------------------------------------------------------------------------------
+[
+  {
+    :key_id=>"06DA6D18CED048CE87E3E3A01CBBDA571B331AB5",
+    :algorithm=>"1",
+    :key_length=>"2048",
+    :creation_date=>"1507718293",
+    :expiration_date=>nil,
+    :flags=>nil,
+    :uids=>[
+      {
+        :name=>"Linus Torvalds (Example) <linus@example.com>",
+        :creation_date=>"1507718293",
+        :expiration_date=>nil,
+        :flags=>nil
+      }
+    ]
+  }
+]
+--------------------------------------------------------------------------------
+
+Each array item describes a primary key uploaded to keyserver, and is associated
+with one or more UIDs.  For field descriptions, refer to
+https://tools.ietf.org/html/draft-shaw-openpgp-hkp-00#section-5.2[HKP draft,
+section 5.2].
+
+UID's name is already percent-decoded.  Other values may require parsing or
+casting (e.g. timestamps and numbers).
+
+Search results may include expired keys.  If that's unwanted, these keys must
+be filtered out by user.
+
+Fetching keys
+~~~~~~~~~~~~~
+
+Operation returns the ASCII-armored keyring as defined in
+https://tools.ietf.org/html/rfc2440#section-11.1[RFC 2440, section 11.1],
+or +nil+.
+
+For example, executing following snippet:
+
+[source,lang=ruby]
+--------------------------------------------------------------------------------
+HkpClient.get "linus@example.com"
+--------------------------------------------------------------------------------
+
+will return string similar to:
+
+--------------------------------------------------------------------------------
+-----BEGIN PGP PUBLIC KEY BLOCK-----
+Version: SKS 1.1.6
+Comment: Hostname: pgp.lehigh.edu
+
+mQENBFnd9JUBCAC1NMfsImuRAUcsKEjdLlSj0THHNytUDE8CB2I728gJAeixdZMEcPpRKHfc
+BXjW+Q864S4yEY4xgaboFkg/qABA/o0PWzZn2AzhvD5gzrfpfvK4BMrgOtPya7MySgImG1NC
+UYqj2vvJt4/bh8MWxSqvADB3SfLNueBQGvISeGwss9kYHEqoP0lxNSEJPJJpLKeqSov7mZOz
+(…)
+c2gFngOSVOrxJswb8/BUkA==
+=jGC1
+-----END PGP PUBLIC KEY BLOCK-----
+--------------------------------------------------------------------------------
+
+Arbitrary queries
+~~~~~~~~~~~~~~~~~
+
+When above two methods are not flexible enough, a +\#query+ method can be
+called.  It returns an instance of +Faraday::Response+.  All the arguments
+become query string parameters (with exception of +keyserver+, which is
+described in the next section).
+
+For example, a following snippet performs a +vindex+ operation for
++linus@example.com+ query.  The +mr+ option specifies that search results should
+be presented in a machine-readable format.  By default, a human-readable format
+is used, typically HTML.
+
+[source,lang=ruby]
+--------------------------------------------------------------------------------
+HkpClient.query(op: "vindex", search: "linus@example.com", options: "mr")
+--------------------------------------------------------------------------------
+
+Using custom keyserver
+~~~~~~~~~~~~~~~~~~~~~~
+
+A +keyserver+ option can be passed to either +\#search+, +\#get+, or +\#query+
+method.  Accepted URI schemes are +http+, +https+, +hkp+, and +hkps+.
+
+TODO: Easy support for custom certificates.
+
+[source,lang=ruby]
+--------------------------------------------------------------------------------
+HkpClient.get "linus@example.com", keyserver: "hkp://server.you.want:8888"
+--------------------------------------------------------------------------------
+
+Contributing
+------------
+
+First, thank you for contributing!  We love pull requests from everyone.
+By participating in this project, you hereby grant 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 issue to discuss a new feature prior implementing it.
+2.  Write tests for new features or bugfixes.
+3.  Make sure the entire test suite passes locally and on CI.
+4.  Follow our style guide (you can validate your contribution locally with
+    Rubocop, also Hound CI will report any offences when you open a pull
+    request).
+
+Credits
+-------
+
+This gem is developed, maintained and funded by
+https://www.ribose.com[Ribose Inc].
+
+License
+-------
+
+The gem is available as open source under the terms of the
+https://opensource.org/licenses/MIT[MIT License].
+
+Resources
+---------
+
+- https://tools.ietf.org/html/draft-shaw-openpgp-hkp-00[HKP protocol definition (IETF draft)]
+- http://www.mit.edu/afs/net.mit.edu/project/pks/thesis/paper/thesis.html[A PGP Public Key Server thesis]
+- https://www.openpgp.org/about/standard/[More documents on OpenPGP]
+- https://sks-keyservers.net/[SKS keyservers]

data/Rakefile

@@ -0,0 +1,6 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec # rubocop:disable Style/HashSyntax

data/bin/console

@@ -0,0 +1,10 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "hkp_client"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+require "pry"
+Pry.start

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/hkp_client.gemspec

@@ -0,0 +1,34 @@
+
+lib = File.expand_path("lib", __dir__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require "hkp_client/version"
+
+Gem::Specification.new do |spec|
+  spec.name          = "hkp_client"
+  spec.version       = HkpClient::VERSION
+  spec.authors       = ["Ribose Inc."]
+  spec.email         = ["open.source@ribose.com"]
+
+  spec.summary       = "A minimalist client for PGP public keyservers."
+  spec.description   = "A minimalist HKP (OpenPGP HTTP Keyserver Protocol) " \
+                       "client, which queries PGP public keyservers, " \
+                       "and downloads public keys."
+  spec.homepage      = "https://github.com/riboseinc/hkp_client"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files -z`.split("\x0").reject do |f|
+    f.match(%r{^(test|spec|features)/})
+  end
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_runtime_dependency "faraday"
+
+  spec.add_development_dependency "bundler", "~> 1.16"
+  spec.add_development_dependency "pry", "~> 0.11.0"
+  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "rspec", "~> 3.0"
+  spec.add_development_dependency "vcr", "~> 4.0"
+  spec.add_development_dependency "webmock"
+end

data/lib/hkp_client.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+require "hkp_client/version"
+require "hkp_client/uri_schemes"
+
+require "faraday"
+require "uri"
+
+module HkpClient
+  DEFAULT_KEYSERVER = URI("hkp://pool.sks-keyservers.net").freeze
+
+  class Error < StandardError; end
+
+  PUB_ENTRY_FIELDS =
+    %i[key_id algorithm key_length creation_date expiration_date flags].freeze
+
+  UID_ENTRY_FIELDS =
+    %i[name creation_date expiration_date flags].freeze
+
+  module_function
+
+  # Fetches a keyring containing open PGP keys from keyserver, and returns it
+  # as an ASCII-armoured string.
+  #
+  # @param string [String] a search string
+  # @param keyserver (see #query)
+  # @return [String] keyring
+  # @return [nil] if key could not be found
+  # @raise [HkpClient::Error] if server responds with different HTTP code than
+  #   200 or 404
+  # @raise any other exceptions caused by networking problems
+  def get(string, keyserver: DEFAULT_KEYSERVER, exact: false)
+    resp = query(
+      keyserver: keyserver,
+      op: "get",
+      search: string,
+      options: "mr",
+      exact: (exact ? "on" : "off"),
+    )
+
+    Util.response_body_or_error_or_nil(resp)
+  end
+
+  # Performs a search query on keyserver, and returns a list of key
+  # descriptions (see README for details).
+  #
+  # @param string (see #get)
+  # @param exact [Boolean] whether to perform an "exact" search
+  # @param keyserver (see #query)
+  # @return [Array<Hash>] list of found keys, possibly empty
+  # @raise [HkpClient::Error] if server responds with different HTTP code than
+  #   200 or 404
+  # @raise any other exceptions caused by networking problems
+  def search(string, keyserver: DEFAULT_KEYSERVER, exact: false)
+    resp = query(
+      keyserver: keyserver,
+      op: "index",
+      search: string,
+      options: "mr",
+      exact: (exact ? "on" : "off"),
+    )
+
+    resp_body = Util.response_body_or_error_or_nil(resp) || ""
+    Util.parse_search_response_entries(resp_body)
+  end
+
+  # Makes a query to keyserver.  Any surplus keyword arguments will be used
+  # as request parameters.
+  #
+  # @param keyserver [String] a keyserver to query
+  # @return [Faraday::Response]
+  # @raise any exceptions caused by networking problems
+  def query(keyserver: DEFAULT_KEYSERVER, **query_args)
+    uri = (URI === keyserver ? keyserver.dup : URI.parse(keyserver))
+    use_ssl = %w[https hkps].include?(uri.scheme)
+    Faraday.new(url: uri, ssl: use_ssl).get("/pks/lookup", query_args)
+  end
+
+  # Utilities to be considered as kinda private API.
+  module Util
+    module_function
+
+    def response_body_or_error_or_nil(resp)
+      if resp.success?
+        resp.body
+      elsif resp.status == 404
+        nil
+      else
+        raise Error, "Server responded with #{resp.status}"
+      end
+    end
+
+    # rubocop:disable Metrics/MethodLength
+
+    def parse_search_response_entries(src_string)
+      src_string.each_line.reduce([]) do |found_keys, line|
+        case line
+        when /\Apub:/
+          key = response_line_to_hash(line, PUB_ENTRY_FIELDS)
+          key[:uids] = []
+          found_keys << key
+        when /\Auid:/
+          uid = response_line_to_hash(line, UID_ENTRY_FIELDS)
+          uid[:name] = CGI.unescape(uid[:name])
+          found_keys.last[:uids] << uid
+        end
+        found_keys
+      end
+    end
+    # rubocop:enable Metrics/MethodLength
+
+    def response_line_to_hash(line, field_names)
+      _line_type, *fields = line.strip.split(":")
+      fields.push(nil) while fields.length < field_names.length
+      [field_names, fields].transpose.to_h
+    end
+  end
+end

data/lib/hkp_client/uri_schemes.rb

@@ -0,0 +1,14 @@
+require "uri"
+
+module URI
+  class HKP < HTTP
+    DEFAULT_PORT = 11371
+  end
+
+  class HKPS < HTTPS
+    DEFAULT_PORT = 443
+  end
+end
+
+URI.scheme_list["HKP".freeze] ||= URI::HKP
+URI.scheme_list["HKPS".freeze] ||= URI::HKPS

data/lib/hkp_client/version.rb

@@ -0,0 +1,3 @@
+module HkpClient
+  VERSION = "0.1.0".freeze
+end