Class: WSDL::Security::Verifier::TimestampValidator

Inherits:
Base
  • Object
show all
Defined in:
lib/wsdl/security/verifier/timestamp_validator.rb

Overview

Validates timestamp freshness in SOAP responses.

This validator checks that response timestamps are within acceptable time bounds to prevent replay attacks and detect stale messages.

Per WS-Security specification (Section 10), timestamps are optional. When present, this validator checks:

  • Created is not too far in the future (clock skew protection)
  • Expires is not in the past (freshness check)

Clock skew tolerance is applied to both checks to account for unsynchronized clocks between sender and receiver.

Examples:

Basic validation

validator = TimestampValidator.new(document)
if validator.valid?
  puts "Timestamp is fresh"
else
  puts "Errors: #{validator.errors}"
end

With custom clock skew

validator = TimestampValidator.new(document, clock_skew: 600)
validator.valid?

See Also:

Constant Summary collapse

DEFAULT_CLOCK_SKEW =

Default clock skew tolerance in seconds (5 minutes).

This value aligns with WS-I BSP guidance and the default TTL used for outgoing timestamps.

300
XSD_DATETIME_TIMEZONE_SUFFIX =

This constant is part of a private API. You should avoid using this constant if possible, as it may be removed or be changed in the future.

Matches xsd:dateTime timezone suffixes (Z or +/-HH:MM).

/(Z|[+-]\d{2}:\d{2})\z/

Constants inherited from Base

Base::SOAPNS, Base::SOAP_NAMESPACES, Base::SecurityNS, Base::SignatureNS, Base::VALID_ID_PATTERN

Instance Attribute Summary collapse

Attributes inherited from Base

#errors

Instance Method Summary collapse

Constructor Details

#initialize(document, clock_skew: DEFAULT_CLOCK_SKEW, reference_time: nil) ⇒ TimestampValidator

Creates a new TimestampValidator instance.

Parameters:

  • document (Nokogiri::XML::Document) —

    the SOAP response document

  • clock_skew (Integer) (defaults to: DEFAULT_CLOCK_SKEW) —

    acceptable clock skew in seconds (default: 300)

  • reference_time (Time, nil) (defaults to: nil) —

    the time to validate against (defaults to current UTC time; useful for testing)



65
66
67
68
69
70
71
72
73
74
 
# File 'lib/wsdl/security/verifier/timestamp_validator.rb', line 65

def initialize(document, clock_skew: DEFAULT_CLOCK_SKEW, reference_time: nil)
  super()
  @document = document
  @clock_skew = clock_skew
  @reference_time = reference_time
  @created_at = nil
  @expires_at = nil
  @parsed = false
  @parsed_values_valid = true
end

Instance Attribute Details

#created_at ⇒ Time? (readonly)

Returns the parsed Created time from the timestamp.

Returns:

  • (Time, nil) —

    the UTC creation time, or nil if not present



51
52
53
 
# File 'lib/wsdl/security/verifier/timestamp_validator.rb', line 51

def created_at
  @created_at
end

#expires_at ⇒ Time? (readonly)

Returns the parsed Expires time from the timestamp.

Returns:

  • (Time, nil) —

    the UTC expiration time, or nil if not present



56
57
58
 
# File 'lib/wsdl/security/verifier/timestamp_validator.rb', line 56

def expires_at
  @expires_at
end

Instance Method Details

#timestamp ⇒ Hash?

Returns the timestamp as a hash.

Returns:

  • (Hash, nil) —

    hash with :created_at and :expires_at keys, or nil if no timestamp present



123
124
125
126
127
128
 
# File 'lib/wsdl/security/verifier/timestamp_validator.rb', line 123

def timestamp
  parse_timestamp unless @parsed
  return nil unless timestamp_present?

  { created_at: @created_at, expires_at: @expires_at }
end

#timestamp_present? ⇒ Boolean

Returns whether a timestamp element is present in the document.

Returns:

  • (Boolean) —

    true if wsu:Timestamp exists in the Security header



113
114
115
116
 
# File 'lib/wsdl/security/verifier/timestamp_validator.rb', line 113

def timestamp_present?
  parse_timestamp unless @parsed
  !timestamp_node.nil?
end

#valid? ⇒ Boolean

Validates the timestamp freshness.

Each call re-evaluates freshness against the current time, ensuring that a Verifier held across a time boundary correctly detects expiration. Parse errors (malformed values detected during the one-time parse) are preserved across calls; only validation errors (freshness checks) are cleared and re-run.

Returns true if:

  • No timestamp is present (timestamps are optional per spec)
  • Timestamp is present and within acceptable time bounds

Returns false if:

  • Created time is too far in the future (beyond clock skew)
  • Expires time is in the past (accounting for clock skew)
  • Timestamp contains malformed time values

Returns:

  • (Boolean) —

    true if valid or no timestamp present



95
96
97
98
99
100
101
102
103
104
105
106
107
 
# File 'lib/wsdl/security/verifier/timestamp_validator.rb', line 95

def valid?
  parse_timestamp unless @parsed

  return true unless timestamp_present?
  return false unless @parsed_values_valid

  # Clear validation errors from previous calls to prevent
  # accumulation. Parse errors are guarded above by
  # @parsed_values_valid which returns false before this point.
  @errors.clear

  validate_created && validate_expires
end