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 exactlyDKIM1; nop=;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 thanrsaored25519.
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.