NAME

Mail::DKIM2::Signature - One DKIM2-Signature header, parsed or under construction

SYNOPSIS

use Mail::DKIM2::Signature;

# Parse a header read from a message
my $sig = Mail::DKIM2::Signature->parse($header_value);
say $sig->sequence;      # i=
say $sig->domain;        # d=
say $sig->mail_from;     # mf=, decoded: "<sender@example.com>"
say @{ $sig->rcpt_to };  # rt=, decoded
say $sig->selector(0);   # first s= item's selector

# Build one (the Signer does this for you)
my $sig = Mail::DKIM2::Signature->new(
    Sequence   => 1,
    Version    => 1,
    Timestamp  => time,
    Domain     => 'example.com',
    MailFrom   => '<sender@example.com>',
    RcptTo     => ['<rcpt@example.net>'],
    Signatures => [['sel1', 'rsa-sha256', '']],
);

DESCRIPTION

A DKIM2-Signature header as defined in spec-06 section 8, as a Mail::DKIM2::TagValueList. The tags:

i=

Sequence number: this signature's position in the chain, from 1.

m=

The Message-Instance m= this signature covers; absent when the message has no Message-Instance.

t=

Unix timestamp of signing.

d=

Signing domain.

mf=, rt=

The envelope of this hop: MAIL FROM, and a comma-separated list of RCPT TO, each a base64-encoded RFC 5321 path with angle brackets (section 7.5 and 7.6). <> is the null sender.

nd=

For an imaginary forwarding hop (section 9.3), the d= of the hop that signs next. Replaces mf= and rt=.

n=

A nonce of at most 64 characters.

f=

Comma-separated flags: donotmodify, donotexplode, feedback, feedhere.

s=

The signature items, selector:algorithm:base64signature, comma-separated. A selector may appear once; an algorithm at most twice.

This module implements draft-ietf-dkim-dkim2-spec-06; see "STATUS" in Mail::DKIM2 for what that means for the wire format and the API, and "CONVENTIONS" in Mail::DKIM2 for the option, input and error conventions every module here follows.

CONSTRUCTORS

new(%args)

Builds a signature from Sequence, Version, Timestamp, Domain, MailFrom, RcptTo (arrayref), NextDomain, Nonce, Flags (arrayref) and Signatures, an arrayref of [selector, algorithm, value] arrayrefs. Each sets the tag described above when given; NextDomain suppresses MailFrom and RcptTo.

parse($header_value)

Parses a header value, with or without the leading DKIM2-Signature:. Tag names keep their case and order so the header can be re-serialised byte for byte; lookups are case-insensitive.

TAG ACCESSORS

Each gets the tag, or sets it when given an argument and returns the new value. Envelope paths are bracketed on the way in and decoded on the way out.

sequence([$i]), version([$m]), timestamp([$t]), domain([$d]), next_domain([$nd])

The plain tags.

nonce([$n])

Croaks on a value over 64 characters.

mail_from([$path])

The decoded mf=, e.g. "<sender@example.com>", or undef.

rcpt_to([$path_or_arrayref])

An arrayref of decoded rt= paths, or undef. Setting accepts one address or an arrayref and requires at least one.

Setting mail_from or rcpt_to on a signature carrying nd= croaks.

flags([\@flags])

An arrayref of flags, or undef.

SIGNATURE ITEMS

signatures_data()

An arrayref of [selector, algorithm, value] arrayrefs, one per s= item, with folding whitespace stripped.

selector([$index]), algorithm([$index]), signature_value([$index])

The parts of the item at $index (default 0).

sig_count()

The number of items.

check_duplicates()

A list of PERMERROR strings for the section 8.9 rules: a selector used twice, or an algorithm used more than twice. Empty if clean.

SERIALIZATION

as_string()

The complete header line, unfolded.

as_string_without_data()

The header with every s= value emptied, unfolded: the last element of the signing input as the Verifier reconstructs it.

as_folded_string_without_data()

The same, folded at 72 characters: the last element of the signing input as the Signer produces it. Where the folds land is part of what is signed.

as_folded_string()

The complete header folded at 72 characters, ready to insert into the message. Never refold it afterwards.

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.

cpanm Mail::DKIM2

perl -MCPAN -e shell
install Mail::DKIM2