evidence_record 0.1.0

data/lib/evidence_record/timestamp_exchange.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+module EvidenceRecord
+  # Internal: one exchange with a TSA for a hash value (docs/design.md 3.3,
+  # 6). Makes the request and takes the time-stamp token out of the response
+  # after checking it. Used by Generator and the renewals.
+  class TimestampExchange
+    GRANTED = 0
+    GRANTED_WITH_MODS = 1
+
+    def initialize(algorithm, imprint)
+      @algorithm = algorithm
+      @imprint = Digest.wrap(imprint)
+    end
+
+    # An OpenSSL::Timestamp::Request for the hash value. The nonce and policy
+    # given here are checked against the response in #token.
+    def request(nonce: nil, cert_requested: true, policy_id: nil)
+      raise ArgumentError, "nonce must be an Integer, got #{nonce.class}" unless nonce.nil? || nonce.is_a?(Integer)
+      unless policy_id.nil? || policy_id.is_a?(String)
+        raise ArgumentError, "policy_id must be a String (OID), got #{policy_id.class}"
+      end
+
+      @nonce = nonce
+      @policy_id = policy_id
+      request = OpenSSL::Timestamp::Request.new
+      request.algorithm = @algorithm.name.to_s.upcase
+      request.message_imprint = @imprint.to_binary
+      request.nonce = nonce if nonce
+      request.policy_id = policy_id if policy_id
+      request.cert_requested = cert_requested ? true : false
+      request
+    end
+
+    # The TimeStampToken in response: a String (the TimeStampResp as
+    # returned by the TSA) or an OpenSSL::Timestamp::Response. Lengths encoded
+    # as BER are rewritten as DER; anything else that is not DER is rejected
+    # (docs/design.md 6). Raises TimestampResponseError when the response
+    # cannot be used.
+    #
+    # The signature is not checked here; verify the resulting record.
+    def token(response)
+      token = extract(response_bytes(response))
+      check!(token)
+      token
+    end
+
+    private
+
+    def response_bytes(response)
+      case response
+      when String then response
+      when OpenSSL::Timestamp::Response then response.to_der
+      else
+        raise ArgumentError,
+              "response must be a String or an OpenSSL::Timestamp::Response, got #{response.class}"
+      end
+    end
+
+    # TimeStampResp ::= SEQUENCE { status PKIStatusInfo,
+    #   timeStampToken TimeStampToken OPTIONAL }
+    # PKIStatusInfo ::= SEQUENCE { status PKIStatus,
+    #   statusString PKIFreeText OPTIONAL, failInfo PKIFailureInfo OPTIONAL }
+    def extract(bytes)
+      node = DER.parse(DER.normalize_lengths(bytes, "time-stamp response"), "time-stamp response")
+      status_info, token = DER.children_of(node, "time-stamp response", size: 1..2)
+      status, *details = DER.children_of(status_info, "time-stamp response status", size: 1..3)
+      code = DER.integer(status, "time-stamp response status")
+      unless [GRANTED, GRANTED_WITH_MODS].include?(code)
+        raise TimestampResponseError, "the TSA rejected the request (status #{code}#{status_text(details)})"
+      end
+      raise TimestampResponseError, "the response has no time-stamp token" unless token
+
+      TimeStampToken.from_node(token, "time-stamp token")
+    rescue ParseError => e
+      raise TimestampResponseError, "invalid time-stamp response: #{e.message}"
+    end
+
+    # PKIFreeText ::= SEQUENCE SIZE (1..MAX) OF UTF8String
+    def status_text(details)
+      text = details.find { _1.universal?(DER::SEQUENCE) }
+      return "" unless text
+
+      strings = text.children.select { _1.universal?(12) }.map { _1.content.dup.force_encoding(Encoding::UTF_8).scrub }
+      strings.empty? ? "" : ": #{strings.join('; ')}"
+    end
+
+    def check!(token)
+      unless token.hash_algorithm_oid == @algorithm.oid
+        raise TimestampResponseError,
+              "the time-stamp uses hash algorithm #{token.hash_algorithm_oid}, but #{@algorithm} was requested"
+      end
+      unless token.message_imprint == @imprint
+        raise TimestampResponseError, "the message imprint of the time-stamp does not match the request"
+      end
+      if @nonce && token.nonce != @nonce
+        raise TimestampResponseError, "the nonce of the time-stamp does not match the request"
+      end
+      return unless @policy_id && token.policy_id != @policy_id
+
+      raise TimestampResponseError, "the policy of the time-stamp does not match the request"
+    end
+  end
+end

data/lib/evidence_record/timestamp_renewal.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module EvidenceRecord
+  # A time-stamp renewal of a Record (RFC 4998 §5.2, docs/design.md 3.4):
+  # a new ArchiveTimeStamp, added to the last chain, that covers the
+  # time-stamps of that chain. Done before the time-stamps become invalid
+  # (for example, before the TSA certificate expires).
+  #
+  #   renewal = record.timestamp_renewal
+  #   req     = renewal.timestamp_request(nonce: SecureRandom.random_number(2**64))
+  #   res     = post_to_tsa(req.to_der)        # the TSA response, as a String
+  #   record2 = renewal.build(res)             # => a new Record
+  #
+  # The new time-stamp covers all the time-stamps of the last chain, as one
+  # data object group, as Bouncy Castle does. Its hash algorithm is the one
+  # of the last chain; when that algorithm weakens, use a hash-tree renewal
+  # (HashTreeRenewal) instead.
+  #
+  # The data are not needed and the record is not verified. Records built
+  # from the same hash tree and renewed in the same way have the same
+  # time-stamps, so one TSA response can renew all of them: build a renewal
+  # for each record and pass the same response to build.
+  #
+  # See Renewal for #timestamp_request and #build.
+  class TimestampRenewal
+    include Renewal
+
+    # Internal: use Record#timestamp_renewal.
+    def initialize(record)
+      chain = record.chains.last
+      if chain.nil? || chain.archive_timestamps.empty?
+        raise MalformedRecordError, "the record has no ArchiveTimeStamp to renew"
+      end
+
+      oids = chain.archive_timestamps.map(&:digest_algorithm_oid).uniq
+      raise MalformedRecordError, "hash algorithms are mixed within the last chain" unless oids.size == 1
+
+      @chain = chain
+      algorithm = DigestAlgorithm.from_oid(oids[0])
+      prepare(record, algorithm, chain.archive_timestamps.map { algorithm.digest(_1.timestamp.to_der) })
+    end
+
+    private
+
+    def renewed_chains(archive_timestamp)
+      @record.chains[0...-1] + [Chain.build(@chain.archive_timestamps + [archive_timestamp])]
+    end
+  end
+end

data/lib/evidence_record/timestamp_validator.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module EvidenceRecord
+  # Time-stamp validators: objects that check that a time-stamp token itself
+  # is valid (docs/design.md 5.3).
+  #
+  # A validator responds to call(token, at:), where token is a TimeStampToken
+  # and at is the Time at which the token must be valid. It returns a truthy
+  # value when the token is valid. When it is not, it raises
+  # EvidenceRecord::TimestampInvalidError or returns false or nil; both are
+  # treated as invalid, so a validator that forgets to return true fails
+  # closed. Other exceptions are not caught.
+  module TimestampValidator
+    # Checks the signature of the token and its certificate chain at the given
+    # time with OpenSSL, using a store of trusted certificates.
+    #
+    #   store = OpenSSL::X509::Store.new
+    #   store.add_cert(tsa_root)
+    #   validator = EvidenceRecord::TimestampValidator::OpenSSL.new(store: store)
+    #
+    # What it checks: the signature, that the signing certificate is the one
+    # named in the token (ESS signing certificate), that it may be used for
+    # time-stamping, and that its chain to a trusted certificate is valid at
+    # the given time.
+    #
+    # What it does not check: revocation (CRL / OCSP) unless the store is set
+    # up for it, and whether the algorithms used are still considered secure.
+    # Give your own validator for those.
+    #
+    # The store's verification time is set on every call, so do not share the
+    # store with other code that relies on it.
+    class OpenSSL
+      def initialize(store:)
+        unless store.is_a?(::OpenSSL::X509::Store)
+          raise ArgumentError, "store must be an OpenSSL::X509::Store, got #{store.class}"
+        end
+
+        @store = store
+      end
+
+      def call(token, at:)
+        raise ArgumentError, "token must be an EvidenceRecord::TimeStampToken" unless token.is_a?(TimeStampToken)
+        raise ArgumentError, "at must be a Time, got #{at.class}" unless at.is_a?(Time)
+
+        @store.time = at
+        response_for(token).verify(request_for(token), @store)
+        true
+      rescue ::OpenSSL::Timestamp::TimestampError => e
+        raise TimestampInvalidError, "invalid time-stamp: #{e.message}"
+      end
+
+      private
+
+      # A request that the token must match. It is built from the token
+      # itself: the hash chain has already been checked against the imprint.
+      def request_for(token)
+        request = ::OpenSSL::Timestamp::Request.new
+        request.algorithm = token.hash_algorithm.name.to_s.upcase
+        request.message_imprint = token.message_imprint.to_binary
+        request.nonce = token.nonce if token.nonce
+        request
+      end
+
+      # A granted TimeStampResp holding the token without its crls field
+      # (docs/design.md 7.2).
+      def response_for(token)
+        status = DER.sequence([DER.encode_integer(0)])
+        ::OpenSSL::Timestamp::Response.new(DER.sequence([status, token.der_without_crls]))
+      end
+    end
+  end
+end

data/lib/evidence_record/verifier.rb

@@ -0,0 +1,158 @@
+# frozen_string_literal: true
+
+module EvidenceRecord
+  # Internal: verifies a Record against data (docs/design.md 5.1). Used by
+  # Record#verify!, #verify_hashes! and the renewals.
+  class Verifier
+    def initialize(record, data)
+      @record = record
+      @data = DataSource.wrap(data)
+    end
+
+    # Steps 1-3: the structure and the hash chain, without looking at the
+    # signatures or the times of the time-stamps.
+    def verify_hashes!
+      check_structure!
+      @record.chains.each_with_index { |chain, ci| verify_chain!(chain, ci) }
+      true
+    end
+
+    # All steps.
+    def verify!(timestamp_validator:, at:)
+      verify_hashes!
+      check_times!(at)
+      validate_timestamps!(timestamp_validator, at)
+      true
+    end
+
+    private
+
+    # [ArchiveTimeStamp, chain index, index in chain] in chronological order.
+    def entries
+      @record.chains.each_with_index.flat_map do |chain, ci|
+        chain.archive_timestamps.each_with_index.map { |ats, ai| [ats, ci, ai] }
+      end
+    end
+
+    # Step 1.
+    def check_structure!
+      raise MalformedRecordError, "the record has no ArchiveTimeStampChain" if @record.chains.empty?
+
+      @record.chains.each_with_index do |chain, ci|
+        if chain.archive_timestamps.empty?
+          raise MalformedRecordError.new("chain #{ci} has no ArchiveTimeStamp", chain_index: ci)
+        end
+
+        oid = chain.archive_timestamps[0].digest_algorithm_oid
+        chain.archive_timestamps.each_with_index { |ats, ai| check_archive_timestamp!(ats, oid, ci, ai) }
+      end
+    end
+
+    def check_archive_timestamp!(ats, chain_oid, ci, ai)
+      where = { chain_index: ci, ats_index: ai }
+      unless ats.digest_algorithm_oid == chain_oid
+        raise MalformedRecordError.new("#{at(ci, ai)}: hash algorithms are mixed within a chain", **where)
+      end
+      declared = ats.declared_digest_algorithm_oid
+      if declared && declared != ats.timestamp.hash_algorithm_oid
+        raise MalformedRecordError.new(
+          "#{at(ci, ai)}: digestAlgorithm differs from the hash algorithm of the time-stamp", **where
+        )
+      end
+
+      algorithm = ats.digest_algorithm # raises UnsupportedAlgorithmError
+      values = ats.reduced_hashtree&.partial_hashtrees&.flatten || []
+      return if values.all? { _1.bytesize == algorithm.digest_size }
+
+      raise MalformedRecordError.new("#{at(ci, ai)}: a hash in reducedHashtree is not a #{algorithm} hash", **where)
+    end
+
+    # Steps 2 and 3.
+    def verify_chain!(chain, ci)
+      algorithm = chain.archive_timestamps[0].digest_algorithm
+      chain.archive_timestamps.each_with_index do |ats, ai|
+        if ai.zero?
+          check_covered!(ats, algorithm, data_hash_candidates(algorithm, ci), "the data", ci, ai)
+        else
+          previous = chain.archive_timestamps[ai - 1].timestamp.to_der
+          check_covered!(ats, algorithm, [[algorithm.digest(previous)]], "the previous time-stamp", ci, ai)
+        end
+      end
+    end
+
+    # The hashes that the first partial hash tree of chain ci must contain,
+    # as alternatives. In the first chain they are the hashes of the data
+    # (each member of a data group). In later chains they are H(H(d) + ha),
+    # where ha is the hash of the older chains; both the fixed order and the
+    # sorted order of the concatenation are accepted (docs/design.md 3.5).
+    def data_hash_candidates(algorithm, ci)
+      hashes = @data.member_digests(algorithm)
+      return [hashes] if ci.zero?
+
+      ha = algorithm.digest(@record.archive_timestamp_sequence_der(ci))
+      [hashes.map { algorithm.digest(_1, ha) }, hashes.map { algorithm.digest(*[_1, ha].sort) }].uniq
+    end
+
+    def check_covered!(ats, algorithm, candidates, subject, ci, ai)
+      imprint = ats.timestamp.message_imprint
+      contained = false
+      candidates.each do |hashes|
+        # Without a reduced hash tree, the hashes themselves make the root.
+        tree = ats.reduced_hashtree || ReducedHashtree.new([hashes])
+        next unless hashes.all? { |h| tree.leaf_values.include?(Digest.new(h)) }
+        return if tree.root(algorithm) == imprint
+
+        contained = true
+      end
+
+      where = { chain_index: ci, ats_index: ai }
+      if contained
+        raise HashMismatchError.new("#{at(ci, ai)}: the root of the hash tree does not match the time-stamp", **where)
+      end
+
+      raise HashMismatchError.new("#{at(ci, ai)}: #{subject} is not covered by the reduced hash tree", **where)
+    end
+
+    # Step 4.
+    def check_times!(time)
+      previous = nil
+      entries.each do |ats, ci, ai|
+        gen_time = ats.timestamp.gen_time
+        if previous && gen_time < previous
+          raise MalformedRecordError.new("#{at(ci, ai)}: the time-stamp is older than the one before",
+                                         chain_index: ci, ats_index: ai)
+        end
+
+        previous = gen_time
+      end
+      return if previous <= time
+
+      _, ci, ai = entries.last
+      raise TimestampInvalidError.new("#{at(ci, ai)}: the time-stamp is later than the verification time",
+                                      chain_index: ci, ats_index: ai)
+    end
+
+    # Step 5. Each time-stamp must have been valid when the next one, which
+    # covers it, was made; the last one must be valid at the verification
+    # time.
+    def validate_timestamps!(validator, time)
+      list = entries
+      list.each_with_index do |(ats, ci, ai), k|
+        reference = k + 1 < list.size ? list[k + 1][0].timestamp.gen_time : time
+        valid = begin
+          validator.call(ats.timestamp, at: reference)
+        rescue TimestampInvalidError => e
+          raise TimestampInvalidError.new("#{at(ci, ai)}: #{e.message}", chain_index: ci, ats_index: ai)
+        end
+        next if valid
+
+        raise TimestampInvalidError.new("#{at(ci, ai)}: rejected by the time-stamp validator",
+                                        chain_index: ci, ats_index: ai)
+      end
+    end
+
+    def at(ci, ai)
+      "chain #{ci}, ArchiveTimeStamp #{ai}"
+    end
+  end
+end

data/lib/evidence_record/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module EvidenceRecord
+  VERSION = "0.1.0"
+end

data/lib/evidence_record.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require_relative "evidence_record/version"
+require_relative "evidence_record/errors"
+require_relative "evidence_record/digest"
+require_relative "evidence_record/digest_algorithm"
+require_relative "evidence_record/data"
+require_relative "evidence_record/reduced_hashtree"
+require_relative "evidence_record/hash_tree"
+require_relative "evidence_record/der"
+require_relative "evidence_record/algorithm_identifier"
+require_relative "evidence_record/time_stamp_token"
+require_relative "evidence_record/archive_time_stamp"
+require_relative "evidence_record/chain"
+require_relative "evidence_record/record"
+require_relative "evidence_record/verifier"
+require_relative "evidence_record/timestamp_validator"
+require_relative "evidence_record/timestamp_exchange"
+require_relative "evidence_record/generator"
+require_relative "evidence_record/renewal"
+require_relative "evidence_record/timestamp_renewal"
+require_relative "evidence_record/hash_tree_renewal"
+
+# Evidence Record Syntax (ERS), RFC 4998.
+module EvidenceRecord
+end

metadata

@@ -0,0 +1,69 @@
+--- !ruby/object:Gem::Specification
+name: evidence_record
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Ken Tanaka
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: Generation, timestamp renewal, hash-tree renewal and verification of
+  Evidence Records as defined in RFC 4998, with no runtime dependencies beyond the
+  Ruby standard library.
+email:
+- tanaka-ken@netlab.jp
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- lib/evidence_record.rb
+- lib/evidence_record/algorithm_identifier.rb
+- lib/evidence_record/archive_time_stamp.rb
+- lib/evidence_record/chain.rb
+- lib/evidence_record/data.rb
+- lib/evidence_record/der.rb
+- lib/evidence_record/digest.rb
+- lib/evidence_record/digest_algorithm.rb
+- lib/evidence_record/errors.rb
+- lib/evidence_record/generator.rb
+- lib/evidence_record/hash_tree.rb
+- lib/evidence_record/hash_tree_renewal.rb
+- lib/evidence_record/record.rb
+- lib/evidence_record/reduced_hashtree.rb
+- lib/evidence_record/renewal.rb
+- lib/evidence_record/time_stamp_token.rb
+- lib/evidence_record/timestamp_exchange.rb
+- lib/evidence_record/timestamp_renewal.rb
+- lib/evidence_record/timestamp_validator.rb
+- lib/evidence_record/verifier.rb
+- lib/evidence_record/version.rb
+homepage: https://github.com/xketanaka/evidence_record
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/xketanaka/evidence_record
+  bug_tracker_uri: https://github.com/xketanaka/evidence_record/issues
+  documentation_uri: https://github.com/xketanaka/evidence_record/blob/main/README.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.4'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Evidence Record Syntax (ERS) compliant with RFC 4998
+test_files: []