Class: Clickwrap::Integrity::Timestamp

Inherits:
Object
  • Object
show all
Defined in:
lib/clickwrap/integrity/timestamp.rb

Overview

The adapter contract for a timestamp provider, plus a reference base implementation that issues no tokens and says so. Configuration defaults to nil.

config.timestamp_receipts_with = MyRfc3161TimestampProvider.new

WHAT THIS SEAM IS FOR. Clickwrap records recorded_at_by_server, and calls it exactly that: the application server's own clock, which the application controls. An RFC 3161 time-stamp authority (https://www.rfc-editor.org/info/rfc3161/) or a qualified trust service supplies something different — a token from a third party over a digest you gave it, whose value depends entirely on that party, its practice statement, its certificate status, and what a reader is willing to accept about it.

WHAT SUCH A TOKEN CLAIMS. Exactly what that provider supplies and nothing more. Clickwrap stores the token and the validation status the adapter reports, and preserves both verbatim; it never upgrades a provider receipt into a guarantee the provider did not make, never treats a token as identity, never treats it as a signature by a person, and never restates it in stronger words than the provider used. If the provider's own status is "unknown" or "expired", that is what travels into the receipt. eIDAS gives distinct legal effect to qualified signatures and seals (https://eur-lex.europa.eu/eli/reg/2014/910/2024-05-20/eng); whether a given provider's output has that effect is a question about that provider, not about this gem.

WHAT THIS FILE DELIBERATELY IS NOT. It is not an RFC 3161 client. Clickwrap ships no ASN.1 encoder, no HTTP client, and no certificate-chain validation, and it adds no dependency that would. Timestamping is an optional integration. A host that needs it supplies an adapter that speaks to its own chosen authority; assigning this base class is useful only when an explicit unavailable result is wanted.

WRITING ONE. Implement #timestamp(digest) and #verify(token, digest), and report honestly from #capabilities. Configuration#timestamp_receipts_with= checks that the object responds to #timestamp.

Defined Under Namespace

Classes: Token, Verification

Instance Method Summary collapse

Instance Method Details

#available? ⇒ Boolean

Returns:

  • (Boolean) 


136
 
# File 'lib/clickwrap/integrity/timestamp.rb', line 136

def available? = false

#capabilities ⇒ Object

What this adapter supplies, in the provider's own terms. Read by the receipt's integrity fragment and by clickwrap:doctor, which report the tier honestly rather than inferring a stronger one from the mere presence of an adapter.



122
123
124
125
126
127
128
129
130
131
132
133
134
 
# File 'lib/clickwrap/integrity/timestamp.rb', line 122

def capabilities
  {
    "name" => provider_name,
    "available" => available?,
    "protocol" => nil,
    "supplies" => "Nothing. This is the default placeholder that reports the absence of a " \
                  "timestamp provider for explicit adapter-contract tests. Configuration " \
                  "normally remains nil.",
    "note" => "A configured provider supplies exactly the assurance and validation status " \
              "that provider supplies. Clickwrap preserves it and never restates it more " \
              "strongly."
  }
end

#provider_name ⇒ Object 



138
 
# File 'lib/clickwrap/integrity/timestamp.rb', line 138

def provider_name = "no_timestamp_provider"

#timestamp(digest) ⇒ Object

Asks the provider to timestamp one digest. Never the raw receipt, never the personal data inside it: a digest is what a timestamp authority needs and the only thing it should ever be given.

Called outside the capture transaction. A provider cannot join a database transaction, and a capture must never fail because a third party was slow.



96
97
98
99
100
101
102
103
104
 
# File 'lib/clickwrap/integrity/timestamp.rb', line 96

def timestamp(digest)
  Token.new(
    issued: false,
    digest: digest,
    provider_name: provider_name,
    detail: "This timestamp adapter issues no token, so the only " \
            "recorded time remains the application server's own."
  )
end

#to_s ⇒ Object 



140
 
# File 'lib/clickwrap/integrity/timestamp.rb', line 140

def to_s = "#{self.class.name} (#{provider_name})"

#verify(_token, _digest) ⇒ Object

Checks a stored token against the digest it was issued over, and reports what the provider said. A token nobody re-checks is a stored blob.



108
109
110
111
112
113
114
115
116
 
# File 'lib/clickwrap/integrity/timestamp.rb', line 108

def verify(_token, _digest)
  Verification.new(
    checked: false,
    verified: false,
    provider_name: provider_name,
    detail: "This timestamp adapter issues no token, so there is nothing to check in this " \
            "token."
  )
end