openssl-additions 0.1.0

data/README.md

@@ -0,0 +1,90 @@
+This is a collection of miscellaneous quality-of-life helpers to Ruby's core
+OpenSSL module.  They're intended to make working with OpenSSL a little less
+frustrating.
+
+
+# Installation
+
+Due to recent changes in the `openssl` standard library, this gem requires
+Ruby 2.5 or later with the `openssl` extension.  Assuming you've got that
+available, you can install as a gem:
+
+    gem install openssl-additions
+
+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
+
+All classes are fully documented with YARD comments, so [the
+online docs](https://rubydoc.info/gems/openssl-additions) are actually useful.
+A brief summary of features, though, appears below.
+
+
+## Consistent SPKIs
+
+Not all OpenSSL key types provide a consistent `SubjectPublicKeyInfo` data
+structure to work with, so I added one, along with helpers on the existing
+SPKI-related classes to extract one.
+
+    require "openssl/x509/spki"
+	
+	key = OpenSSL::PKey::EC.new("prime256v1").generate_key
+	spki = key.to_spki
+	spki.to_der   # => bundle of gibberish
+	spki.spki_fingerprint.hexdigest  # => lots of hex characters
+
+	cert = OpenSSL::X509::Certificate.new(File.read("/tmp/cert.pem"))
+	spki = cert.to_spki
+    # ... and so on
+
+## Parsing SSH public keys into PKeys
+
+Ever needed an SSH public key in an OpenSSL-compatible object?  Neither did I
+until recently, but once I did, I wrote this.
+
+    require "openssl/pkey"
+
+	key = OpenSSL::PKey.from_ssh_key(File.read("~/.ssh/id_rsa.pub"))
+	key.class     # => OpenSSL::PKey::RSA
+	key.public?   # => true
+	key.private?  # => false
+
+
+# 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/openssl/pkey.rb

@@ -0,0 +1,100 @@
+require "openssl"
+
+# Enhancements to the core asymmetric key handling.
+module OpenSSL::PKey
+  # A mapping of the "SSH" names for various curves, to their OpenSSL
+  # equivalent names.
+  SSH_CURVE_NAME_MAP = {
+    "nistp256" => "prime256v1",
+    "nistp384" => "secp384r1",
+    "nistp521" => "secp521r1",
+  }
+
+  # Create a new `OpenSSL::PKey` from an SSH public key.
+  #
+  # Given an OpenSSL 2 public key (with or without the `ssh-rsa` / `ecdsa-etc`
+  # prefix), create an equivalent instance of an `OpenSSL::PKey::PKey` subclass
+  # which represents the same key parameters.
+  #
+  # If you've got an SSH *private* key, you don't need this method, as they're
+  # already PKCS#8 ("PEM") private keys, which OpenSSL is happy to read
+  # directly (using `OpenSSL::PKey.read`).
+  #
+  # @param s [String] the SSH public key to convert, in its usual
+  #   base64-encoded form, with or without key type prefix.
+  #
+  # @return [OpenSSL::PKey::PKey] the OpenSSL-compatible key object.  Note
+  #   that this can only ever be a *public* key, never a private key, because
+  #   SSH public keys are, well, public.
+  #
+  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
+
+  # Take the base64 string and split it into its component parts.
+  #
+  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
+
+  # Turn an SSH "MPI" (encoded arbitrary-length integer) string into a real
+  # Ruby integer.
+  #
+  def self.ssh_key_mpi_decode(s)
+    s.each_char.inject(0) { |i, c| i * 256 + c.ord }
+  end
+end

data/lib/openssl/pkey/ec.rb

@@ -0,0 +1,25 @@
+require "openssl"
+
+require_relative "../x509/spki"
+
+# Additional helpers for ECDSA keys.
+#
+class OpenSSL::PKey::EC
+  # Generate an OpenSSL::X509::SPKI structure for this public key.
+  #
+  # @param format [Symbol] whether to return the SPKI containing the compressed
+  #   or uncompressed form of the curve point which represents the public key.
+  #   Note that from a functional perspective, the two forms are identical, but
+  #   they will produce completely different key and SPKI fingerprints, which
+  #   may be important.
+  #
+  # @return [OpenSSL::X509::SPKI]
+  #
+  def to_spki(format = :uncompressed)
+    unless self.public_key?
+      raise OpenSSL::PKey::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

data/lib/openssl/pkey/rsa.rb

@@ -0,0 +1,17 @@
+require "openssl"
+
+require_relative "../x509/spki"
+
+# Additional helper methods for RSA keys.
+#
+class OpenSSL::PKey::RSA
+  # Generate an OpenSSL::X509::SPKI structure for this public key.
+  #
+  # @param _format [NilClass] unused by this class.
+  #
+  # @return [OpenSSL::X509::SPKI]
+  #
+  def to_spki(_format = nil)
+    OpenSSL::X509::SPKI.new(self.public_key.to_der)
+  end
+end

data/lib/openssl/x509/certificate.rb

@@ -0,0 +1,17 @@
+require "openssl"
+
+require_relative "./spki"
+
+# Additional helper methods for certificates.
+#
+class OpenSSL::X509::Certificate
+  # Generate an OpenSSL::X509::SPKI structure for the public key in the cert.
+  #
+  # @param _format [NilClass] Unused.
+  #
+  # @return [OpenSSL::X509::SPKI]
+  #
+  def to_spki(_format = nil)
+    OpenSSL::X509::SPKI.new(self.public_key.to_der)
+  end
+end

data/lib/openssl/x509/request.rb

@@ -0,0 +1,17 @@
+require "openssl"
+
+require_relative "./spki"
+
+# Additional helper methods for CSRs.
+#
+class OpenSSL::X509::Request
+  # Generate an OpenSSL::X509::SPKI structure for the public key in the CSR.
+  #
+  # @param _format [NilClass] Unused.
+  #
+  # @return [OpenSSL::X509::SPKI]
+  #
+  def to_spki(_format = nil)
+    OpenSSL::X509::SPKI.new(self.public_key.to_der)
+  end
+end

data/lib/openssl/x509/spki.rb

@@ -0,0 +1,179 @@
+require "openssl"
+
+# Additional classes for X509 data structures.
+#
+module OpenSSL::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
+
+    # Make sure that the SPKI data we were passed is legit.
+    #
+    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
+
+require_relative "../pkey/rsa"
+require_relative "../pkey/ec"
+require_relative "./request"
+require_relative "./certificate"