NAME

HTTP::Message::Signature - Verify HTTP Message Signatures (RFC 9421)

VERSION

version v0.0.2

SYNOPSIS

use HTTP::Message::Signature;

try {

    my $sig = HTTP::Message::Signature->new(
        message     => $request,         # HTTP::Request, Plack::Request or PSGI env hash
        require_tag => 'web-bot-auth',
    );

    $sig->is_expired and die "expired signature";

    $sig->verify or die "bad signature";

}
catch ($e) {

    ...

}

STATUS

This module is an experimental prototype.

The user interface is subject to change.

See also "KNOWN ISSUES" and "SECURITY CONSIDERATIONS".

DESCRIPTION

This module supports verifying HTTP Message Signatures (RFC 9421), notably those used for Web Bot Authentication.

ATTRIBUTES

message

This is an HTTP::Message or a Plack::Request.

Note that you can pass a PSGI environment hash reference to the constructor.

This is required.

is_request

True if "message" is a request.

is_response

True if "message" is a response.

user_agent

The user agent used for requesting keys.

This is a HTTP::Tiny object.

signature_agent

This is the signature agent from the Signature-Agent header.

This should be a base URL but the actual value may be quoted. Some agents may send a full URL.

signature_agent_uri

This is the URI for the "signature_agent" JSON Web Key (JWK).

signature_input

This is the Signature-Input header, parsed into a Hash::MultiValue object.

signature_labels

This is an array of the labels from the "signature_input".

signature_header

This is the Signature header, parsed into a Hash::MultiValue object, where the keys are labels.

public_keys_json

This is the raw JSON of the "public_keys".

The keys will be fetched from "signature_agent_uri".

Cached keys should be saved here instead of "public_keys".

public_keys

This is the parsed "public_keys_json".

require_tag

When set, the "verify" method requires the tag in the "signature_input" header to be that value.

Set this to web-bot-auth to verify bots.

has_require_tag

A predicate for "require_tag".

METHODS

is_expired

Returns true if the signature is expired.

This can be checked before verification to avoid the work of checking a signature.

verify

$sig->verify( $label ) or die "Signature ${label} is not verified";

Returns true if the signature was verified.

The $label defaults to the first "signature_labels" if omitted.

KNOWN ISSUES

Signature Algorithms

The current version only supports the "Ed25519" algorithm.

Missing Signature-Agent headers

The current version does not support caching keys.

Multiple Signatures

The current version of this module does not support multiple signatures.

SECURITY CONSIDERATIONS

Structured Fields

The current version of this module uses regular expressions for splitting dictionary and parameter fields, rather than using an HTTP Structured Field (RFC 9651) parser.

Trusted Agents

Your application should use an allowed list of trusted agents, rather than attempt to verify arbitrary requests.

SEE ALSO

Web Bot Auth

HTTP Message Signatures for automated traffic

RFC 7517: JSON Web Key (JWK)

RFC 9421: HTTP Message Signatures

RFC 9651: Structured Field Values for HTTP

SOURCE

The development version is on github at https://github.com/robrwo/perl-HTTP-Message-Signature and may be cloned from https://github.com/robrwo/perl-HTTP-Message-Signature.git

SUPPORT

Only the latest release of this module will be supported.

This module requires Perl v5.24 or later. Future releases may only support Perl versions released in the last ten (10) years.

Reporting Bugs and Submitting Feature Requests

Please report any bugs or feature requests on the bugtracker website https://github.com/robrwo/perl-HTTP-Message-Signature/issues

When submitting a bug or request, please include a test-file or a patch to an existing test-file that illustrates the bug or desired feature.

If the bug you are reporting has security implications which make it inappropriate to send to a public issue tracker, then see SECURITY.md for instructions how to report security vulnerabilities.

AUTHOR

Robert Rothenberg <perl@rhizomnic.com>

COPYRIGHT AND LICENSE

This software is Copyright (c) 2026 by Robert Rothenberg.

This is free software, licensed under:

The Apache License, Version 2.0, January 2004