derparse 0.1.0

data/README.md

@@ -0,0 +1,141 @@
+Ever wanted to do terrible, terrible things with DER-encoded ASN.1 data
+structures?  Now you can!
+
+While there are plenty of DER parsers out there, they tend to suffer from the
+misguided assumption that the data they're parsing is actually valid.  Wild
+idea, it'll never catch on.  In contrast, `derparse` makes the opposite
+assumption -- that everything is awful.  This means that it makes an attempt to
+parse incomplete and, to a limited degree, corrupted DER-encoded data
+structures.
+
+Why would you *ever* want this, you might ask?  It's a niche requirement,
+undoubtedly, and if you're asking the question, that's a good indication that
+`derparse` probably isn't what you're looking for -- `OpenSSL::ASN1` does a
+good job of parsing well-formed DER data.
+
+
+# Installation
+
+It's a gem:
+
+    gem install derparse
+
+There's also the wonders of [the Gemfile](http://bundler.io):
+
+    gem 'derparse'
+
+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
+
+Instantiate a new `DerParse` object, giving it the DER-encoded data you want
+to parse:
+
+```ruby
+p = DerParse.new("0\x81\x80\x02\x01\x2a\x04\x44\x65\x72\x50\x61\x72\x73\x65\x02\x01\x45\x6e\x69\x63\x65")
+```
+
+{DerParse} has a number of instance methods to help you examine and work with
+the parsed ASN.1 data.  For example, you can get a string description of the
+data and its structure:
+
+```ruby
+p.to_s   # => "long, multi-line string of something something"
+```
+
+which means, of course, that you can print it to screen:
+
+```ruby
+puts p
+```
+
+If you want to process the data, you can use `#traverse` to walk
+through every element of the DER, which will yield a {`DerParse::Node`}
+for each ASN.1 object that is encountered, along with info about the
+parser state.
+
+```ruby
+p.traverse do |node, depth, offset|
+  puts "Parsing depth: #{depth} Offset: #{offset}"
+  puts "Header length: #{node.header_length} Data length: #{node.data_length}"
+  puts "Tag number: #{node.tag} Tag class: #{node.tag_class} Constructed: #{node.constructed?}"
+  puts "Value: #{node.value}"
+  puts "INCOMPLETE!" unless node.complete?
+end
+```
+
+There are a whole bunch of methods which {`DerParse::Node`} has to help you
+query what sort of ASN.1 object you're dealing with.  It also handles a string
+in which there are multiple ASN.1 objects encoded sequentially.
+
+It's is particularly important to note the {`DerParse::Node#complete?`} method.
+Because `DerParse` tries to give you as much data as it can, even if the DER is
+incomplete or corrupt, it needs to let you know when the data it's passing back
+is known to not be "correct", in a strict sense.  What counts as an
+"incomplete" value, and what impact it has on the value of a given node, can
+get complicated.  For full details, see the documentation for
+{DerParse#traverse}.
+
+If you call `#traverse` without a block, it'll return an iterator, which allows
+you to be more flexible with your iteration, like constructing complicated handlers
+for parsed DER structures.
+
+Finally, you can try {`DerParse#to_a`}.  This attempts to turn a DER blob into
+a collection of Ruby objects.  It handles many common ASN.1 data types,
+including integers, octet and bit strings, sequences and sets (turns them into
+arrays), and so on.  If it hits an ASN.1 type it can't handle, it'll give up
+and raise {`DerParse::IncompatibleDataTypeError`}.
+
+
+# Compatibility and Coverage
+
+The parts of ASN.1 that `DerParse` best supports are those which I've needed
+for my own purposes -- mainly sequences, integers, octet strings, and to a
+lesser extent OIDs.  In particular, it's important to note that `DerParse` is
+for ***DER*** structures, so any BER-specific things like indefinite lengths
+are not, and probably will not, be supported.  Support for additional ASN.1
+types are welcomed via a well-tested PR.
+
+
+# Security
+
+ASN.1 has a long and glorious history of being difficult to parse safely.
+While parsing in a memory-safe language reduces the attack surface, I don't
+recommend unconstrained parsing of arbitrary input using `DerParse`.
+Reasonable care has been taken to not produce any absolute bone-headed bugs,
+but this code has not been intensively vetted for potential security issues.
+
+That being said, `DerParse` is intended to be secure, and everyone wants it to
+be secure.  If you *do* find anything in `DerParse` that is security sensitive,
+please e-mail [`mpalmer@hezmatt.org`](mailto:mpalmer@hezmatt.org).
+
+
+# Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+
+# Licence
+
+Unless otherwise stated, everything in this repo is covered by the following
+copyright notice:
+
+    Copyright (C) 2020  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/derparse.gemspec

@@ -0,0 +1,35 @@
+begin
+	require 'git-version-bump'
+rescue LoadError
+	nil
+end
+
+Gem::Specification.new do |s|
+	s.name = "derparse"
+
+	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  = "DER parsing classes and routines"
+
+	s.authors  = ["Matt Palmer"]
+	s.email    = ["theshed+derparse@hezmatt.org"]
+  s.homepage = "http://github.com/mpalmer/derparse"
+
+	s.files = `git ls-files -z`.split("\0").reject { |f| f =~ /^(G|spec|Rakefile)/ }
+
+  s.required_ruby_version = ">= 2.5.0"
+
+	s.add_development_dependency 'bundler'
+	s.add_development_dependency 'github-release'
+	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 'simplecov'
+	s.add_development_dependency 'yard'
+end

data/lib/derparse.rb

@@ -0,0 +1,53 @@
+class DerParse
+	class Error < StandardError; end
+	class IncompatibleDatatypeError < StandardError; end
+
+	class Bug < Exception; end
+
+	def initialize(s)
+		if s.respond_to?(:to_str)
+			@s = s.to_str
+		else
+			raise ArgumentError,
+			      "Must provide string to parse"
+		end
+	end
+
+	def traverse(&blk)
+		if blk
+			node(@s, 0, 0, &blk)
+			self
+		else
+			to_enum(:traverse)
+		end
+	end
+
+	def to_a
+		[].tap do |v|
+			r = @s
+
+			until r.empty?
+				n = DerParse::Node.factory(r)
+				v << n.value
+				r = n.rest
+			end
+		end
+	end
+
+	private
+
+	def node(der, depth, offset, &blk)
+		node = DerParse::Node.factory(der, depth: depth, offset: offset)
+		yield node
+
+		if node.constructed?
+			node(node.data, depth + 1, offset + node.header_length, &blk)
+		end
+
+		unless node.rest.empty?
+			node(node.rest, depth, offset + node.der_length, &blk)
+		end
+	end
+end
+
+require_relative "./derparse/node"

data/lib/derparse/node.rb

@@ -0,0 +1,142 @@
+require "derparse"
+
+class DerParse
+	class Node
+		def self.factory(der, *args)
+			klass_name = DerParse::Node.constants.find do |const|
+				DerParse::Node.const_get(const).handles?(der)
+			end
+
+			klass = klass_name.nil? ? DerParse::Node : const_get(klass_name)
+
+			klass.new(der, *args)
+		end
+
+		attr_reader :tag, :tag_class, :tag_length, :length_length, :data_length, :data, :depth, :offset, :rest
+
+		def initialize(der, depth: 0, offset: 0)
+			@depth, @offset = depth, offset
+			@tag = @tag_class = @constructed = @tag_length = @data_length = @length_length, @data = nil
+			@complete = true
+
+			begin
+				r = parse_type(der)
+				r = parse_length(r)
+				@rest = parse_data(r)
+			rescue IncompleteDer
+				@complete = false
+			end
+		end
+
+		def der_length
+			if data_length.nil? || header_length.nil?
+				nil
+			else
+				data_length + header_length
+			end
+		end
+
+		def header_length
+			if tag_length.nil? || length_length.nil?
+				nil
+			else
+				tag_length + length_length
+			end
+		end
+
+		def constructed?
+			@constructed
+		end
+
+		def primitive?
+			!constructed?
+		end
+
+		def complete?
+			@complete
+		end
+
+		def value
+			raise IncompatibleDatatypeError
+		end
+
+		private
+
+		class IncompleteDer < Error; end
+		private_constant :IncompleteDer
+
+		def parse_type(s)
+			if s.empty? || s.nil?
+				# This *technically* shouldn't be possible
+				#:nocov:
+				raise Bug, "parse_type(#{s.inspect})"
+				#:nocov:
+			end
+
+			t0, s = ss(s)
+
+			@tag_class = (t0 & 0xc0) >> 6
+			@constructed = ((t0 & 0x20) >> 5) == 1
+			@tag = t0 & 0x1f
+			tl = 1
+
+=begin
+# As-yet unneeded big-tag support
+			if tag == 0x1f
+				tag = 0
+				more = true
+
+				while more
+					c = ss(s)
+					tag = tag * 128 + c & 0x7f
+					more = (c & 0x80) == 0x80
+					tl += 1
+				end
+			end
+=end
+
+			@tag_length = tl
+
+			s
+		end
+
+		def parse_length(s)
+			l0, s = ss(s)
+
+			if (l0 & 0x80) == 0
+				@data_length = l0
+				@length_length = 1
+			else
+				ll = l0 & 0x7f
+				@length_length = ll + 1
+				@data_length = ll.times.inject(0) { |a, _| c, s = ss(s); a * 256 + c }
+			end
+
+			s
+		end
+
+		def parse_data(s)
+			if s.length < @data_length
+				@data = s
+				raise IncompleteDer
+			else
+				@data = s[0, @data_length]
+			end
+
+			s[@data_length..]
+		end
+
+		def ss(s)
+			raise IncompleteDer if s.empty?
+
+			c, r = s.unpack("Ca*")
+			# Make sure that we always return a string as the second element
+			[c, r || ""]
+		end
+	end
+end
+
+require_relative "./node/integer"
+require_relative "./node/octet_string"
+require_relative "./node/null"
+require_relative "./node/sequence"

data/lib/derparse/node/integer.rb

@@ -0,0 +1,15 @@
+class DerParse
+	class Node
+		class Integer < Node
+			def self.handles?(der)
+				der[0] == "\x02"
+			end
+
+			def value
+				sign = (@data[0].ord & 0x80) >> 7
+
+				@data.split(//).inject(0) { |a, c| sign *= 256; a * 256 + c.ord } - sign
+			end
+		end
+	end
+end

data/lib/derparse/node/null.rb

@@ -0,0 +1,13 @@
+class DerParse
+	class Node
+		class Null < Node
+			def self.handles?(der)
+				der[0] == "\x05"
+			end
+
+			def value
+				nil
+			end
+		end
+	end
+end

data/lib/derparse/node/octet_string.rb

@@ -0,0 +1,13 @@
+class DerParse
+	class Node
+		class OctetString < Node
+			def self.handles?(der)
+				der[0] == "\x04"
+			end
+
+			def value
+				@data
+			end
+		end
+	end
+end

data/lib/derparse/node/sequence.rb

@@ -0,0 +1,21 @@
+class DerParse
+	class Node
+		class Sequence < Node
+			def self.handles?(der)
+				der[0] == "\x30"
+			end
+
+			def value
+				[].tap do |v|
+					r = @data
+
+					until r == ""
+						n = DerParse::Node.factory(r)
+						v << n.value
+						r = n.rest
+					end
+				end
+			end
+		end
+	end
+end

metadata

@@ -0,0 +1,188 @@
+--- !ruby/object:Gem::Specification
+name: derparse
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Matt Palmer
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2020-05-08 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: github-release
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: guard-rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.4'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 10.4.2
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.4'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 10.4.2
+- !ruby/object:Gem::Dependency
+  name: rb-inotify
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+- !ruby/object:Gem::Dependency
+  name: redcarpet
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: 
+email:
+- theshed+derparse@hezmatt.org
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".editorconfig"
+- ".gitignore"
+- ".yardopts"
+- CODE_OF_CONDUCT.md
+- CONTRIBUTING.md
+- LICENCE
+- README.md
+- derparse.gemspec
+- lib/derparse.rb
+- lib/derparse/node.rb
+- lib/derparse/node/integer.rb
+- lib/derparse/node/null.rb
+- lib/derparse/node/octet_string.rb
+- lib/derparse/node/sequence.rb
+homepage: http://github.com/mpalmer/derparse
+licenses: []
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.5.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.0.3
+signing_key: 
+specification_version: 4
+summary: DER parsing classes and routines
+test_files: []