Module: Linzer

Extended by:
Helper, Key::Helper
Defined in:
lib/linzer.rb,
lib/linzer/jws.rb,
lib/linzer/key.rb,
lib/linzer/rsa.rb,
lib/linzer/hmac.rb,
lib/linzer/http.rb,
lib/linzer/ecdsa.rb,
lib/linzer/common.rb,
lib/linzer/helper.rb,
lib/linzer/ml_dsa.rb,
lib/linzer/signer.rb,
lib/linzer/ed25519.rb,
lib/linzer/message.rb,
lib/linzer/options.rb,
lib/linzer/rsa_pss.rb,
lib/linzer/version.rb,
lib/linzer/verifier.rb,
lib/linzer/signature.rb,
lib/linzer/key/helper.rb,
lib/linzer/faraday/utils.rb,
lib/linzer/message/field.rb,
lib/linzer/http/bootstrap.rb,
lib/linzer/message/adapter.rb,
lib/linzer/message/overlay.rb,
lib/linzer/message/wrapper.rb,
lib/linzer/signature/context.rb,
lib/linzer/signature/profile.rb,
lib/linzer/message/field/parser.rb,
lib/linzer/http/structured_field.rb,
lib/linzer/http/signature_feature.rb,
lib/linzer/signature/profile/base.rb,
lib/linzer/message/adapter/abstract.rb,
lib/linzer/signature/profile/example.rb,
lib/linzer/message/adapter/rack/common.rb,
lib/linzer/message/adapter/rack/request.rb,
lib/linzer/message/adapter/rack/response.rb,
lib/linzer/signature/profile/web_bot_auth.rb,
lib/linzer/message/adapter/faraday/request.rb,
lib/linzer/message/adapter/generic/request.rb,
lib/linzer/message/adapter/http_gem/common.rb,
lib/linzer/message/adapter/faraday/response.rb,
lib/linzer/message/adapter/generic/response.rb,
lib/linzer/message/adapter/http_gem/request.rb,
lib/linzer/message/adapter/net_http/request.rb,
lib/linzer/message/adapter/http_gem/response.rb,
lib/linzer/message/adapter/net_http/response.rb

Overview

Linzer is a Ruby library for HTTP Message Signatures as defined in RFC 9421.

It provides functionality to sign and verify HTTP messages using various cryptographic algorithms including RSA-PSS, HMAC-SHA256, ECDSA, Ed25519, and ML-DSA.

Examples:

Signing a request with Ed25519

key = Linzer.generate_ed25519_key("my-key-id")
request = Net::HTTP::Post.new(URI("https://example.com/api"))
request["date"] = Time.now.httpdate

Linzer.sign!(request,
  key: key,
  components: %w[@method @request-target date]
)

Verifying a signed request

pubkey = Linzer.new_ed25519_public_key(public_key_pem, "my-key-id")
Linzer.verify!(request, key: pubkey)

See Also:

Author:

  • Miguel Landaeta

Defined Under Namespace

Modules: Common, ECDSA, Ed25519, Faraday, HMAC, HTTP, Helper, JWS, MLDSA, Options, RSA, RSAPSS, Signer, Verifier Classes: Error, Key, Message, Signature, SigningError, VerifyError

Constant Summary collapse

FieldId =

Alias for Message::Field::Identifier for convenient access. Used for serializing and deserializing component identifiers.

Message::Field::Identifier
VERSION =

Current version of the Linzer gem.

Returns:

  • (String) 
"0.8.1.beta1"

Class Method Summary collapse

Methods included from Helper

sign!, verify!

Methods included from Key::Helper

generate_ecdsa_p256_sha256_key, generate_ecdsa_p384_sha384_key, generate_ed25519_key, generate_hmac_sha256_key, generate_jws_key, generate_ml_dsa_44_key, generate_ml_dsa_65_key, generate_ml_dsa_87_key, generate_rsa_pss_sha512_key, generate_rsa_v1_5_sha256_key, jwk_import, new_ecdsa_p256_sha256_key, new_ecdsa_p384_sha384_key, new_ed25519_key, new_ed25519_public_key, new_hmac_sha256_key, new_ml_dsa_44_key, new_ml_dsa_65_key, new_ml_dsa_87_key, new_rsa_pss_sha512_key, new_rsa_pss_sha512_public_key, new_rsa_v1_5_sha256_key, new_rsa_v1_5_sha256_public_key

Class Method Details

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

Signs an HTTP message.

Examples:

Sign with default options

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

Sign with custom parameters

signature = Linzer.sign(key, message, %w[@method @path],
  keyid: "my-key",
  created: Time.now.to_i,
  nonce: SecureRandom.hex(16)
)

Parameters:

  • key (Linzer::Key) —

    The private key to sign with

  • message (Linzer::Message) —

    The HTTP message to sign

  • components (Array<String>) —

    The message components to include in the signature (e.g., ["@method", "@path", "content-type"])

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

    Additional signature parameters

Options Hash (options):

  • :created (Integer) —

    Unix timestamp for signature creation (defaults to current time)

  • :keyid (String) —

    Key identifier to include in signature

  • :label (String) —

    Signature label (defaults to "sig1")

  • :nonce (String) —

    A unique nonce value

  • :tag (String) —

    Application-specific tag

  • :expires (Integer) —

    Unix timestamp for signature expiration

Returns:

Raises:

See Also:



139
140
141
 
# File 'lib/linzer.rb', line 139

def sign(key, message, components, options = {})
  Linzer::Signer.sign(key, message, components, options)
end

.signature_base(message, components, parameters) ⇒ String

Computes the signature base string for an HTTP message.

The signature base is the canonical string representation that gets signed. This method is primarily useful for debugging or implementing custom signing logic.

Parameters:

  • message (Linzer::Message) —

    The HTTP message

  • components (Array<String>) —

    Serialized component identifiers

  • parameters (Hash) —

    Signature parameters

Returns:

  • (String) —

    The signature base string

See Also:



156
157
158
 
# File 'lib/linzer.rb', line 156

def signature_base(message, components, parameters)
  Linzer::Common.signature_base(message, components, parameters)
end

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

Verifies an HTTP message signature.

Examples:

Basic verification

Linzer.verify(pubkey, message, signature)

Verification with age limit (reject signatures older than 5 minutes)

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

Parameters:

  • pubkey (Linzer::Key) —

    The public key to verify the signature with

  • message (Linzer::Message) —

    The HTTP message to verify

  • signature (Linzer::Signature) —

    The signature to verify

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

    Maximum age of signature in seconds. If provided, signatures with a created timestamp older than this value will be rejected to mitigate replay attacks.

Returns:

  • (true) —

    Returns true if verification succeeds

Raises:

  • (VerifyError) —

    If verification fails for any reason

See Also:



106
107
108
 
# File 'lib/linzer.rb', line 106

def verify(pubkey, message, signature, no_older_than: nil)
  Linzer::Verifier.verify(pubkey, message, signature, no_older_than: no_older_than)
end