NAME
Mail::DKIM2::Canon - Header canonicalization and the signing input for DKIM2
SYNOPSIS
use Mail::DKIM2::Canon qw(dkim2_canonicalize_header should_skip build_signing_input);
my $line = dkim2_canonicalize_header("Subject: Hello\r\n\tworld\r\n"); # "subject:Hello world\r\n"
DESCRIPTION
The octets the spec defines: which header fields are hashed (-09 section 4), how a field is canonicalized for the header hash (section 6.2) and for the signing input (section 12.8), and the signing input itself. Of interest to anyone checking this implementation against another. Nothing is exported by default; Mail::DKIM2::Common exports all of these too, as it did before they moved here in 0.31.
See "CONVENTIONS" in Mail::DKIM2 for the conventions every module follows.
FUNCTIONS
should_skip($header_name, [\@prefixes])
True if the field is excluded from the header hash: the -09 section 4 list (Received, Return-Path, Message-Instance, DKIM2-Signature, DKIM-Signature, Authentication-Results, the ARC fields and others), any X-* or Received-* field, or a field whose name starts with one of the caller's prefixes, case-insensitively. The prefixes are an operator's local policy; pass them as IgnorePrefixes to Mail::DKIM2::Verifier and the Mail::DKIM2::MessageInstance class methods.
check_ignore_prefixes($value)
Croaks unless $value is undef or an array reference; returns it. Every entry point that takes IgnorePrefixes calls this.
dkim2_canonicalize_header($line)
Header-hash canonicalization (-09 section 6.2) of one complete header line including its CRLF: unfold, lowercase the name, collapse whitespace runs to one space, trim whitespace around the colon and at the end. Returns name:value\r\n.
field_name($name)
A header field name as DKIM2 compares it: lowercased, without the white space RFC 5322's obsolete syntax allows between the name and its colon (-09 section 6.2 deletes it), so From : names a From field. New in 0.31.
header_values($msg, $name)
The values of every field of an Email::MIME message whose field_name is $name's, in order: header_raw, but also finding a field written with white space before its colon, which Email::Simple files under a name that includes it. New in 0.31.
dkim2_canonicalize_sig_header($line)
Signing-input canonicalization (-09 section 12.8): as above, but all whitespace in the value is removed rather than collapsed.
build_signing_input(%args)
The octets a DKIM2-Signature signs (-09 section 12.8): the canonicalized Message-Instance fields in ascending m= order, the DKIM2-Signature fields below the one being signed in ascending i= order, and that one with its s= signature values emptied. Arguments, each field given whole (name and value) and folded or not: instances, an arrayref of the Message-Instance fields the signature covers; signatures, an arrayref of the DKIM2-Signature fields below it; signing, the DKIM2-Signature being made or checked, signed or not. The Signer and the Verifier build the input the same way, from the fields themselves. (Before 0.31 the arguments were mi_headers, dk2_headers, signing_i, signature and signing_header.)
AUTHOR
Bron Gondwana <brong@fastmailteam.com>
COPYRIGHT AND LICENSE
Copyright (c) 2025-2026 Fastmail Pty Ltd. This is free software; you can redistribute it and/or modify it under the same terms as Perl itself.