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
HTTP Message Signatures for automated traffic
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