derparse 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 719be66a0a1211105f01fcab6ca73988fd5ca6a173b6c1d39b91101ced07a3da
-  data.tar.gz: 2e0c0d0241a457f84f80b0be1233002fc0aa2e24ccc4b5d9b5c030a0a524f893
+  metadata.gz: a97c66e10d00854afeb8f25016c1e2a1078104fdaffaf0114b0583c83957403c
+  data.tar.gz: 9748b530905bddd81be8d7510daa7cff17f7e9fa88b8bedcfd54fc668f42a658
 SHA512:
-  metadata.gz: 025a57ef3f0bf26dd8d3387cbf122cf4c285148ed132fe293009122715e12afd923460c52a89eb3f687be40145b48d218a7960667f62127486911279291ee15d
-  data.tar.gz: ea07d6a6fa38ff4874cb439b7aacf84556fddee24c94a9027d157eae3e9a9461440d6f8947625a56079db18753d66b3fa2e72126546a0e06e2ce7b3ccddfe2c8
+  metadata.gz: b3f09d136141f1d2c7e16fed6348ac044836d258ebf5f1c1b7e2be39e799f439b6bec67f27b0de32a6418f95f24f6e9d306d41a8f17a08a687e7f97ec6fbeb1f
+  data.tar.gz: 39c6a09d9f6fd69ee6f915116bbe8d38aafaa8ef400406e696599d46278c484a9cf2e09de9bd89fa16aa8c8a1f96ff51c050cae5aa335de41fd031c863459d37

data/README.md

@@ -41,38 +41,50 @@ to parse:
 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:
+If you've got multiple DER-encoded strings concatenated, that's no problem --
+`DerParse` will handle that.  If you're traversing, you'll get multiple nodes
+of depth `0`.
 
-```ruby
-p.to_s   # => "long, multi-line string of something something"
-```
+The {`DerParse`} class has a number of instance methods to help you examine and
+work with the parsed ASN.1 data.
 
-which means, of course, that you can print it to screen:
 
-```ruby
-puts p
-```
+## Traversing the entire DER tree
 
-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.
+If you want to examine every value in the DER, digging down into sequences
+and such, then you want `#traverse`.  It walks through every element of the DER, yielding
+a {`DerParse::Node`} for each ASN.1 object that is encountered.  When a constructed
+element (structure, set) is encountered, a node for the sequence or set will be
+yielded, followed by a node for each of the ASN.1 objects in the sequence of set.
 
 ```ruby
-p.traverse do |node, depth, offset|
-  puts "Parsing depth: #{depth} Offset: #{offset}"
+p.traverse do |node|
+  puts "Parsing depth: #{node.depth} Offset: #{node.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 "Tag number: #{node.tag} Tag class: #{node.tag_class} Constructed: #{node.constructed?.inspect}"
+  puts "Value: #{node.value rescue nil}"
   puts "INCOMPLETE!" unless node.complete?
 end
 ```
 
+If you call `#traverse` without a block, it'll return an `Enumerator`, which
+returns the next node in the DER structure for each call to `#next`.  It is
+more convenient when you want to construct parsing state machines.
+
+
+## Walking around nodes
+
+If you want more control about how you travel through the tree of nodes, you
+can get the first node in the DER tree with {`DerParse#first_node`}.  Every
+node has {`DerParse#next_node`} and {`DerParse#first_child`} methods, which do
+what they say on the tin.  In both cases, if there is no relevant node, a
+{`DerParse::Node::Nil`} will be returned.
+
+
+## Examining a node
+
 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.
+query what sort of ASN.1 object you're dealing with.
 
 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
@@ -82,15 +94,56 @@ is known to not be "correct", in a strict sense.  What counts as an
 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
+## Finding objects in a corrupted DER
+
+If you're working with a string that is missing its beginning, or has its early
+parts corrupted, you can try using the {`DerParse#resync`} method to try and "resync"
+the parser, based on knowing that an object of a particular type is in there
+*somewhere*.
+
+It works by looking for an encoded ASN.1 object of a type you specify, and returning
+a node instance for that object, which you can then traverse using `#next_node`
+and `#first_child` (as appropriate).
+
+There is always the risk of a false-positive when using `#resync`, so you
+should never 100% trust the values it gives back.  However, to try and minimise
+the risk, we assume that the ASN.1 object you're looking for is complete (not
+truncated), and that the rest of the string is valid DER.  This means that all
+of the lengths remaining in the DER must line up, which isn't particularly
+likely to happen at random.
+
+The downside of this validation approach is that if the corruption extends to
+having extra "garbage" data at the end of the DER, then `#resync` won't find
+anything.  You can turn this off by passing `strict: false` to `#resync`, but
+be aware that your false positive rate will skyrocket.
+
+
+## Rendering as a string
+
+This is quite straightforward.  If a DER consists entirely of object types that
+`DerParse` knows how to decode into Ruby values, you can just use `#to_s`:
+
+```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 your DER contains an ASN.1 value that `DerParse` doesn't know how to
+render, you'll get a {`DerParse::IncompatibleDatatypeError`}.
+
+## A collection of Ruby objects
+
+For this, you can use {`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`}.
+and raise {`DerParse::IncompatibleDatatypeError`}.
 
 
 # Compatibility and Coverage
@@ -99,8 +152,9 @@ 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.
+are not, and probably will never, be supported.  Support for rendering
+additional ASN.1 types into specific Ruby objects are welcomed via a
+well-tested PR.
 
 
 # Security

data/lib/derparse.rb

@@ -6,7 +6,7 @@ class DerParse
 
 	def initialize(s)
 		if s.respond_to?(:to_str)
-			@s = s.to_str
+			@s = s.to_str.dup.force_encoding("BINARY")
 		else
 			raise ArgumentError,
 			      "Must provide string to parse"
@@ -34,6 +34,36 @@ class DerParse
 		end
 	end
 
+	def resync(tag, strict: true)
+		i = @s.index(tag)
+
+		until i.nil?
+			n = DerParse::Node.factory(@s[i..], offset: i)
+
+			if n.complete?
+				if !strict || n.next_node.nil?
+					return n
+				else
+					nn = n.next_node
+					while nn.complete? && !nn.next_node.nil?
+						nn = nn.next_node
+					end
+					if nn.complete?
+						return n
+					end
+				end
+			end
+
+			i = (ni = @s[i+1..].index(tag)) ? ni + i + 1: nil
+		end
+
+		DerParse::Node::Nil.new
+	end
+
+	def first_node
+		node(@s, 0, 0) { |n| return n }
+	end
+
 	private
 
 	def node(der, depth, offset, &blk)

data/lib/derparse/node.rb

@@ -25,6 +25,7 @@ class DerParse
 				@rest = parse_data(r)
 			rescue IncompleteDer
 				@complete = false
+				@rest = ""
 			end
 		end
 
@@ -56,8 +57,20 @@ class DerParse
 			@complete
 		end
 
+		def next_node
+			if @rest.empty?
+				DerParse::Node::Nil.new
+			else
+				DerParse::Node.factory(@rest)
+			end
+		end
+
+		def first_child
+			DerParse::Node::Nil.new
+		end
+
 		def value
-			raise IncompatibleDatatypeError
+			raise IncompatibleDatatypeError, "No known way to render tag #{@tag} into a value"
 		end
 
 		private
@@ -138,5 +151,6 @@ end
 
 require_relative "./node/integer"
 require_relative "./node/octet_string"
+require_relative "./node/nil"
 require_relative "./node/null"
 require_relative "./node/sequence"

data/lib/derparse/node/nil.rb

@@ -0,0 +1,31 @@
+class DerParse
+	class Node
+		# This class does not represent an ASN.1 object, but instead is a special
+		# node that is returned when no other node would be suitable.  It is, shall
+		# we say, "`nil`-compatible".
+		class Nil < Node
+			def initialize(*_)
+			end
+
+			def self.handles?(_)
+				false
+			end
+
+			def value
+				nil
+			end
+
+			def nil?
+				true
+			end
+
+			def next_node
+				self
+			end
+
+			def first_child
+				self
+			end
+		end
+	end
+end

data/lib/derparse/node/sequence.rb

@@ -16,6 +16,14 @@ class DerParse
 					end
 				end
 			end
+
+			def first_child
+				if @data.empty?
+					DerParse::Node::Nil.new
+				else
+					DerParse::Node.factory(@data)
+				end
+			end
 		end
 	end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: derparse
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Matt Palmer
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2020-05-08 00:00:00.000000000 Z
+date: 2020-05-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -160,6 +160,7 @@ files:
 - lib/derparse.rb
 - lib/derparse/node.rb
 - lib/derparse/node/integer.rb
+- lib/derparse/node/nil.rb
 - lib/derparse/node/null.rb
 - lib/derparse/node/octet_string.rb
 - lib/derparse/node/sequence.rb