Module: Linzer::Signer

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

Overview

Handles HTTP message signing according to RFC 9421.

This module provides the core signing functionality. It creates signatures by computing a signature base from the message components and signing it with the provided key.

Examples:

Direct usage (prefer Linzer.sign for convenience)

message = Linzer::Message.new(request)
components = %w[@method @path content-type]
signature = Linzer::Signer.sign(key, message, components)

See Also:

Constant Summary collapse

DEFAULT_LABEL =

Default label used for signatures when none is specified.

Returns:

  • (String) 
"sig1"

Class Method Summary collapse

Methods included from Common

signature_base, signature_base_line, signature_params_line

Class Method Details

.default_label ⇒ String

Returns the default signature label.

Returns:

  • (String) —

    The default label ("sig1")



101
102
103
 
# File 'lib/linzer/signer.rb', line 101

def default_label
  DEFAULT_LABEL
end

.sign(key, message, components, options = {}) ⇒ Linzer::Signature

Signs an HTTP message.

Creates a signature by:

  1. Serializing the component identifiers
  2. Building the signature base from the message and parameters
  3. Signing the signature base with the key
  4. Returning a Signature object with the result

Examples:

Basic signing

signature = Linzer::Signer.sign(key, message, %w[@method @path])

With all options

signature = Linzer::Signer.sign(key, message, %w[@method @path date],
  created: Time.now.to_i,
  keyid: "my-key-2024",
  label: "request-sig",
  nonce: SecureRandom.hex(16),
  tag: "my-app"
)

Parameters:

  • key (Linzer::Key) —

    The private key to sign with. Must respond to #sign and should contain private key material.

  • message (Linzer::Message) —

    The HTTP message to sign

  • components (Array<String>) —

    Component identifiers to include in the signature. Can be header names (e.g., "content-type") or derived components (e.g., "@method", "@path"). May include parameters (e.g., "content-type";bs for binary-wrapped).

  • options (Hash) (defaults to: {}) —

    Additional signature parameters

Options Hash (options):

  • :created (Integer) —

    Unix timestamp for signature creation. Defaults to the current UTC time.

  • :keyid (String) —

    Key identifier. If not provided, uses the key's key_id if available.

  • :label (String) —

    The signature label (defaults to "sig1"). Multiple signatures on a message must have distinct labels.

  • :nonce (String) —

    A unique nonce value to prevent replay

  • :tag (String) —

    Application-specific tag

  • :expires (Integer) —

    Unix timestamp when signature expires

  • :alg (String) —

    Algorithm identifier (usually inferred from key)

Returns:

Raises:

  • (SigningError) —

    If the message, key, or components are invalid

  • (SigningError) —

    If required components are missing from the message

  • (SigningError) —

    If components are duplicated

  • (SigningError) —

    If @signature-params is included in components



70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
 
# File 'lib/linzer/signer.rb', line 70

def sign(key, message, components, options = {})
  serialized_components, field_ids =
    FieldId.serialize_components_with_field_ids(Array(components))
  validate key, message, serialized_components, field_ids: field_ids

  # Reuse the already-parsed items from field_ids
  parsed_items = field_ids.map(&:item)

  parameters = populate_parameters(key, options)
  signature_base = signature_base(message, serialized_components, parameters,
                                  field_ids: field_ids)

  raw_signature = key.sign(signature_base)
  label = options[:label] || DEFAULT_LABEL

  # Build the signature directly, bypassing the serialize -> parse round-trip
  headers = serialize(raw_signature, serialized_components, parameters, label)

  Linzer::Signature.from_components(
    components:    serialized_components,
    raw_signature: raw_signature,
    label:         label,
    parameters:    parameters,
    parsed_items:  parsed_items,
    headers:       headers
  )
end