NAME

Mail::DKIM2::Key - Keys, key records, Domain Policy Records and signing algorithms for DKIM2

SYNOPSIS

use Mail::DKIM2::Key qw(load_private_key parse_dkim_pubkey signature_algorithm);

my $key = load_private_key('/etc/dkim2/sel1.pem');
my $pub = parse_dkim_pubkey('v=DKIM1; k=rsa; p=MIIB...');

DESCRIPTION

Private keys as a Signer takes them, the public key records and Domain Policy Records a Verifier reads from the DNS (-09 sections 3.7, 3.8 and 14.5), and the table of signing algorithms both use (sections 3.2, 3.3). Nothing is exported by default; Mail::DKIM2::Common exports these too, as it did before they moved here in 0.31.

See "CONVENTIONS" in Mail::DKIM2 for the conventions every module follows.

FUNCTIONS

load_private_key($pem_file)

A Crypt::PK::RSA or Crypt::PK::Ed25519 from a PEM file, whichever it holds. Dies if the file is neither.

load_private_key_data($data)

The same from key material in memory: PEM, or bare base64 DER as some key stores keep it. Returns undef rather than dying, so a signer of live mail can log and carry on.

parse_dkim_key_record($txt_record)

Validates a whole key record (draft-ietf-dkim-dkim2-dns sections 3.2 and 3.4.1) and returns the public key object: a Crypt::PK::RSA for k=rsa (the default) or a Crypt::PK::Ed25519 for k=ed25519, the raw 32 octets of RFC 8463 (-09 section 14.5). Otherwise returns (undef, $why), where $why completes "public key <selector> ...":

has a syntax error

Not a tag-list; a tag given twice; v= present but not the first tag or not exactly DKIM1; no p=; p= not base64.

is malformed

p= is base64 but not a usable key of its type (-09 section 14.5): an Ed25519 key that is not exactly 32 octets (DER included), or one that does not load.

too short

An RSA key of fewer than 1024 bits: -09 sections 3.2 and 14.6 leave it to the Verifier, and this one refuses it (new in 0.29; it was is malformed).

has been revoked

An empty p=.

has an unsupported key type

A k= other than rsa or ed25519.

Unknown tags and the retired h=, n=, s= and t= are ignored. Tag names are case sensitive, as in DKIM1.

query_domain_policy($resolver, $domain)

The TXT records at _domainkey.<domain> through $resolver->query, each RR's strings joined, as an arrayref: empty for NXDOMAIN, NOERROR or NODATA; dies with TEMPERROR: otherwise. New in 0.29.

policy_from_source($domain, $callback, $resolver_sub, @callback_args)

The Domain Policy Record state of $domain (open, strict, multiple or temperror, with the reason second for temperror), from $callback->($domain, @callback_args) when given, else "query_domain_policy" through $resolver_sub->(). New in 0.29.

key_records(@txt)

The TXT records at a selector that are candidate key records (-09 section 3.7, draft-ietf-dkim-dkim2-dns-03 section 3): all but those that begin with a v= tag whose value is not DKIM1. More than one left is the caller's has multiple records. New in 0.29.

domain_policy(@txt)

The Domain Policy Record held by the TXT records at _domainkey.<domain> (-09 section 3.8, draft-ietf-dkim-dkim2-dns-03 section 6): strict when subdomains are not authorized to make that domain's From Authentic, open when they are (no record, no f=, or no strict flag; unknown flags are ignored), multiple for more than one record. Only records whose first tag is v=DKIM1 count; one that does but does not parse is strict (it fails closed). New in 0.29.

parse_dkim_pubkey($txt_record)

The key object from parse_dkim_key_record, or undef for a record that gives no usable key.

signature_algorithm($name)

The signing algorithm named $name in an s= item (-09 sections 3.2, 3.3), as a hashref, or undef for one this library does not implement: name; key_class, the class a key for it must be; sign, called as ->($key, $signing_input) and returning the raw signature; verify, called as ->($key, $signing_input, $signature); and for rsa-sha256, min_bits (1024). The Mail::DKIM2::Signer and the Mail::DKIM2::Verifier both sign and verify through it. Names are case-sensitive. New in 0.31.

signature_algorithm_for_key($key)

The name of the algorithm a key object signs with (rsa-sha256 for a Crypt::PK::RSA, ed25519-sha256 for a Crypt::PK::Ed25519), or undef. New in 0.31.

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.