pwnedkeys-api-client 0.1.0

data/README.md

@@ -0,0 +1,74 @@
+This is a library for querying the [pwnedkeys.com](https://pwnedkeys.com) API.
+It allows you to provide a public key, and determine whether or not the
+corresponding public key has ever been exposed to the public, rendering it
+permanently unsafe to use.
+
+Due to recent changes in the `openssl` standard library, this code requires
+at least Ruby 2.5 to run.
+
+
+# Installation
+
+It's a gem!
+
+    gem install pwnedkeys-api-client
+
+If you're the sturdy type that likes to run from git:
+
+    rake install
+
+Or, if you've eschewed the convenience of Rubygems entirely, then you
+presumably know what to do already.
+
+
+# Usage
+
+To query for a pwned key, simply create a new `Pwnedkeys::Request`, passing in
+the public key you want to query for:
+
+    require "pwnedkeys/request"
+
+    key = OpenSSL::PKey.read("/tmp/suss_key")
+	query = Pwnedkeys::Request.new(key)
+
+Then, just ask whether it's pwned!
+
+    query.pwned?
+
+You'll get back a `true` or `false` answer in next-to-no-time.  If any problems
+crop up (like the signature can't be validated, or the API doesn't respond) you'll
+get a `Pwnedkeys::Request::Error` exception.
+
+
+# Contributing
+
+See `CONTRIBUTING.md`.
+
+
+# Licence
+
+Unless otherwise stated, everything in this repo is covered by the following
+copyright notice:
+
+    Copyright (C) 2018  Matt Palmer <matt@hezmatt.org>
+
+    This program is free software: you can redistribute it and/or modify it
+    under the terms of the GNU General Public License version 3, as
+    published by the Free Software Foundation.
+
+    This program is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+    GNU General Public License for more details.
+
+    You should have received a copy of the GNU General Public License
+    along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+	In addition, as a special exception, the copyright holders give permission
+	to link the code of portions of this program with the OpenSSL library. You
+	must obey the GNU General Public License in all respects for all of the
+	code used other than OpenSSL. If you modify file(s) with this exception,
+	you may extend this exception to your version of the file(s), but you are
+	not obligated to do so. If you do not wish to do so, delete this exception
+	statement from your version. If you delete this exception statement from
+	all source files in the program, then also delete it here.

data/lib/pwnedkeys/request.rb

@@ -0,0 +1,203 @@
+require "base64"
+require "json"
+require "net/http"
+require "openssl"
+
+require "openssl/x509/spki"
+
+# All the keys that are fit to be pwned.
+module Pwnedkeys
+  # Make a query against the pwnedkeys.com API.
+  #
+  class Request
+    # Generic error relating to API requests.
+    #
+    class Error < StandardError; end
+
+    # Raised if the signature on the pwnedkeys response cannot be
+    # validated.  This almost certainly indicates something very wrong
+    # in the API itself, as the correctness of the key is ensured by the
+    # query protocol.
+    #
+    class VerificationError < Error; end
+
+    # Prepare to the make a request to the pwnedkeys API.
+    #
+    # @param spki [OpenSSL::X509::SPKI, OpenSSL::PKey::PKey, String] the
+    #   public key to query for.  Can be provided as a key object itself,
+    #   an SPKI object (most likely derived from an X509 certificate or
+    #   CSR), or a string containing a DER-encoded `SubjectPublicKeyInfo`
+    #   ASN.1 structure.
+    #
+    #   If in doubt, just pass in a key and we'll take care of the rest.
+    #
+    # @raise [Pwnedkeys::Request::Error] if the passed-in key representation
+    #   can't be induced into something useable.
+    #
+    def initialize(spki)
+      @spki = if spki.is_a?(OpenSSL::X509::SPKI)
+        spki
+      elsif spki.is_a?(String)
+        begin
+          OpenSSL::X509::SPKI.new(spki)
+        rescue OpenSSL::ASN1::ASN1Error, OpenSSL::X509::SPKIError
+          raise Error,
+                "Invalid SPKI ASN.1 string"
+        end
+      elsif spki.is_a?(OpenSSL::PKey::PKey)
+        spki.to_spki
+      else
+        raise Error,
+              "Invalid argument type passed to Pwnedkeys::Request.new (need OpenSSL::X509::SPKI, PKey, or string, got #{spki.class})"
+      end
+
+      # Verify key type is OK
+      key_params
+    end
+
+    # Query the pwnedkeys API and tell whether the key is exposed.
+    #
+    # @return [Boolean] whether the key embodied in this request is contained
+    #   within the pwnedkeys database.
+    #
+    # @raise [VerificationError] if a response was provided, but the signature
+    #   on the response was not able to be verified.
+    #
+    # @raise [Error] if the request to the API could not be successfully
+    #   completed.
+    #
+    def pwned?
+      retry_count = 10
+      uri = URI(ENV["PWNEDKEYS_API_URL"] || "https://v1.pwnedkeys.com")
+      uri.path += "/#{@spki.spki_fingerprint.hexdigest}"
+
+      loop do
+        res = Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https") do |http|
+          req = Net::HTTP::Get.new(uri.path)
+          req["User-Agent"] = "pwnedkeys-tools/0.0.0"
+          http.request(req)
+        end
+
+        if res.code == "200"
+          verify!(res.body)
+          return true
+        elsif res.code == "404"
+          return false
+        elsif (500..599) === res.code.to_i && retry_count > 0
+          # Server-side error, let's try a few more times
+          sleep 1
+          retry_count -= 1
+        else
+          raise Error,
+                "Unable to determine pwnage, error status code returned from #{uri}: #{res.code}"
+        end
+      end
+    end
+
+    private
+
+    # Do the dance of the signature verification.
+    #
+    def verify!(res)
+      json = JSON.parse(res)
+      header = JSON.parse(unb64(json["protected"]))
+
+      key = @spki.to_key
+
+      verify_data = "#{json["protected"]}.#{json["payload"]}"
+
+      unless key.verify(hash_func.new, format_sig(unb64(json["signature"])), verify_data)
+        raise VerificationError,
+              "Response signature cannot be validated by provided key"
+      end
+
+      unless header["alg"] == key_alg
+        raise VerificationError,
+              "Incorrect alg parameter.  Got #{header["alg"]}, expected #{key_alg} for #{key.class} key"
+      end
+
+      unless header["kid"] == @spki.spki_fingerprint.hexdigest
+        raise VerificationError,
+              "Key ID in response doesn't match.  Got #{header["kid"]}, expected #{@spki.spki_fingerprint.hexdigest}"
+      end
+
+      unless unb64(json["payload"]) =~ /key is pwned/
+        raise VerificationError,
+              "Response payload does not include magic string 'key is pwned', got #{unb64(json["payload"])}"
+      end
+
+      # The gauntlet has been run and you have been found... worthy
+    end
+
+    # Strip off the base64 barnacles.
+    #
+    def unb64(s)
+      Base64.urlsafe_decode64(s)
+    end
+
+    def key_alg
+      key_params[:key_alg]
+    end
+
+    def hash_func
+      key_params[:hash_func]
+    end
+
+    def format_sig(sig)
+      key_params[:format_sig].call(sig)
+    end
+
+    # Turn a JOSE EC sig into a "proper" EC sig that OpenSSL can use.
+    #
+    def ec_sig(jose_sig)
+      # *Real* EC signatures are a two-element ASN.1 sequence containing
+      # the R and S values.  RFC7518, in its infinite wisdom, has decided that
+      # that is not good enough, and instead it wants the signatures in raw
+      # concatenated R/S as octet strings.  Because of *course* it does.
+      OpenSSL::ASN1::Sequence.new(split_in_two_equal_halves(jose_sig).map do |i|
+        OpenSSL::ASN1::Integer.new(i.unpack("C*").inject(0) { |v, i| v * 256 + i })
+      end).to_der
+    end
+
+    def split_in_two_equal_halves(s)
+      [s[0..(s.length / 2 - 1)], s[(s.length / 2)..(s.length - 1)]]
+    end
+
+    # Return all the relevant parameters required to validate the API response,
+    # based on the type of key being queried.
+    #
+    def key_params
+      case @spki.to_key
+      when OpenSSL::PKey::RSA then {
+        key_alg: "RS256",
+        hash_func: OpenSSL::Digest::SHA256,
+        format_sig: ->(sig) { sig },
+      }
+      when OpenSSL::PKey::EC
+        case @spki.to_key.public_key.group.curve_name
+        when "prime256v1" then {
+          key_alg: "ES256",
+          hash_func: OpenSSL::Digest::SHA256,
+          format_sig: ->(sig) { ec_sig(sig) },
+        }
+        when "secp384r1"  then {
+          key_alg: "ES384",
+          hash_func: OpenSSL::Digest::SHA384,
+          format_sig: ->(sig) { ec_sig(sig) },
+        }
+        when "secp521r1"  then {
+          key_alg: "ES512",
+          hash_func: OpenSSL::Digest::SHA512,
+          # The components of P-521 keys are 521 bits each, which is padded
+          # out to be 528 bits -- 66 octets.
+          format_sig: ->(sig) { ec_sig(sig) },
+        }
+        else
+          raise Error, "EC key containing unsupported curve #{@spki.to_key.group.curve_name}"
+        end
+      else
+        raise Error, "Unsupported key type #{@key.class}"
+      end
+    end
+  end
+end

data/lib/pwnedkeys/response.rb

@@ -0,0 +1,146 @@
+require "base64"
+require "json"
+require "openssl"
+
+require "openssl/x509/spki"
+
+module Pwnedkeys
+  # Generate a v1 compromise attestation.
+  #
+  class Response
+    # Raised in the event of any inability to generate the response.
+    #
+    class Error < StandardError; end
+
+    # Create a new response.
+    #
+    # @param key [OpenSSL::PKey::PKey, String] the key for which to generate
+    #   the compromise attestation.  It can either be an OpenSSL key object
+    #   itself, or a string that `OpenSSL::PKey.read` will accept (so
+    #   a PEM or DER format PKCS#8-like key).
+    #
+    # @raise [Error] if an invalid argument type was passed, or if the key
+    #   given is not, in fact, a private key.
+    #
+    def initialize(key)
+      @key = if key.kind_of?(OpenSSL::PKey::PKey)
+        key
+      elsif key.is_a?(String)
+        begin
+          OpenSSL::PKey.read(key)
+        rescue OpenSSL::PKey::PKeyError
+          raise Error,
+                "Unable to parse provided key data"
+        end
+      else
+        raise Error,
+              "Invalid argument type passed to Pwnedkeys::Response.new (need OpenSSL::PKey::PKey or string, got #{key.class})"
+      end
+
+      unless @key.private?
+        raise Error,
+              "Provided key is not a private key."
+      end
+    end
+
+    # Produce a JSON format compromise attestation.
+    #
+    # @param spki_format [Object] some key types (specifically, ECDSA keys) can
+    #   generate multiple formats of public key info, which hash to different
+    #   key fingerprints.  This parameter allows you to specify which format of
+    #   SPKI should be generated.  See the relevant key type's `#to_spki`
+    #   method to see what the valid values are.
+    #
+    # @return [String] the JSON response body, which is a JSON Web Signature
+    #   containing proof of possession of the private key.
+    #
+    def to_json(*spki_format)
+      header = {
+        alg: key_alg,
+        kid: @key.to_spki(*spki_format).spki_fingerprint.hexdigest,
+      }
+
+      obj = {
+        payload:   b64("This key is pwned!  See https://pwnedkeys.com for more info."),
+        protected: b64(header.to_json),
+      }
+
+      obj[:signature] = b64(sign(obj))
+      obj.to_json
+    end
+
+    private
+
+    # URL-safe base64 encoding.
+    #
+    def b64(s)
+      Base64.urlsafe_encode64(s).sub(/=*\z/, '')
+    end
+
+    def key_alg
+      key_params[:key_alg]
+    end
+
+    def hash_func
+      key_params[:hash_func]
+    end
+
+    def format_sig(sig)
+      key_params[:format_sig].call(sig)
+    end
+
+    # Turn an OpenSSL-style ECDSA signature into the frankly unhinged form
+    # required by JOSE.
+    #
+    def jose_sig(ec_sig, len)
+      # EC signatures are a two-element ASN.1 sequence containing
+      # the R and S values.  RFC7518, in its infinite wisdom, has decided that
+      # that is not good enough, and instead it wants the signatures in raw
+      # concatenated R/S as octet strings.  Because of *course* it does.
+      OpenSSL::ASN1.decode(ec_sig).value.map { |n| [sprintf("%0#{len * 2}x", n.value)].pack("H*") }.join
+    end
+
+    # Return all the relevant parameters required to generate the JWS, based
+    # on the type of key we're dealing with.
+    #
+    def key_params
+      case @key
+      when OpenSSL::PKey::RSA then {
+        key_alg: "RS256",
+        hash_func: OpenSSL::Digest::SHA256,
+        format_sig: ->(sig) { sig },
+      }
+      when OpenSSL::PKey::EC
+        case @key.public_key.group.curve_name
+        when "prime256v1" then {
+          key_alg: "ES256",
+          hash_func: OpenSSL::Digest::SHA256,
+          format_sig: ->(sig) { jose_sig(sig, 32) },
+        }
+        when "secp384r1"  then {
+          key_alg: "ES384",
+          hash_func: OpenSSL::Digest::SHA384,
+          format_sig: ->(sig) { jose_sig(sig, 48) },
+        }
+        when "secp521r1"  then {
+          key_alg: "ES512",
+          hash_func: OpenSSL::Digest::SHA512,
+          # The components of P-521 keys are 521 bits each, which is padded
+          # out to be 528 bits -- 66 octets.
+          format_sig: ->(sig) { jose_sig(sig, 66) },
+        }
+        else
+          raise Error, "EC key containing unsupported curve #{@key.public_key.group.curve_name}"
+        end
+      else
+        raise Error, "Unsupported key type #{@key.class}"
+      end
+    end
+
+    # Generate the signature over the signable parts of the JWS.
+    #
+    def sign(obj)
+      format_sig(@key.sign(hash_func.new, obj[:protected] + "." + obj[:payload]))
+    end
+  end
+end

data/pwnedkeys-api-client.gemspec

@@ -0,0 +1,37 @@
+begin
+  require 'git-version-bump'
+rescue LoadError
+  nil
+end
+
+Gem::Specification.new do |s|
+  s.name = "pwnedkeys-api-client"
+
+  s.version = GVB.version rescue "0.0.0.1.NOGVB"
+  s.date    = GVB.date    rescue Time.now.strftime("%Y-%m-%d")
+
+  s.platform = Gem::Platform::RUBY
+
+  s.summary  = "Library to query the pwnedkeys.com API"
+
+  s.authors  = ["Matt Palmer"]
+  s.email    = ["matt@hezmatt.org"]
+  s.homepage = "https://github.com/pwnedkeys/pwnedkeys-api-client"
+
+  s.files = `git ls-files -z`.split("\0").reject { |f| f =~ /^(\.|G|spec|Rakefile)/ }
+
+  s.required_ruby_version = ">= 2.5.0"
+
+  s.add_runtime_dependency "openssl-additions"
+
+  s.add_development_dependency 'bundler'
+  s.add_development_dependency 'github-release'
+  s.add_development_dependency 'git-version-bump'
+  s.add_development_dependency 'guard-rspec'
+  s.add_development_dependency 'rack-test'
+  s.add_development_dependency 'rake', "~> 12.0"
+  s.add_development_dependency 'redcarpet'
+  s.add_development_dependency 'rspec'
+  s.add_development_dependency 'simplecov'
+  s.add_development_dependency 'yard'
+end