pwnedkeys-tools 0.1.0

data/README.md

@@ -0,0 +1,109 @@
+This is a collection of command-line tools and utility classes which are useful
+for interacting with the [pwnedkeys.com](https://pwnedkeys.com) compromised key
+database.  You can search the database to determine whether a key you have is
+compromised, or create a signed attestation of compromise for a key you have.
+
+These tools are all written in Ruby, and require a fairly modern Ruby installation
+(version 2.5 or later).  If you have such a setup, you can [install the tools
+as a gem](#installation).  Otherwise, if you have Docker, you can [use the
+wrapper scripts to run the tools via a docker container](#docker-wrapper-scripts).
+
+
+# Installation
+
+Due to recent changes in the `openssl` standard library, the tools require
+Ruby 2.5 or later with the `openssl` extension.  Assuming you've got that
+available, you can install the tools as a gem:
+
+    gem install pwnedkeys-tools
+
+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.
+
+
+## Docker Wrapper Scripts
+
+For those of you who don't have a bleeding edge Ruby installation laying
+around, but *do* have a Docker installation, you can copy the scripts in
+the `docker-wrappers` subdirectory into a directory in your `PATH`, and
+you'll be ready to go.
+
+
+# Usage
+
+Whether you're running as a gem or via Docker, the command line tools have the
+same names and usage.
+
+## Query for a pwned key
+
+Run `pwnedkeys-query`, passing a public or private key, CSR, or X.509 certificate
+via `stdin`:
+
+    pwnedkeys-query < /etc/ssl/certs/ssl-cert-snakeoil.pem
+
+The exit status indicates whether the key is in the pwnedkeys database or not:
+
+* **`0`** -- the key is **not** known to be compromised.
+
+* **`1`** -- the key is known to be compromised, and should not be used.
+
+* **`2`** -- some sort of error occurred, and the key's status is undetermined.
+  An error message should have been printed on `stderr`.
+
+
+## Generate a compromise attestation
+
+If you have a key you'd like to submit to the pwnedkeys database, the best way
+to do it is to e-mail the key itself to `submit@pwnedkeys.com`.  However, if
+for some reason you really, *really* don't want to do that, you can generate
+your own compromise attestation and e-mail *that* (along with the public key,
+so *we* can verify the attestation is legit) to `submit@pwnedkeys.com`.
+
+To generate an attestation, run `pwnedkeys-prove-pwned`, passing in a
+private key on `stdin`:
+
+    pwnedkeys-prove-pwned < /etc/ssl/private/ssl-cert-snakeoil.key
+
+A JSON blob, containing the attestation and signature, will be output on
+`stdout`.
+
+
+# Contributing
+
+Bug reports should be sent to the [GitHub issue
+tracker](https://github.com/pwnedkeys/pwnedkeys-tools/issues).  Patches can be
+sent as a [GitHub pull
+request](https://github.com/pwnedkeys/pwnedkeys-tools/pulls).
+
+
+# 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/bin/pwnedkeys-prove-pwned

@@ -0,0 +1,5 @@
+#!/usr/bin/env ruby
+
+require "pwnedkeys/response"
+
+puts Pwnedkeys::Response.new($stdin.read).to_json

data/bin/pwnedkeys-query

@@ -0,0 +1,57 @@
+#!/usr/bin/env ruby
+
+require "pwnedkeys/request"
+require "openssl/x509/spki"
+require "openssl/pkey"
+
+def main(data)
+  spki = spki_from_arbitrary_data(data)
+
+  Pwnedkeys::Request.new(spki).pwned? ? 1 : 0
+end
+
+def spki_from_arbitrary_data(data)
+  begin
+    spki_from_key(data)
+  rescue OpenSSL::PKey::PKeyError
+    begin
+      spki_from_cert(data)
+    rescue OpenSSL::X509::CertificateError
+      begin
+        spki_from_csr(data)
+      rescue OpenSSL::X509::RequestError
+        begin
+          spki_from_ssh_key(data)
+        rescue OpenSSL::PKey::PKeyError
+          raise ArgumentError, "Unknown input format -- must be an unencrypted key, X.509 certificate, or X.509 CSR in PEM or DER format, or an OpenSSH public key"
+        end
+      end
+    end
+  end
+end
+
+def spki_from_key(data)
+  OpenSSL::PKey.read(data).to_spki
+end
+
+def spki_from_cert(data)
+  OpenSSL::X509::Certificate.new(data).to_spki
+end
+
+def spki_from_csr(data)
+  OpenSSL::X509::Request.new(data).to_spki
+end
+
+def spki_from_ssh_key(data)
+  OpenSSL::PKey.from_ssh_key(data).to_spki
+end
+  
+begin
+  exit main($stdin.read)
+rescue => ex
+  $stderr.puts "ERROR: #{ex.message} (#{ex.class})"
+  if ENV["PWNEDKEYS_DEBUG"] && !ENV["PWNEDKEYS_DEBUG"].empty?
+    $stderr.puts ex.backtrace.map { |l| "  #{l}" }.join
+    exit 2
+  end
+end

data/docker-wrappers/pwnedkeys-prove-pwned

@@ -0,0 +1,7 @@
+#!/bin/sh
+
+set -e
+
+: ${PWNEDKEYS_TOOLS_DOCKER_IMAGE:=pwnedkeys/tools:latest}
+
+docker run -i --rm "$PWNEDKEYS_TOOLS_DOCKER_IMAGE" pwnedkeys-prove-pwned "$@"

data/docker-wrappers/pwnedkeys-query

@@ -0,0 +1,7 @@
+#!/bin/sh
+
+set -e
+
+: ${PWNEDKEYS_TOOLS_DOCKER_IMAGE:=pwnedkeys/tools:latest}
+
+docker run -i --rm "$PWNEDKEYS_TOOLS_DOCKER_IMAGE" pwnedkeys-query "$@"

data/lib/openssl/pkey.rb

@@ -0,0 +1,77 @@
+require "openssl"
+
+module OpenSSL
+  module PKey
+    SSH_CURVE_NAME_MAP = {
+      "nistp256" => "prime256v1",
+      "nistp384" => "secp384r1",
+      "nistp521" => "secp521r1",
+    }
+
+    def self.from_ssh_key(s)
+      if s =~ /\Assh-[a-z0-9-]+ /
+        # WHOOP WHOOP prefixed key detected.
+        s = s.split(" ")[1]
+      else
+        # Discard any comment, etc that might be lurking around
+        s = s.split(" ")[0]
+      end
+
+      unless s =~ /\A[A-Za-z0-9\/+]+={0,2}\z/
+        raise OpenSSL::PKey::PKeyError,
+              "Invalid key encoding (not valid base64)"
+      end
+
+      parts = ssh_key_lv_decode(s)
+
+      case parts.first
+      when "ssh-rsa"
+        OpenSSL::PKey::RSA.new.tap do |k|
+          k.e = ssh_key_mpi_decode(parts[1])
+          k.n = ssh_key_mpi_decode(parts[2])
+        end
+      when "ssh-dss"
+        OpenSSL::PKey::DSA.new.tap do |k|
+          k.p = ssh_key_mpi_decode(parts[1])
+          k.q = ssh_key_mpi_decode(parts[2])
+          k.g = ssh_key_mpi_decode(parts[3])
+        end
+      when /ecdsa-sha2-/
+        begin
+          OpenSSL::PKey::EC.new(SSH_CURVE_NAME_MAP[parts[1]]).tap do |k|
+            k.public_key = OpenSSL::PKey::EC::Point.new(k.group, parts[2])
+          end
+        rescue TypeError
+          raise OpenSSL::PKey::PKeyError.new,
+                "Unknown curve identifier #{parts[1]}"
+        end
+      else
+        raise OpenSSL::PKey::PKeyError,
+              "Unknown key type #{parts.first.inspect}"
+      end
+    end
+
+    private
+
+    def self.ssh_key_lv_decode(s)
+      rest = s.unpack("m").first
+
+      [].tap do |parts|
+        until rest == ""
+          len, rest = rest.unpack("Na*")
+          if len > rest.length
+            raise OpenSSL::PKey::PKeyError,
+                  "Invalid LV-encoded string; wanted #{len} octets, but there's only #{rest.length} octets left"
+          end
+
+          elem, rest = rest.unpack("a#{len}a*")
+          parts << elem
+        end
+      end
+    end
+
+    def self.ssh_key_mpi_decode(s)
+      s.each_char.inject(0) { |i, c| i * 256 + c.ord }
+    end
+  end
+end

data/lib/openssl/pkey/ec.rb

@@ -0,0 +1,16 @@
+require "openssl/x509/spki"
+
+module OpenSSL
+  module PKey
+    class EC
+      # Generate an OpenSSL::X509::SPKI structure for this public key
+      def to_spki(format = :uncompressed)
+        unless self.public_key?
+          raise ECError,
+                "Cannot convert non-public-key to SPKI"
+        end
+        OpenSSL::X509::SPKI.new("id-ecPublicKey", OpenSSL::ASN1::ObjectId.new(self.public_key.group.curve_name), self.public_key.to_octet_string(format))
+      end
+    end
+  end
+end

data/lib/openssl/pkey/rsa.rb

@@ -0,0 +1,12 @@
+require "openssl/x509/spki"
+
+module OpenSSL
+  module PKey
+    class RSA
+      # Generate an OpenSSL::X509::SPKI structure for this public key
+      def to_spki(_format = nil)
+        OpenSSL::X509::SPKI.new(self.public_key.to_der)
+      end
+    end
+  end
+end

data/lib/openssl/x509/certificate.rb

@@ -0,0 +1,12 @@
+require "openssl/x509/spki"
+
+module OpenSSL
+  module X509
+    class Certificate
+      # Generate an OpenSSL::X509::SPKI structure for the public key in the cert
+      def to_spki(_format = nil)
+        OpenSSL::X509::SPKI.new(self.public_key.to_der)
+      end
+    end
+  end
+end

data/lib/openssl/x509/request.rb

@@ -0,0 +1,12 @@
+require "openssl/x509/spki"
+
+module OpenSSL
+  module X509
+    class Request
+      # Generate an OpenSSL::X509::SPKI structure for the public key in the CSR
+      def to_spki(_format = nil)
+        OpenSSL::X509::SPKI.new(self.public_key.to_der)
+      end
+    end
+  end
+end

data/lib/openssl/x509/spki.rb

@@ -0,0 +1,177 @@
+require "openssl"
+
+module OpenSSL
+  module X509
+    # Error raised when something goes awry in an SPKI object.
+    #
+    class SPKIError < OpenSSL::OpenSSLError; end
+
+    # `subjectPublicKeyInfo` for everyone.
+    #
+    # A standardised representation of the `SubjectPublicKeyInfo` X.509
+    # structure, along with helper methods to construct, deconstruct,
+    # and derive useful results from such a structure.
+    #
+    class SPKI
+      # Create a new SPKI object.
+      #
+      # This method can be called in one of a few different ways:
+      # 
+      # * `SPKI.new(String)` -- the provided string is interpreted as an ASN.1
+      #   DER data stream representing a `SubjectPublicKeyInfo` structure.  If
+      #
+      #
+      # * `SPKI.new(OpenSSL::ASN::Sequence) -- an already-decoded
+      #   `SubjectPublicKeyInfo` structure, ready for inspection and manipulation.
+      #
+      # * `SPKI.new(String, Object, String) -- create a new SPKI from its
+      #   component parts.  The first `String` is the OID of the
+      #   `algorithm.algorithm` field, while the second string is the content of
+      #   the `subjectPublicKey` field.  These will be converted into their ASN.1
+      #   equivalents (ObjectID and BitString, respectively).  The second
+      #   argument, the `Object`, is an arbitrary ASN.1 object representing
+      #   whatever should go in the `algorithm.parameters` field.  If this
+      #   field should be **absent**, this argument should be set to `nil`.
+      #
+      # * `SPKI.new(OpenSSL::ASN1::ObjectId, Object, OpenSSL::ASN1::BitString)` --
+      #   this is equivalent to the above three-argument form, but the arguments
+      #   are already in their ASN.1 object form, and won't be converted.  The
+      #   `Object` argument has the same semantics as above.
+      #
+      # @raise [OpenSSL::X509::SPKIError] if the parameters passed don't meet
+      #   validation requirements.  The exception message will provide more
+      #   details as to what was unacceptable.
+      #
+      def initialize(*args)
+        @spki = if args.length == 1
+          if args.first.is_a?(String)
+            OpenSSL::ASN1.decode(args.first)
+          elsif args.first.is_a?(OpenSSL::ASN1::Sequence)
+            args.first
+          else
+            raise SPKIError,
+                  "Must pass String or OpenSSL::ASN1::Sequence (you gave me an instance of #{args.first.class})"
+          end
+        elsif args.length == 3
+          alg_id, params, key_data = args
+          alg_id = alg_id.is_a?(String) ? OpenSSL::ASN1::ObjectId.new(alg_id) : alg_id
+          key_data = key_data.is_a?(String) ? OpenSSL::ASN1::BitString.new(key_data) : key_data
+
+          alg_info = [alg_id, params].compact
+
+          OpenSSL::ASN1::Sequence.new([
+            OpenSSL::ASN1::Sequence.new(alg_info),
+            key_data
+          ])
+        else
+          raise SPKIError,
+                "SPKI.new takes either one or three arguments only"
+        end
+
+        validate_spki
+      end
+
+      # Return the DER-encoded SPKI structure.
+      #
+      # @return [String]
+      #
+      def to_der
+        @spki.to_der
+      end
+
+      # Return an OpenSSL key.
+      #
+      # @return [OpenSSL::PKey::PKey]
+      #
+      def to_key
+        OpenSSL::PKey.read(self.to_der)
+      end
+
+      # Return a digest object for the *public key* data.
+      #
+      # Some specifications (such as RFC5280's subjectKeyId) want a fingerprint
+      # of only the key data, rather than a fingerprint of the entire SPKI
+      # structure.  If so, this is the method for you.
+      #
+      # Because different things want their fingerprints in different formats,
+      # this method returns a *digest object*, rather than a string, on which
+      # you can call whatever output format method you like (`#digest`, `#hexdigest`,
+      # or `#base64digest`, as appropriate).
+      #
+      # @param type [OpenSSL::Digest] override the default hash function used
+      #   to calculate the digest.  The default, SHA1, is in line with the most
+      #   common use of the key fingerprint, which is RFC5280 subjectKeyId
+      #   calculation, however if you wish to use a different hash function
+      #   you can pass an alternate digest class to use.
+      #
+      # @return [OpenSSL::Digest]
+      #
+      def key_fingerprint(type = OpenSSL::Digest::SHA1)
+        type.new(@spki.value.last.value)
+      end
+
+      # Return a digest object for the entire DER-encoded SPKI structure.
+      #
+      # Some specifications (such as RFC7469 public key pins, and pwnedkeys.com
+      # key IDs) require a hash of the entire DER-encoded SPKI structure.
+      # If that's what you want, you're in the right place.
+      #
+      # Because different things want their fingerprints in different formats,
+      # this method returns a *digest object*, rather than a string, on which
+      # you can call whatever output format method you like (`#digest`, `#hexdigest`,
+      # or `#base64digest`, as appropriate).
+      #
+      # @param type [OpenSSL::Digest] override the default hash function used
+      # to calculate the digest.  The default, SHA256, is in line with the most
+      # common uses of the SPKI fingerprint, however if you wish to use a
+      # different hash function you can pass an alternate digest class to use.
+      #
+      # @return [OpenSSL::Digest]
+      #
+      def spki_fingerprint(type = OpenSSL::Digest::SHA256)
+        type.new(@spki.to_der)
+      end
+
+      private
+
+      def validate_spki
+        unless @spki.is_a?(OpenSSL::ASN1::Sequence)
+          raise SPKIError,
+                "SPKI data is not an ASN1 sequence (got a #{@spki.class})"
+        end
+
+        if @spki.value.length != 2
+          raise SPKIError,
+                "SPKI top-level sequence must have two elements (length is #{@spki.value.length})"
+        end
+
+        alg_id, key_data = @spki.value
+
+        unless alg_id.is_a?(OpenSSL::ASN1::Sequence)
+          raise SPKIError,
+                "SPKI algorithm_identifier must be a sequence (got a #{alg_id.class})"
+        end
+
+        unless (1..2) === alg_id.value.length
+          raise SPKIError,
+                "SPKI algorithm sequence must have one or two elements (got #{alg_id.value.length} elements)"
+        end
+
+        unless alg_id.value.first.is_a?(OpenSSL::ASN1::ObjectId)
+          raise SPKIError,
+                "SPKI algorithm identifier does not contain an object ID (got #{alg_id.value.first.class})"
+        end
+
+        unless key_data.is_a?(OpenSSL::ASN1::BitString)
+          raise SPKIError,
+                "SPKI publicKeyInfo field must be a BitString (got a #{@spki.value.last.class})"
+        end
+      end
+    end
+  end
+end
+
+require_relative "../pkey/rsa"
+require_relative "../pkey/ec"
+require_relative "./request"
+require_relative "./certificate"