evidence_record 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: bbd1dbdd156796ea4d19b859ab779f227e646dd67bbdc3395a82e322bef66831
+  data.tar.gz: ea49206348d9bf5e361375613b0bc7b0e6a6cbb3790efc0333abc88541e331c4
+SHA512:
+  metadata.gz: 2b93957420913d30bfbef1c4387207dc1796100c3ceabde8b794e666b775e7f84b85c1c56685dbd3ab69b4fab25ea9dc5848f39052952612ae977194c015a4f9
+  data.tar.gz: 80225299d4546a4fcd95ea35baa382ed8c5b8d0ed834ff9d2e8b5a3c2d5a95b5b08c19806de6b95f040a26a5be208bb6ece4d62ac367f23015907ffeb3ce5bd2

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Ken Tanaka
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,160 @@
+# evidence_record
+
+[RFC 4998](https://www.rfc-editor.org/rfc/rfc4998)（Evidence Record Syntax, ERS）に準拠した、Evidence Record の Ruby 実装。
+
+Evidence Record とは、データがある時点に存在しそれ以降改ざんされてないことを長期間にわたって証明するデータ構造。多数のデータをハッシュツリーにまとめてタイムスタンプ(RFC 3161)で保護する。タイムスタンプやハッシュアルゴリズムがが弱くなる前に新しいタイムスタンプやハッシュアルゴリズムに更新することができる。
+
+## 機能
+
+- 文字列または計算済みのハッシュ値を対象に Evidence Record を生成
+- 多数のデータの Evidence Record を、1 つのタイムスタンプでまとめて生成
+- タイムスタンプ更新(TSA の証明書の期限が切れる前にタイムスタンプを掛け直す)、ハッシュツリー更新(新しいハッシュアルゴリズムに移行する)
+- 外部から与えられた Evidence Record の検証。任意のハッシュツリーを RFC 4998 の手順で検証する
+- タイムスタンプの検証は差し替え可能。OpenSSL で署名と証明書チェーンを検証する検証器を同梱
+- TSA との通信は行わない
+- [BSI のテストデータ](https://github.com/bcgit/bc-test-data)で動作を確認済み。[Bouncy Castle](https://www.bouncycastle.org/) と双方向に相互運用できることを確認済み
+- 依存ライブラリなし
+
+## インストール
+
+```bash
+gem install evidence_record
+
+# or
+
+bundle add evidence_record
+```
+
+## 使い方
+
+### 生成
+
+```ruby
+gen = EvidenceRecord::Generator.new(digest_algorithm: :sha256)
+gen.add("doc-a")
+gen.add(EvidenceRecord::DataGroup.new([meta_xml, body_pdf]))  # グループは 1 つの Evidence Record になる
+
+# タイムスタンプ要求(OpenSSL::Timestamp::Request)を作り、TSA に送る
+req = gen.timestamp_request(nonce: SecureRandom.random_number(2**64))
+res = post_to_tsa(req.to_der)   # res: TSA の応答(TimeStampResp のバイト列)
+
+# add した順に Evidence Record が返る
+records = gen.build(res)        # => [Record, Record]
+File.binwrite("doc-a.ers", records[0].to_der)
+```
+
+タイムスタンプ取得(post_to_tsa)の実装例
+
+```ruby
+def post_to_tsa(der)
+  uri = URI("https://tsa.example.com/")
+  res = Net::HTTP.post(uri, der, "Content-Type" => "application/timestamp-query")
+  raise "TSA error: #{res.code}" unless res.is_a?(Net::HTTPSuccess)
+
+  res.body
+end
+```
+
+### 検証
+
+```ruby
+record = EvidenceRecord::Record.from_der(File.binread("doc-a.ers"))
+
+# TSA の証明書チェーンを検証する
+store = OpenSSL::X509::Store.new
+store.add_cert(tsa_root_certificate)
+validator = EvidenceRecord::TimestampValidator::OpenSSL.new(store: store)
+
+record.verify(data: "doc-a", timestamp_validator: validator)    # => true / false
+record.verify!(data: "doc-a", timestamp_validator: validator)   # 失敗すると例外
+record.proven_time                                              # データの存在が証明される時刻(タイムスタンプの genTime)
+```
+
+検証では、データからすべてのタイムスタンプまでのハッシュの連鎖、各タイムスタンプの正当性を確認する。
+
+### タイムスタンプ更新
+
+TSA の証明書の期限が切れる前にタイムスタンプを掛け直す
+
+```ruby
+renewal = record.timestamp_renewal
+req     = renewal.timestamp_request(nonce: SecureRandom.random_number(2**64))
+record2 = renewal.build(post_to_tsa(req.to_der))   # => 新しい Record
+```
+
+### ハッシュツリー更新
+
+使っているハッシュアルゴリズムが弱くなった際に新しいアルゴリズムに移行する。データが必要。
+
+```ruby
+renewal = record.hash_tree_renewal(data: "doc-a", digest_algorithm: :sha512)
+req     = renewal.timestamp_request(nonce: SecureRandom.random_number(2**64))
+record3 = renewal.build(post_to_tsa(req.to_der))   # => 新しい Chain が追加された Record
+```
+
+### 計算済みのハッシュ値
+
+データ本体の代わりにあらかじめ手計算したハッシュ値を指定可能。
+
+```ruby
+pre = EvidenceRecord::PrehashedData.new(
+  sha256: OpenSSL::Digest.new("SHA256").file("large.bin").digest,
+  sha512: OpenSSL::Digest.new("SHA512").file("large.bin").digest,
+)
+gen.add(pre)
+record.verify(data: pre, timestamp_validator: validator)
+record.hash_tree_renewal(data: pre, digest_algorithm: :sha512)
+```
+
+### Evidence Record の内容確認
+
+```ruby
+record.chains.each do |chain|
+  chain.archive_timestamps.each do |ats|
+    ts = ats.timestamp
+    puts "#{ats.digest_algorithm} #{ts.gen_time} serial=#{ts.serial_number}"
+  end
+end
+
+# 最後のタイムスタンプの TSA 証明書の期限を調べる
+last = record.chains.last.archive_timestamps.last.timestamp
+last.certificates.map(&:not_after)
+```
+
+### 参照
+
+- 各クラス・メソッドの仕様は [docs/reference.md](docs/reference.md) を参照
+
+## 開発
+
+```bash
+bundle install
+bundle exec rake test
+```
+
+BSI のテストデータを使うテストは、データをダウンロードしてから実行する。
+テストデータは [bcgit/bc-test-data](https://github.com/bcgit/bc-test-data) の `tsp/20170316_Testdaten` (BSI TR-ESOR / ERS テストツール)から固定したコミットのものを取得し、SHA-256 で内容を確認する。
+
+```bash
+bundle exec rake test:fetch_vectors   # test/fixtures/bsi に取得する
+```
+
+Bouncy Castle との相互運用テストには JDK が必要。Bouncy Castle は Maven Central から固定したバージョンのものを取得し、SHA-256 で内容を確認する。
+
+```bash
+bundle exec rake test:fetch_bouncy_castle   # interop/lib に取得する
+bundle exec rake test:interop
+```
+
+Docker を使う場合：
+
+```bash
+docker compose run --rm test        # Ruby 4.0
+docker compose run --rm test-3.4    # Ruby 3.4
+docker compose run --rm test bundle exec rake test:fetch_vectors
+docker compose run --rm interop     # Bouncy Castle との相互運用テスト（JDK 入りのイメージ）
+```
+
+## ライセンス
+
+[MIT License](LICENSE.txt)

data/lib/evidence_record/algorithm_identifier.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module EvidenceRecord
+  # Internal: reading and writing the AlgorithmIdentifiers of hash
+  # algorithms.
+  #
+  # Any OID is read, so that Evidence Records using other algorithms can still
+  # be parsed; DigestAlgorithm.from_oid raises UnsupportedAlgorithmError when
+  # such an algorithm is used. Parameters of SHA-2 must be absent or NULL
+  # (RFC 5754 §2); absent is generated.
+  module AlgorithmIdentifier
+    module_function
+
+    # node: a SEQUENCE, or with context: n, a constructed element with the
+    # implicit tag [n]. Returns the OID as a dotted String.
+    def parse(node, what, context: nil)
+      children = DER.children_of(node, "#{what} (AlgorithmIdentifier)", size: 1..2, context: context)
+      oid = DER.oid(children[0], what)
+      params = children[1]
+      if params && DigestAlgorithm::BY_OID.key?(oid) && !params.universal?(DER::NULL)
+        raise ParseError, "#{what}: parameters of #{DigestAlgorithm::BY_OID[oid]} must be absent or NULL"
+      end
+
+      oid
+    end
+
+    # The contents octets of an AlgorithmIdentifier (to be wrapped in a
+    # SEQUENCE or an implicit tag).
+    def encode_content(algorithm)
+      DER.encode_oid(algorithm.oid)
+    end
+
+    def encode(algorithm)
+      DER.sequence([encode_content(algorithm)])
+    end
+  end
+end

data/lib/evidence_record/archive_time_stamp.rb

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+module EvidenceRecord
+  # An ArchiveTimeStamp (RFC 4998 §4.1): a time-stamp token and the reduced
+  # hash tree leading from a data object (or an earlier time-stamp) to the
+  # time-stamped root.
+  #
+  #   ArchiveTimeStamp ::= SEQUENCE {
+  #     digestAlgorithm [0] AlgorithmIdentifier OPTIONAL,
+  #     attributes      [1] Attributes OPTIONAL,
+  #     reducedHashtree [2] SEQUENCE OF PartialHashtree OPTIONAL,
+  #     timeStamp       ContentInfo }
+  #
+  # The original DER is kept and returned by #to_der.
+  class ArchiveTimeStamp
+    # The time-stamp token (TimeStampToken).
+    attr_reader :timestamp
+    # The ReducedHashtree, or nil when the field is absent (the time-stamp
+    # covers the hash of a single data object directly).
+    attr_reader :reduced_hashtree
+    # The attributes field as it was read (DER, including its [1] tag), or
+    # nil. It is kept but not interpreted (docs/design.md 7.3).
+    attr_reader :attributes
+    # Internal: the OID of the digestAlgorithm field, or nil when absent.
+    attr_reader :declared_digest_algorithm_oid
+
+    class << self
+      def from_der(der)
+        from_node(DER.parse(der, "ArchiveTimeStamp"), "ArchiveTimeStamp")
+      end
+
+      # Internal: from an already parsed element.
+      def from_node(node, what)
+        new(node, what)
+      end
+
+      # Internal: encodes a new ArchiveTimeStamp. Used by the generator and
+      # the renewals.
+      def build(timestamp:, reduced_hashtree: nil, digest_algorithm: nil)
+        parts = []
+        parts << DER.context(0, AlgorithmIdentifier.encode_content(digest_algorithm)) if digest_algorithm
+        if reduced_hashtree
+          partials = reduced_hashtree.partial_hashtrees.map do |values|
+            DER.sequence(values.map { DER.encode_octet_string(_1.to_binary) })
+          end
+          parts << DER.context(2, partials.join)
+        end
+        parts << timestamp.to_der
+        from_der(DER.sequence(parts))
+      end
+
+      private :new
+    end
+
+    def initialize(node, what)
+      @der = node.raw
+      *fields, timestamp = DER.children_of(node, what, size: 1..4)
+      @timestamp = TimeStampToken.from_node(timestamp, "#{what} timeStamp")
+
+      previous_tag = -1
+      fields.each do |field|
+        tag = field.tag_class == :context && field.constructed? ? field.tag : nil
+        unless tag && tag <= 2 && tag > previous_tag
+          raise ParseError, "#{what}: unexpected element before timeStamp"
+        end
+
+        previous_tag = tag
+        case tag
+        when 0 then @declared_digest_algorithm_oid = AlgorithmIdentifier.parse(field, "#{what} digestAlgorithm", context: 0)
+        when 1 then @attributes = parse_attributes(field, "#{what} attributes")
+        when 2 then @reduced_hashtree = parse_reduced_hashtree(field, "#{what} reducedHashtree")
+        end
+      end
+      freeze
+    end
+
+    # The OID of the hash algorithm of the reduced hash tree: the
+    # digestAlgorithm field, or the hash algorithm of the time-stamp when the
+    # field is absent (RFC 4998 §4.1).
+    def digest_algorithm_oid
+      @declared_digest_algorithm_oid || @timestamp.hash_algorithm_oid
+    end
+
+    # The hash algorithm of the reduced hash tree, as a DigestAlgorithm.
+    # Raises UnsupportedAlgorithmError for other algorithms.
+    def digest_algorithm
+      DigestAlgorithm.from_oid(digest_algorithm_oid)
+    end
+
+    def to_der
+      @der
+    end
+
+    def ==(other)
+      other.is_a?(ArchiveTimeStamp) && to_der == other.to_der
+    end
+    alias eql? ==
+
+    def hash
+      [ArchiveTimeStamp, @der].hash
+    end
+
+    def inspect
+      shape = @reduced_hashtree ? @reduced_hashtree.partial_hashtrees.map(&:size).join("-") : "none"
+      "#<#{self.class.name} digest_algorithm_oid=#{digest_algorithm_oid} " \
+        "reduced_hashtree=#{shape} timestamp=#{@timestamp.inspect}>"
+    end
+
+    private
+
+    # Attributes ::= SET SIZE (1..MAX) OF Attribute
+    def parse_attributes(node, what)
+      if node.children.empty? || !node.children.all? { _1.universal?(DER::SEQUENCE) } ||
+         !DER.sorted?(node.children)
+        raise ParseError, "#{what}: invalid Attributes"
+      end
+
+      node.raw
+    end
+
+    # SEQUENCE OF PartialHashtree; PartialHashtree ::= SEQUENCE OF OCTET STRING
+    def parse_reduced_hashtree(node, what)
+      partials = node.children.each_with_index.map do |partial, i|
+        DER.children_of(partial, "#{what}[#{i}]").map { DER.octet_string(_1, "#{what}[#{i}]") }
+      end
+      ReducedHashtree.new(partials)
+    rescue ArgumentError => e
+      raise ParseError, "#{what}: #{e.message}"
+    end
+  end
+end

data/lib/evidence_record/chain.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module EvidenceRecord
+  # An ArchiveTimeStampChain (RFC 4998 §5): ArchiveTimeStamps that use the
+  # same hash algorithm, each covering the time-stamp of the one before.
+  #
+  # The original DER is kept and returned by #to_der.
+  class Chain
+    attr_reader :archive_timestamps
+
+    class << self
+      def from_der(der)
+        from_node(DER.parse(der, "ArchiveTimeStampChain"), "ArchiveTimeStampChain")
+      end
+
+      # Internal: from an already parsed element.
+      def from_node(node, what)
+        new(node, what)
+      end
+
+      # Internal: encodes a new chain from ArchiveTimeStamps.
+      def build(archive_timestamps)
+        from_der(DER.sequence(archive_timestamps.map(&:to_der)))
+      end
+
+      private :new
+    end
+
+    def initialize(node, what)
+      @der = node.raw
+      @archive_timestamps = DER.children_of(node, what).each_with_index.map do |ats, i|
+        ArchiveTimeStamp.from_node(ats, "#{what}[#{i}]")
+      end.freeze
+      freeze
+    end
+
+    def to_der
+      @der
+    end
+
+    def ==(other)
+      other.is_a?(Chain) && to_der == other.to_der
+    end
+    alias eql? ==
+
+    def hash
+      [Chain, @der].hash
+    end
+
+    def inspect
+      "#<#{self.class.name} #{@archive_timestamps.inspect}>"
+    end
+  end
+end

data/lib/evidence_record/data.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+module EvidenceRecord
+  # Hash values of a data object computed elsewhere, given per algorithm
+  # (docs/design.md 3.7.1). Use it for data that is not at hand or too large
+  # to read into a String.
+  #
+  #   EvidenceRecord::PrehashedData.new(sha256: d256, sha512: d512)
+  #
+  # The library cannot check that the hashes were computed from the same data.
+  class PrehashedData
+    def initialize(**hashes)
+      raise ArgumentError, "at least one hash must be given" if hashes.empty?
+
+      @hashes = hashes.to_h do |name, value|
+        algorithm = DigestAlgorithm.fetch(name)
+        bytes = Digest.bytes_of(value, "#{name} hash")
+        unless bytes.bytesize == algorithm.digest_size
+          raise ArgumentError,
+                "#{name} hash must be #{algorithm.digest_size} bytes, got #{bytes.bytesize}"
+        end
+        [algorithm, bytes]
+      end.freeze
+      freeze
+    end
+
+    def algorithms
+      @hashes.keys
+    end
+
+    # The hash for algorithm (a Symbol or DigestAlgorithm) as a Digest, or nil.
+    def [](algorithm)
+      bytes = @hashes[DigestAlgorithm.fetch(algorithm)]
+      bytes && Digest.new(bytes)
+    end
+
+    def inspect
+      "#<#{self.class.name} #{@hashes.map { |a, b| "#{a}=#{b.unpack1('H*')}" }.join(' ')}>"
+    end
+  end
+
+  # A data object group: several data objects covered by one Evidence Record
+  # (RFC 4998 §4.2). Members are Strings or PrehashedData; groups cannot be
+  # nested.
+  class DataGroup
+    attr_reader :members
+
+    def initialize(members)
+      raise ArgumentError, "members must be an Array, got #{members.class}" unless members.is_a?(Array)
+      raise ArgumentError, "a data group needs at least one member" if members.empty?
+
+      members.each_with_index do |m, i|
+        raise ArgumentError, "data groups cannot be nested (member #{i})" if m.is_a?(DataGroup)
+
+        DataSource.check!(m, "member #{i}")
+      end
+      @members = members.dup.freeze
+      freeze
+    end
+
+    def size
+      @members.size
+    end
+  end
+
+  # Internal: turns the values accepted as data (String, PrehashedData,
+  # DataGroup) into objects that compute hash values, caching them per
+  # algorithm.
+  module DataSource
+    module_function
+
+    def check!(value, name = "data")
+      return if value.is_a?(String) || value.is_a?(PrehashedData)
+
+      raise ArgumentError,
+            "#{name} must be a String, an EvidenceRecord::PrehashedData " \
+            "or an EvidenceRecord::DataGroup, got #{value.class}"
+    end
+
+    def wrap(value)
+      case value
+      when Single, Group then value
+      when DataGroup then Group.new(value.members.map { Single.new(_1) })
+      else
+        check!(value)
+        Single.new(value)
+      end
+    end
+
+    # One data object.
+    class Single
+      def initialize(value)
+        @value = value
+        @cache = {}
+      end
+
+      def group?
+        false
+      end
+
+      # The hash of the data object, as a BINARY String.
+      def digest(algorithm)
+        algorithm = DigestAlgorithm.fetch(algorithm)
+        @cache[algorithm] ||= compute(algorithm)
+      end
+
+      # [hash]; the list that becomes the first partial hash tree.
+      def member_digests(algorithm)
+        [digest(algorithm)]
+      end
+
+      private
+
+      def compute(algorithm)
+        case @value
+        when PrehashedData
+          d = @value[algorithm] or
+            raise ArgumentError, "PrehashedData has no #{algorithm} hash, which is required here"
+          d.to_binary
+        else
+          algorithm.digest(@value).freeze
+        end
+      end
+    end
+
+    # A data object group.
+    class Group
+      attr_reader :members
+
+      def initialize(members)
+        @members = members
+      end
+
+      def group?
+        true
+      end
+
+      def member_digests(algorithm)
+        @members.map { _1.digest(algorithm) }
+      end
+    end
+  end
+end