certificate-transparency-client 0.1.0

data/README.md

@@ -0,0 +1,79 @@
+This is a Ruby client library for interacting with
+[RFC6962](http://tools.ietf.org/html/rfc6962) [Certificate
+Transparency](http://www.certificate-transparency.org/) servers.  It
+aims to provide a complete interface for retrieving and validating tree
+heads, entries, SCTs, as well as submitting certificates and precerts to a
+log.
+
+At present, it is not feature complete, however what is released is well
+tested, heavily documented, and should be ready for production use.
+
+
+# Installation
+
+It's a gem:
+
+    gem install certificate-transparency-client
+
+There's also the wonders of [the Gemfile](http://bundler.io):
+
+    gem 'certificate-transparency-client'
+
+If you're the sturdy type that likes to run from git:
+
+    rake build; gem install pkg/certificate-transparency-client-<whatever>.gem
+
+Or, if you've eschewed the convenience of Rubygems entirely, then you
+presumably know what to do already.
+
+
+# Usage
+
+To get started, instantiate a new instance of {CT::Client}:
+
+    require 'certificate-transparency-client'
+
+    ct = CT::Client.new "https://ct.example.org"
+
+The URL provided should be the "base" URL for the log; that is, everything
+immediately preceding the `/ct/v1/<blah>` parts of the URL when making a
+complete request.
+
+If you only provide a URL, you can retrieve things and submit entries, but
+if you provide a public key, {CT::Client} will also validate signatures for
+you:
+
+    ct = CT::Client.new "https://ct.example.org",
+                        :public_key => "<native or base64 key>"
+
+To discover what you can do with an instance of {CT::Client}, see the API
+docs for the {CT::Client} class.
+
+
+# Contributing
+
+Bug reports should be sent to the [Github issue
+tracker](https://github.com/mpalmer/certificate-transparency-client/issues),
+or [e-mailed](mailto:theshed+certificate-transparency-client@hezmatt.org). 
+Patches can be sent as a Github pull request, or
+[e-mailed](mailto:theshed+certificate-transparency-client@hezmatt.org).
+
+
+# Licence
+
+Unless otherwise stated, everything in this repo is covered by the following
+copyright notice:
+
+    Copyright (C) 2014,2015  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/>.

data/certificate-transparency-client.gemspec

@@ -0,0 +1,35 @@
+begin
+	require 'git-version-bump'
+rescue LoadError
+	nil
+end
+
+Gem::Specification.new do |s|
+	s.name = "certificate-transparency-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  = "A client for RFC6962 Certificate Transparency log servers"
+
+	s.authors  = ["Matt Palmer"]
+	s.email    = ["theshed+certificate-transparency-client@hezmatt.org"]
+	s.homepage = "http://theshed.hezmatt.org/certificate-transparency-client"
+
+	s.files = `git ls-files -z`.split("\0").reject { |f| f =~ /^(G|spec|Rakefile)/ }
+
+	s.required_ruby_version = ">= 1.9.3"
+
+	s.add_development_dependency 'bundler'
+	s.add_development_dependency 'github-release'
+	s.add_development_dependency 'guard-spork'
+	s.add_development_dependency 'guard-rspec'
+	s.add_development_dependency 'rake', '~> 10.4', '>= 10.4.2'
+	# Needed for guard
+	s.add_development_dependency 'rb-inotify', '~> 0.9'
+	s.add_development_dependency 'redcarpet'
+	s.add_development_dependency 'rspec'
+	s.add_development_dependency 'yard'
+end

data/lib/certificate-transparency/client.rb

@@ -0,0 +1,27 @@
+require 'openssl'
+
+# Interact with a Certificate Transparency server.
+#
+class CertificateTransparency::Client
+	def initialize(url, opts = {})
+		unless opts.is_a? Hash
+			raise ArgumentError,
+			      "Must pass a hash of options as second argument"
+		end
+
+		if opts[:public_key]
+			begin
+				@pubkey = if opts[:public_key].valid_encoding? && opts[:public_key] =~ /^[A-Za-z0-9+\/]+=*$/
+					OpenSSL::PKey::EC.new(opts[:public_key].unpack("m").first)
+				else
+					OpenSSL::PKey::EC.new(opts[:public_key])
+				end
+			rescue OpenSSL::PKey::ECError
+				raise ArgumentError,
+				      "Invalid public key"
+			end
+		end
+
+		@url = URI(url)
+	end
+end

data/lib/certificate-transparency/constants.rb

@@ -0,0 +1,23 @@
+module CertificateTransparency
+	# RFC6962 s3.1
+	LogEntryType = {
+		:x509_entry => 0,
+		:precert_entry => 1
+	}
+
+	# RFC6962 s3.4
+	MerkleLeafType = {
+		:timestamped_entry => 0
+	}
+
+	# RFC6962 s3.2
+	SignatureType = {
+		:certificate_timestamp => 0,
+		:tree_hash             => 1
+	}
+
+	# RFC6962 s3.2
+	Version = {
+		:v1 => 0
+	}
+end

data/lib/certificate-transparency/extensions/string.rb

@@ -0,0 +1,15 @@
+# Extensions to the String class.
+#
+class String
+	# Return a new string, which is simply the object base64 encoded.
+	#
+	def base64
+		[self.to_s].pack("m0")
+	end
+
+	# Return a new string, which is simply the object base64 decoded.
+	#
+	def unbase64
+		self.to_s.unpack("m").first
+	end
+end

data/lib/certificate-transparency/extensions/time.rb

@@ -0,0 +1,17 @@
+# Extensions to the Time class.
+#
+class Time
+	# Return the time represented by this object, in milliseconds since the
+	# epoch.
+	#
+	def ms
+		(self.to_f * 1000).to_i
+	end
+
+	# Create a new instance of Time, set to the given number of milliseconds
+	# since the epoch.
+	#
+	def self.ms(i)
+		Time.at(i.to_f / 1000)
+	end
+end

data/lib/certificate-transparency/signed_tree_head.rb

@@ -0,0 +1,51 @@
+require 'json'
+require 'tls'
+
+# A CT SignedTreeHead (RFC6962 s3.5, s4.3).
+#
+class CertificateTransparency::SignedTreeHead
+	attr_accessor :tree_size
+	attr_accessor :timestamp
+	attr_accessor :root_hash
+	attr_accessor :signature
+
+	# Create a new SignedTreeHead instance from the JSON returned
+	# by `/ct/v1/get-sth`.
+	#
+	def self.from_json(json)
+		doc = JSON.parse(json)
+
+		self.new.tap do |sth|
+			sth.tree_size = doc['tree_size']
+			sth.timestamp = Time.at(doc['timestamp'].to_f / 1000)
+			sth.root_hash = doc['sha256_root_hash'].unpack("m").first
+			sth.signature = doc['tree_head_signature'].unpack("m").first
+		end
+	end
+
+	# Determine whether or not the signature that was provided in the
+	# signed tree head is a valid one, based on the provided key.
+	#
+	# @param pk [String] the raw binary form of the public key of the
+	#   log.
+	#
+	# @return Boolean
+	#
+	def valid?(pk)
+		key = OpenSSL::PKey::EC.new(pk)
+
+		blob = [
+			CT::Version[:v1],
+			CT::SignatureType[:tree_hash],
+		   timestamp.ms,
+		   tree_size,
+		   root_hash
+		].pack("ccQ>Q>a32")
+
+		ds = TLS::DigitallySigned.from_blob(signature)
+		ds.content = blob
+		ds.key = key
+
+		ds.valid?
+	end
+end

data/lib/certificate-transparency-client.rb

@@ -0,0 +1,2 @@
+require 'certificate-transparency'
+require 'certificate-transparency/client'

data/lib/certificate-transparency.rb

@@ -0,0 +1,14 @@
+# The base module of everything related to Certificate Transparency.
+module CertificateTransparency; end
+
+unless Kernel.const_defined?(:CT)
+	#:nodoc:
+	CT = CertificateTransparency
+end
+
+require 'certificate-transparency/extensions/string'
+require 'certificate-transparency/extensions/time'
+
+require 'certificate-transparency/constants'
+
+require 'certificate-transparency/signed_tree_head'

data/lib/tls/digitally_signed.rb

@@ -0,0 +1,129 @@
+require 'openssl'
+
+unless OpenSSL::PKey::EC.instance_methods.include?(:private?)
+	OpenSSL::PKey::EC.class_eval("alias_method :private?, :private_key?")
+end
+
+# Create a `DigitallySigned` struct, as defined by RFC5246 s4.7, and adapted
+# for the CertificateTransparency system (that is, ECDSA using the NIST
+# P-256 curve is the only signature algorithm supported, and SHA-256 is the
+# only hash algorithm supported).
+#
+class TLS::DigitallySigned
+	# Create a new `DigitallySigned` struct.
+	#
+	# Takes a number of named options:
+	#
+	# * `:key` -- (required) An instance of `OpenSSL::PKey::EC`.  If you pass
+	#   in `:blob` as well, then this can be either a public key or a private
+	#   key (because you only need a public key for validating a signature),
+	#   but if you only pass in `:content`, you must provide a private key
+	#   here.
+	#
+	#   This key *must* be generated with the NIST P-256 curve (known to
+	#   OpenSSL as `prime256v1`) in order to be compliant with the CT spec.
+	#   However, we can't validate that, so it's up to you to make sure you
+	#   do it right.
+	#
+	# * `:content` -- (required) The content to sign, or verify the signature
+	#   of.  This can be any string.
+	#
+	# * `:blob` -- An existing encoded `DigitallySigned` struct you'd like to
+	#   have decoded and verified against `:content` with `:key`.
+	#
+	# Raises an `ArgumentError` if you try to pass in anything that doesn't
+	# meet the rather stringent requirements.
+	#
+	def self.from_blob(blob)
+		hash_algorithm, signature_algorithm, sig_blob = blob.unpack("CCa*")
+
+		if signature_algorithm != ::TLS::SignatureAlgorithm[:ecdsa]
+			raise ArgumentError,
+			      "Signature specified in blob is not ECDSA"
+		end
+
+		if hash_algorithm != ::TLS::HashAlgorithm[:sha256]
+			raise ArgumentError,
+			      "Hash algorithm specified in blob is not SHA256"
+		end
+
+		sig, rest = ::TLS::Opaque.from_blob(sig_blob, 2**16-1)
+		signature = sig.value
+
+		TLS::DigitallySigned.new.tap do |ds|
+			ds.hash_algorithm = hash_algorithm
+			ds.signature_algorithm = signature_algorithm
+			ds.signature = signature
+		end
+	end
+
+	attr_accessor :content, :hash_algorithm, :signature_algorithm, :signature
+	attr_reader :key
+
+	# Set the key for this instance.
+	#
+	# @param k [OpenSSL::PKey::EC] a key to verify or generate the signature. 
+	#   If you only want to verify an existing signature (ie you created this
+	#   instance via {.from_blob}, then this key can be a public key. 
+	#   Otherwise, if you want to generate a new signature, you must pass in
+	#   a private key.
+	#
+	# @return void
+	#
+	# @raise [ArgumentError] if you pass in a key that isn't of the
+	#   appropriate type.
+	#
+	def key=(k)
+		unless k.is_a? OpenSSL::PKey::EC
+			raise ArgumentError,
+			      "Key must be an instance of OpenSSL::PKey::EC"
+		end
+
+		@key = k
+	end
+
+	# Return a binary string which represents a `DigitallySigned` struct of
+	# the content passed in.
+	#
+	def to_blob
+		if @key.nil?
+			raise RuntimeError,
+			      "No key has been supplied"
+		end
+		begin
+			@signature ||= @key.sign(OpenSSL::Digest::SHA256.new, @content)
+		rescue ArgumentError
+			raise RuntimeError,
+			      "Must have a private key in order to make a signature"
+		end
+
+		[
+			@hash_algorithm,
+			@signature_algorithm,
+			@signature.length,
+			@signature
+		].pack("CCna*").force_encoding("BINARY")
+	end
+
+	# Verify whether or not the `signature` struct given is a valid signature
+	# for the key/content/blob combination provided to the constructor.
+	#
+	def valid?
+		if @key.nil?
+			raise RuntimeError,
+			      "No key has been specified"
+		end
+
+		if @signature.nil?
+			raise RuntimeError,
+			      "No signature is available yet"
+		end
+
+		if @content.nil?
+			raise RuntimeError,
+			      "No content has been specified yet"
+		end
+
+		@key.verify(OpenSSL::Digest::SHA256.new, @signature, @content)
+	end
+end

data/lib/tls/opaque.rb

@@ -0,0 +1,106 @@
+# An implementation of the TLS 1.2 (RFC5246) "variable length" opaque type.
+#
+# You can create an instance of this type by passing in a stringish to be
+# encoded, and a "maximum length", like this:
+#
+#    TLS::Opaque.new("Hello World", 2**16-1)
+#
+# If you have a TLS::Opaque-encoded blob, and you'd like to get the
+# content out of it, you can use `.from_blob` to create a TLS::Opaque object
+# that will contain the data you seek:
+#
+#    TLS::Opaque.from_blob("\x00\x0BHello World", 2**16-1)
+#
+# In both cases, you need to specify what the maximum length of the `value`
+# can be, because that is what determines how many bytes the length field
+# takes up at the beginning of the string.
+#
+# To get the "encoded" form,, call `#to_blob`:
+#
+#    TLS::Opaque.new("Hello World", 255).to_blob
+#    => "\x0BHello World"
+#
+# Or, to get the string itself out, call `#value`:
+#
+#    TLS::Opaque.from_blob("\x0BHello World", 255)[0].value
+#    => "Hello World"
+#
+# Passing in a value or blob which is longer than the maximum length
+# specified will result in `ArgumentError` being thrown.
+#
+class TLS::Opaque
+	attr_reader :value
+
+	# Parse out an opaque string from a blob, as well as returning
+	# any remaining data.  The `maxlen` parameter is required to
+	# know how many octets at the beginning of the string to read to
+	# determine the length of the opaque string.
+	#
+	# Returns a two-element array, `[TLS::Opaque, String]`, being a
+	# `TLS::Opaque` instance retrieved from the blob provided, and a `String`
+	# containing any remainder of the blob that wasn't considered part of the
+	# `TLS::Opaque`.  This second element will *always* be a string, but it
+	# may be an empty string, if the `TLS::Opaque` instance was the entire
+	# blob.
+	#
+	# This method will raise `ArgumentError` if the length encoded at the
+	# beginning of `blob` is longer than the data in `blob`, or if it is
+	# larger than `maxlen`.
+	#
+	def self.from_blob(blob, maxlen)
+		len_bytes = lenlen(maxlen)
+
+		len = blob[0..len_bytes-1].split('').inject(0) do |total, c|
+			total * 256 + c.ord
+		end
+
+		if len > maxlen
+			raise ArgumentError,
+			      "Encoded length (#{len}) is greater than maxlen (#{maxlen})"
+		end
+
+		if len > blob[len_bytes..-1].length
+			raise ArgumentError,
+			      "Encoded length (#{len}) is greater than the number of bytes available"
+		end
+
+		[TLS::Opaque.new(blob[len_bytes..(len_bytes+len-1)], maxlen),
+		 blob[(len_bytes+len)..-1]
+		]
+	end
+
+	def initialize(str, maxlen)
+		unless maxlen.is_a? Integer
+			raise ArgumentError,
+			      "maxlen must be an Integer"
+		end
+
+		if str.length > maxlen
+			raise ArgumentError,
+			      "value given is longer than maxlen (#{maxlen})"
+		end
+
+		@maxlen = maxlen
+		@value  = str
+	end
+
+	# Return an encoded Opaque.
+	#
+	def to_blob
+		len = value.length
+		params = []
+		self.class.lenlen(@maxlen).times do
+			params.unshift(len % 256)
+			len /= 256
+		end
+
+		params << value
+
+		params.pack("C#{self.class.lenlen(@maxlen)}a*")
+	end
+
+	private
+	def self.lenlen(len)
+		(Math.log2(len).ceil / 8.0).ceil
+	end
+end

data/lib/tls.rb

@@ -0,0 +1,24 @@
+# Constants and types required by CertificateTransparency, which come from
+# the core TLS specs.
+#
+module TLS
+	# RFC5246 s7.4.1.4.1 (I shit you not, five levels of headings)
+	HashAlgorithm = { :none   => 0,
+	                  :md5    => 1,
+	                  :sha1   => 2,
+	                  :sha224 => 3,
+	                  :sha256 => 4,
+	                  :sha384 => 5,
+	                  :sha512 => 6
+	                }
+
+	# RFC5246 s7.4.1.4.1
+	SignatureAlgorithm = { :anonymous => 0,
+	                       :rsa       => 1,
+	                       :dsa       => 2,
+	                       :ecdsa     => 3
+	                     }
+end
+
+require 'tls/digitally_signed'
+require 'tls/opaque'