evidence_record 0.1.0

data/lib/evidence_record/der.rb

@@ -0,0 +1,370 @@
+# frozen_string_literal: true
+
+module EvidenceRecord
+  # Internal: a strict DER reader and the few encoders the library needs
+  # (docs/design.md 7.1).
+  #
+  # OpenSSL::ASN1 is not used to check DER: re-encoding what it decoded keeps
+  # indefinite lengths and constructed strings, does not reorder SETs, and
+  # drops the fractional seconds of GeneralizedTime, so "decode and re-encode
+  # gives the same bytes" accepts BER and rejects valid DER. This reader also
+  # keeps the original bytes of every element, which are what gets hashed.
+  module DER
+    BOOLEAN = 1
+    INTEGER = 2
+    BIT_STRING = 3
+    OCTET_STRING = 4
+    NULL = 5
+    OBJECT_IDENTIFIER = 6
+    ENUMERATED = 10
+    RELATIVE_OID = 13
+    SEQUENCE = 16
+    SET = 17
+    UTC_TIME = 23
+    GENERALIZED_TIME = 24
+
+    # Universal types that are always constructed: EXTERNAL, EMBEDDED PDV,
+    # SEQUENCE and SET. All others must use the primitive encoding in DER.
+    CONSTRUCTED_TYPES = [8, 11, SEQUENCE, SET].freeze
+    TAG_CLASSES = %i[universal application context private].freeze
+    MAX_DEPTH = 64
+    GENERALIZED_TIME_PATTERN = /\A(\d{4})(\d{2})(\d{2})(\d{2})(\d{2})(\d{2})(?:\.(\d*[1-9]))?Z\z/
+
+    # One element (TLV). raw is its whole encoding, content its contents
+    # octets; children is an Array of Nodes for a constructed element.
+    class Node
+      attr_reader :tag_class, :tag, :raw, :content, :children
+
+      def initialize(tag_class, constructed, tag, raw, content, children)
+        @tag_class = tag_class
+        @constructed = constructed
+        @tag = tag
+        @raw = raw.freeze
+        @content = content.freeze
+        @children = children&.freeze
+        freeze
+      end
+
+      def constructed?
+        @constructed
+      end
+
+      def universal?(tag)
+        @tag_class == :universal && @tag == tag
+      end
+
+      def context?(tag)
+        @tag_class == :context && @tag == tag
+      end
+    end
+
+    module_function
+
+    # Parses one DER element that must span all of bytes. what names the
+    # input in error messages.
+    def parse(bytes, what)
+      raise ArgumentError, "#{what} must be a String, got #{bytes.class}" unless bytes.is_a?(String)
+
+      bytes = bytes.b
+      node, pos = read(bytes, 0, bytes.bytesize, 0, what)
+      raise ParseError, "#{what}: #{bytes.bytesize - pos} bytes of trailing data" unless pos == bytes.bytesize
+
+      node
+    end
+
+    def read(bytes, pos, limit, depth, what)
+      raise ParseError, "#{what}: nested too deeply" if depth > MAX_DEPTH
+
+      start = pos
+      id = byte_at(bytes, pos, limit, what)
+      pos += 1
+      tag_class = TAG_CLASSES[id >> 6]
+      constructed = id.anybits?(0x20)
+      tag = id & 0x1f
+      tag, pos = read_high_tag(bytes, pos, limit, what) if tag == 0x1f
+      length, pos = read_length(bytes, pos, limit, what)
+      raise ParseError, "#{what}: truncated" if limit - pos < length
+
+      children = nil
+      if constructed
+        children = []
+        child_pos = pos
+        while child_pos < pos + length
+          child, child_pos = read(bytes, child_pos, pos + length, depth + 1, what)
+          children << child
+        end
+      end
+      node = Node.new(tag_class, constructed, tag, bytes.byteslice(start, pos + length - start),
+                      bytes.byteslice(pos, length), children)
+      check_universal(node, what) if tag_class == :universal
+      [node, pos + length]
+    end
+
+    def byte_at(bytes, pos, limit, what)
+      raise ParseError, "#{what}: truncated" if pos >= limit
+
+      bytes.getbyte(pos)
+    end
+
+    def read_high_tag(bytes, pos, limit, what)
+      tag = 0
+      loop do
+        b = byte_at(bytes, pos, limit, what)
+        raise ParseError, "#{what}: non-minimal tag number" if tag.zero? && b == 0x80
+        raise ParseError, "#{what}: tag number too large" if tag > 0xffffff
+
+        tag = (tag << 7) | (b & 0x7f)
+        pos += 1
+        break if b < 0x80
+      end
+      raise ParseError, "#{what}: non-minimal tag number" if tag < 0x1f
+
+      [tag, pos]
+    end
+
+    def read_length(bytes, pos, limit, what)
+      first = byte_at(bytes, pos, limit, what)
+      pos += 1
+      return [first, pos] if first < 0x80
+      raise ParseError, "#{what}: indefinite length is not allowed in DER" if first == 0x80
+
+      count = first & 0x7f
+      raise ParseError, "#{what}: length too large" if count > 4
+      raise ParseError, "#{what}: truncated" if limit - pos < count
+
+      length_bytes = bytes.byteslice(pos, count)
+      length = length_bytes.unpack1("H*").to_i(16)
+      if length_bytes.getbyte(0).zero? || length < 0x80
+        raise ParseError, "#{what}: length is not in its shortest form"
+      end
+
+      [length, pos + count]
+    end
+
+    def check_universal(node, what)
+      tag = node.tag
+      raise ParseError, "#{what}: unexpected end-of-contents" if tag.zero?
+      if node.constructed? != CONSTRUCTED_TYPES.include?(tag)
+        raise ParseError, "#{what}: universal type #{tag} must use the " \
+                          "#{node.constructed? ? 'primitive' : 'constructed'} encoding"
+      end
+
+      c = node.content
+      ok = case tag
+           when BOOLEAN then ["\x00".b, "\xff".b].include?(c)
+           when INTEGER, ENUMERATED then minimal_integer?(c)
+           when NULL then c.empty?
+           when BIT_STRING then valid_bit_string?(c)
+           when OBJECT_IDENTIFIER, RELATIVE_OID then valid_oid_content?(c)
+           when SET then sorted?(node.children)
+           when UTC_TIME then c.match?(/\A\d{12}Z\z/)
+           when GENERALIZED_TIME then c.match?(GENERALIZED_TIME_PATTERN)
+           else true
+           end
+      raise ParseError, "#{what}: invalid DER encoding of universal type #{tag}" unless ok
+    end
+
+    def minimal_integer?(c)
+      return false if c.empty?
+      return true if c.bytesize == 1
+
+      a = c.getbyte(0)
+      b = c.getbyte(1)
+      !((a.zero? && b < 0x80) || (a == 0xff && b >= 0x80))
+    end
+
+    def valid_bit_string?(c)
+      return false if c.empty?
+
+      unused = c.getbyte(0)
+      return unused.zero? if c.bytesize == 1
+
+      unused <= 7 && (c.getbyte(-1) & ((1 << unused) - 1)).zero?
+    end
+
+    def valid_oid_content?(c)
+      return false if c.empty? || c.getbyte(-1) >= 0x80
+
+      # no subidentifier may start with 0x80 (a non-minimal encoding)
+      c.each_byte.each_with_index.none? { |b, i| b == 0x80 && (i.zero? || c.getbyte(i - 1) < 0x80) }
+    end
+
+    # DER sorts the elements of a SET by their encodings (X.690 11.6).
+    def sorted?(nodes)
+      nodes.each_cons(2).all? { |a, b| (a.raw <=> b.raw) <= 0 }
+    end
+
+    # --- normalizing lengths ---------------------------------------------------
+
+    # Rewrites indefinite lengths and lengths not in their shortest form as
+    # definite, shortest lengths. Nothing else is changed: tags and the
+    # contents of primitive elements are copied as they are, so the result is
+    # DER only if the input was DER apart from its lengths (check it with
+    # parse). Used for time-stamp tokens from TSAs (docs/design.md 6).
+    def normalize_lengths(bytes, what)
+      raise ArgumentError, "#{what} must be a String, got #{bytes.class}" unless bytes.is_a?(String)
+
+      bytes = bytes.b
+      out, pos = normalize(bytes, 0, bytes.bytesize, 0, what)
+      raise ParseError, "#{what}: #{bytes.bytesize - pos} bytes of trailing data" unless pos == bytes.bytesize
+
+      out
+    end
+
+    def normalize(bytes, pos, limit, depth, what)
+      raise ParseError, "#{what}: nested too deeply" if depth > MAX_DEPTH
+
+      start = pos
+      id = byte_at(bytes, pos, limit, what)
+      pos += 1
+      _, pos = read_high_tag(bytes, pos, limit, what) if (id & 0x1f) == 0x1f
+      identifier = bytes.byteslice(start, pos - start)
+      constructed = id.anybits?(0x20)
+
+      first = byte_at(bytes, pos, limit, what)
+      if first == 0x80
+        raise ParseError, "#{what}: indefinite length on a primitive element" unless constructed
+
+        pos += 1
+        content = "".b
+        loop do
+          raise ParseError, "#{what}: missing end-of-contents" if limit - pos < 2
+          break if bytes.byteslice(pos, 2) == "\x00\x00".b
+
+          child, pos = normalize(bytes, pos, limit, depth + 1, what)
+          content << child
+        end
+        return [identifier + encode_length(content.bytesize) + content, pos + 2]
+      end
+
+      length, pos = read_any_length(bytes, pos, limit, what)
+      raise ParseError, "#{what}: truncated" if limit - pos < length
+
+      content = if constructed
+                  children = "".b
+                  child_pos = pos
+                  while child_pos < pos + length
+                    child, child_pos = normalize(bytes, child_pos, pos + length, depth + 1, what)
+                    children << child
+                  end
+                  children
+                else
+                  bytes.byteslice(pos, length)
+                end
+      [identifier + encode_length(content.bytesize) + content, pos + length]
+    end
+
+    # A definite length in any form (BER).
+    def read_any_length(bytes, pos, limit, what)
+      first = byte_at(bytes, pos, limit, what)
+      pos += 1
+      return [first, pos] if first < 0x80
+
+      count = first & 0x7f
+      raise ParseError, "#{what}: length too large" if count > 8 || first == 0xff
+      raise ParseError, "#{what}: truncated" if limit - pos < count
+
+      [bytes.byteslice(pos, count).unpack1("H*").to_i(16), pos + count]
+    end
+
+    # --- reading values ------------------------------------------------------
+
+    def expect(node, what, tag)
+      raise ParseError, "#{what}: expected universal type #{tag}" unless node&.universal?(tag)
+
+      node
+    end
+
+    # The children of a SEQUENCE (or of the constructed element given by
+    # context:), checking how many there are.
+    def children_of(node, what, size: nil, context: nil)
+      ok = node && node.constructed? &&
+           (context ? node.context?(context) : node.universal?(SEQUENCE))
+      raise ParseError, "#{what}: expected #{context ? "[#{context}]" : 'a SEQUENCE'}" unless ok
+      if size && !(size === node.children.size)
+        raise ParseError, "#{what}: unexpected number of elements (#{node.children.size})"
+      end
+
+      node.children
+    end
+
+    # The OID as a frozen dotted String.
+    def oid(node, what)
+      c = expect(node, what, OBJECT_IDENTIFIER).content
+      ids = []
+      value = 0
+      c.each_byte do |b|
+        value = (value << 7) | (b & 0x7f)
+        next if b >= 0x80
+
+        ids << value
+        value = 0
+      end
+      first = [ids[0] / 40, 2].min
+      [first, ids[0] - (first * 40), *ids[1..]].join(".").freeze
+    end
+
+    def integer(node, what)
+      c = expect(node, what, INTEGER).content
+      value = c.unpack1("H*").to_i(16)
+      c.getbyte(0) >= 0x80 ? value - (1 << (8 * c.bytesize)) : value
+    end
+
+    def octet_string(node, what)
+      expect(node, what, OCTET_STRING).content
+    end
+
+    # A frozen UTC Time, keeping fractions of a second. Frozen because Time
+    # has methods that change it (Time#localtime), and the Time is held by
+    # immutable objects (TimeStampToken#gen_time).
+    def generalized_time(node, what)
+      m = GENERALIZED_TIME_PATTERN.match(expect(node, what, GENERALIZED_TIME).content)
+      year, month, day, hour, minute, second = m.captures.first(6).map(&:to_i)
+      fraction = m[7] ? Rational(m[7].to_i, 10**m[7].size) : 0
+      time = Time.utc(year, month, day, hour, minute, second + fraction)
+      unless [time.year, time.month, time.day, time.hour, time.min, time.sec] ==
+             [year, month, day, hour, minute, second]
+        raise ParseError, "#{what}: invalid time"
+      end
+
+      time.freeze
+    rescue ArgumentError
+      raise ParseError, "#{what}: invalid time"
+    end
+
+    # --- encoding --------------------------------------------------------------
+
+    # A TLV with a one-byte identifier.
+    def encode(identifier, content)
+      [identifier].pack("C") + encode_length(content.bytesize) + content.b
+    end
+
+    def encode_length(length)
+      return [length].pack("C") if length < 0x80
+
+      bytes = [length.to_s(16).then { _1.size.odd? ? "0#{_1}" : _1 }].pack("H*")
+      [0x80 | bytes.bytesize].pack("C") + bytes
+    end
+
+    def sequence(parts)
+      encode(0x20 | SEQUENCE, parts.map(&:b).join)
+    end
+
+    # A constructed context-specific element [tag] (tag < 31).
+    def context(tag, content)
+      encode(0xa0 | tag, content)
+    end
+
+    def encode_octet_string(bytes)
+      encode(OCTET_STRING, bytes)
+    end
+
+    def encode_integer(value)
+      OpenSSL::ASN1::Integer.new(value).to_der
+    end
+
+    def encode_oid(dotted)
+      OpenSSL::ASN1::ObjectId.new(dotted).to_der
+    end
+  end
+end

data/lib/evidence_record/digest.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module EvidenceRecord
+  # An immutable hash value. The bytes are always held as a frozen BINARY
+  # String. The same design as CTMerkle::Digest of the ct_merkle gem.
+  #
+  # A Digest does not know its hash algorithm: in RFC 4998 the algorithm is
+  # given by the context (the ArchiveTimeStamp or ArchiveTimeStampChain).
+  class Digest
+    HEX_PATTERN = /\A(?:[0-9a-fA-F]{2})*\z/
+
+    class << self
+      def from_hex(str)
+        raise ArgumentError, "hex must be a String, got #{str.class}" unless str.is_a?(String)
+        raise ArgumentError, "invalid hex string: #{str.inspect}" unless HEX_PATTERN.match?(str)
+
+        new([str].pack("H*"))
+      end
+
+      def from_base64(str)
+        raise ArgumentError, "base64 must be a String, got #{str.class}" unless str.is_a?(String)
+
+        bytes = begin
+          str.unpack1("m0")
+        rescue ArgumentError
+          raise ArgumentError, "invalid base64 string: #{str.inspect}"
+        end
+        new(bytes)
+      end
+
+      # Returns the bytes of a Digest or a String as a frozen BINARY String.
+      # Used internally to accept both kinds of arguments.
+      def bytes_of(value, name = "hash")
+        case value
+        when Digest then value.to_binary
+        when String then value.b.freeze
+        else raise ArgumentError, "#{name} must be an EvidenceRecord::Digest or a binary String, got #{value.class}"
+        end
+      end
+
+      # Wraps a Digest or a binary String as a Digest.
+      def wrap(value, name = "hash")
+        value.is_a?(Digest) ? value : new(bytes_of(value, name))
+      end
+    end
+
+    def initialize(bytes)
+      raise ArgumentError, "bytes must be a String, got #{bytes.class}" unless bytes.is_a?(String)
+
+      @bytes = bytes.b.freeze
+      freeze
+    end
+
+    def to_binary
+      @bytes
+    end
+
+    def to_hex
+      @bytes.unpack1("H*")
+    end
+
+    def to_base64
+      [@bytes].pack("m0")
+    end
+
+    alias to_s to_hex
+
+    def inspect
+      "#<#{self.class.name} #{to_hex}>"
+    end
+
+    def bytesize
+      @bytes.bytesize
+    end
+
+    # Compares bytes with another Digest or a String (encoding is ignored).
+    def ==(other)
+      case other
+      when Digest then @bytes == other.to_binary
+      when String then @bytes == other.b
+      else false
+      end
+    end
+
+    # Only Digests are eql?, so that #hash stays consistent.
+    def eql?(other)
+      other.is_a?(Digest) && @bytes.eql?(other.to_binary)
+    end
+
+    def hash
+      [Digest, @bytes].hash
+    end
+  end
+end

data/lib/evidence_record/digest_algorithm.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require "openssl"
+
+module EvidenceRecord
+  # A supported hash algorithm. Only SHA-256, SHA-384 and SHA-512 are
+  # supported (docs/design.md 4.4).
+  #
+  # Instances are looked up with DigestAlgorithm.fetch (by Symbol) or
+  # DigestAlgorithm.from_oid; they are frozen singletons.
+  class DigestAlgorithm
+    attr_reader :name, :oid, :digest_size
+
+    def initialize(name, oid, openssl_name, digest_size)
+      @name = name
+      @oid = oid
+      @openssl_name = openssl_name
+      @digest_size = digest_size
+      freeze
+    end
+
+    SHA256 = new(:sha256, "2.16.840.1.101.3.4.2.1", "SHA256", 32)
+    SHA384 = new(:sha384, "2.16.840.1.101.3.4.2.2", "SHA384", 48)
+    SHA512 = new(:sha512, "2.16.840.1.101.3.4.2.3", "SHA512", 64)
+
+    ALL = [SHA256, SHA384, SHA512].freeze
+    BY_NAME = ALL.to_h { [_1.name, _1] }.freeze
+    BY_OID = ALL.to_h { [_1.oid, _1] }.freeze
+
+    class << self
+      # Accepts a Symbol (:sha256, :sha384, :sha512) or a DigestAlgorithm.
+      def fetch(value)
+        case value
+        when DigestAlgorithm then value
+        when Symbol
+          BY_NAME.fetch(value) do
+            raise UnsupportedAlgorithmError,
+                  "unsupported digest algorithm #{value.inspect} (supported: #{BY_NAME.keys.map(&:inspect).join(', ')})"
+          end
+        else raise ArgumentError, "digest algorithm must be a Symbol, got #{value.class}"
+        end
+      end
+
+      def from_oid(oid)
+        BY_OID.fetch(oid) { raise UnsupportedAlgorithmError, "unsupported digest algorithm OID #{oid}" }
+      end
+    end
+
+    # The hash of the concatenation of parts, as a BINARY String.
+    def digest(*parts)
+      d = new_openssl_digest
+      parts.each { d.update(_1) }
+      d.digest
+    end
+
+    def new_openssl_digest
+      OpenSSL::Digest.new(@openssl_name)
+    end
+
+    def to_s
+      @name.to_s
+    end
+
+    def inspect
+      "#<#{self.class.name} #{@name}>"
+    end
+  end
+end

data/lib/evidence_record/errors.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module EvidenceRecord
+  # Base class of all errors raised by this library.
+  # Invalid arguments are reported with the standard ArgumentError instead.
+  class Error < StandardError; end
+
+  # The input is not valid DER, or does not match the RFC 4998 structures.
+  class ParseError < Error; end
+
+  # A hash algorithm that this library does not support (only SHA-256,
+  # SHA-384 and SHA-512 are supported).
+  class UnsupportedAlgorithmError < Error; end
+
+  # The time-stamp response from a TSA cannot be used: it was rejected, or its
+  # message imprint does not match the request.
+  class TimestampResponseError < Error; end
+
+  # Raised by verify! when an Evidence Record does not verify.
+  #
+  # chain_index and ats_index tell where the verification failed. They are nil
+  # when the failure is not tied to a specific ArchiveTimeStamp.
+  class VerificationError < Error
+    attr_reader :chain_index, :ats_index
+
+    def initialize(message = nil, chain_index: nil, ats_index: nil)
+      super(message)
+      @chain_index = chain_index
+      @ats_index = ats_index
+    end
+  end
+
+  # The Evidence Record is structurally invalid: an empty chain, mixed hash
+  # algorithms within a chain, and so on.
+  class MalformedRecordError < VerificationError; end
+
+  # The data is not covered by the Evidence Record, or a computed root does not
+  # match the message imprint of its time-stamp.
+  class HashMismatchError < VerificationError; end
+
+  # The time-stamp validator rejected a time-stamp token.
+  class TimestampInvalidError < VerificationError; end
+end

data/lib/evidence_record/generator.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module EvidenceRecord
+  # Builds Evidence Records for many data objects with one time-stamp
+  # (docs/design.md 3.3).
+  #
+  #   gen = EvidenceRecord::Generator.new(digest_algorithm: :sha256)
+  #   gen.add("doc-a")                                          # => 0
+  #   gen.add(EvidenceRecord::DataGroup.new([meta, body]))      # => 1
+  #   req = gen.timestamp_request(nonce: SecureRandom.random_number(2**64))
+  #   res = post_to_tsa(req.to_der)          # the TSA response, as a String
+  #   records = gen.build(res)               # => [Record, Record], in add order
+  #
+  # The data are hashed when they are added and are not kept. Data cannot be
+  # added once timestamp_request or build has been called, because the
+  # time-stamp covers the hash tree at that point.
+  #
+  # build checks that the response is granted and matches the request, but
+  # does not check its signature; verify the records for that.
+  #
+  # Not thread-safe.
+  class Generator
+    attr_reader :digest_algorithm
+
+    # digest_algorithm: :sha256, :sha384 or :sha512.
+    def initialize(digest_algorithm: :sha256)
+      @digest_algorithm = DigestAlgorithm.fetch(digest_algorithm)
+      @tree = HashTree.new(digest_algorithm: @digest_algorithm)
+      @groups = []
+      @closed = false
+    end
+
+    # Adds a data object (a String or a PrehashedData) or a DataGroup, and
+    # returns its index: the position of its record in the result of build.
+    def add(data)
+      raise Error, "data cannot be added after timestamp_request or build" if @closed
+
+      source = DataSource.wrap(data)
+      index = @tree.add(source.member_digests(@digest_algorithm))
+      @groups << source.group?
+      index
+    end
+
+    # The number of data objects and groups added.
+    def size
+      @tree.size
+    end
+
+    # The root of the hash tree: the hash value to be time-stamped.
+    def root
+      raise Error, "no data has been added" if @tree.empty?
+
+      @tree.root
+    end
+
+    # An OpenSSL::Timestamp::Request for the root, to be sent to a TSA. When
+    # nonce or policy_id is given, build checks that the response has the
+    # same values.
+    def timestamp_request(nonce: nil, cert_requested: true, policy_id: nil)
+      exchange.request(nonce: nonce, cert_requested: cert_requested, policy_id: policy_id)
+    end
+
+    # Builds the records from the TSA response (a String, or an
+    # OpenSSL::Timestamp::Response). Returns an Array of Records in the order
+    # the data were added. Raises TimestampResponseError when the response
+    # is not usable.
+    def build(response)
+      timestamp = exchange.token(response)
+      Array.new(size) { |i| Record.build([Chain.build([archive_timestamp(i, timestamp)])]) }
+    end
+
+    private
+
+    def exchange
+      @exchange ||= begin
+        imprint = root
+        @closed = true
+        TimestampExchange.new(@digest_algorithm, imprint)
+      end
+    end
+
+    # A single data object time-stamped alone needs no reduced hash tree: its
+    # hash is the message imprint (as Bouncy Castle does).
+    def archive_timestamp(index, timestamp)
+      return ArchiveTimeStamp.build(timestamp: timestamp) if size == 1 && !@groups[0]
+
+      ArchiveTimeStamp.build(timestamp: timestamp, reduced_hashtree: @tree.reduced_hashtree(index),
+                             digest_algorithm: @digest_algorithm)
+    end
+  end
+end