Module: Linzer::Verifier

Extended by:
Common
Defined in:
lib/linzer/verifier.rb

Overview

Handles HTTP message signature verification according to RFC 9421.

This module verifies that a signature on an HTTP message is valid by:

  1. Reconstructing the signature base from the message and signature parameters
  2. Verifying the signature using the provided public key

Examples:

Direct usage (prefer Linzer.verify for convenience)

signature = Linzer::Signature.build(signature_headers)
message = Linzer::Message.new(request)
Linzer::Verifier.verify(pubkey, message, signature)

See Also:

Class Method Summary collapse

Methods included from Common

signature_base, signature_base_line, signature_params_line

Class Method Details

.verify(key, message, signature, no_older_than: nil) ⇒ true

Verifies an HTTP message signature.

Verification succeeds if:

  • All covered components exist in the message
  • The signature base matches what was signed
  • The cryptographic signature is valid for the public key
  • The signature has not expired (if expires parameter is present)
  • The signature is not older than no_older_than (if specified)

Examples:

Basic verification

Linzer::Verifier.verify(pubkey, message, signature)
# => true (or raises VerifyError)

With age validation (5 minute window)

Linzer::Verifier.verify(pubkey, message, signature, no_older_than: 300)

Parameters:

  • key (Linzer::Key) —

    The public key to verify with. Must respond to #verify and should contain public key material.

  • message (Linzer::Message) —

    The HTTP message to verify

  • signature (Linzer::Signature) —

    The signature to verify. Typically built from the signature and signature-input headers using Signature.build.

  • no_older_than (Integer, nil) (defaults to: nil) —

    Maximum age in seconds. If the signature's created parameter is older than this, verification fails. This helps mitigate replay attacks. See RFC 9421 Section 7.2.2.

Returns:

  • (true) —

    Returns true if verification succeeds

Raises:

  • (VerifyError) —

    If the message is nil

  • (VerifyError) —

    If the key is nil

  • (VerifyError) —

    If the signature is nil or invalid

  • (VerifyError) —

    If required components are missing from the message

  • (VerifyError) —

    If the signature is too old (when no_older_than is set)

  • (VerifyError) —

    If the cryptographic verification fails

See Also:



56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
 
# File 'lib/linzer/verifier.rb', line 56

def verify(key, message, signature, no_older_than: nil)
  validate message, key, signature, no_older_than: no_older_than

  parameters = signature.parameters
  serialized_components = signature.serialized_components

  # Build fresh field_ids for signature_base (validate already
  # consumed its own set, which may have been mutated by adapters).
  field_ids = signature.field_ids

  signature_base = signature_base(message, serialized_components, parameters,
                                  field_ids: field_ids)

  verify_or_fail key, signature.value, signature_base
end