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/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/message/field.rb,
lib/linzer/http/bootstrap.rb,
lib/linzer/message/adapter.rb,
lib/linzer/message/wrapper.rb,
lib/linzer/message/field/parser.rb,
lib/linzer/http/signature_feature.rb,
lib/linzer/message/adapter/abstract.rb,
lib/linzer/message/adapter/rack/common.rb,
lib/linzer/message/adapter/rack/request.rb,
lib/linzer/message/adapter/rack/response.rb,
lib/linzer/message/adapter/generic/request.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, and Ed25519.

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, HMAC, HTTP, Helper, JWS, 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.7.8"

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_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_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:



135
136
137
 
# File 'lib/linzer.rb', line 135

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:



152
153
154
 
# File 'lib/linzer.rb', line 152

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:



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

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