.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Mail::DKIM::AuthorDomainPolicy 3pm" .TH Mail::DKIM::AuthorDomainPolicy 3pm "2020-09-11" "perl v5.30.3" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Mail::DKIM::AuthorDomainPolicy \- represents an Author Domain Signing Practices (ADSP) record .SH "VERSION" .IX Header "VERSION" version 1.20200907 .SH "DESCRIPTION" .IX Header "DESCRIPTION" The Author Domain Signing Policies (\s-1ADSP\s0) record can be published by any domain to help a receiver know what to do when it encounters an unsigned message claiming to originate from that domain. .PP The record is published as a \s-1DNS TXT\s0 record at _adsp._domainkey.DOMAIN where \s-1DOMAIN\s0 is the domain of the message's \*(L"From\*(R" address. .PP More details about this record can be found by reading the specification itself at . .SH "CONSTRUCTORS" .IX Header "CONSTRUCTORS" .SS "\fBfetch()\fP" .IX Subsection "fetch()" Lookup an \s-1ADSP\s0 record in \s-1DNS.\s0 .PP .Vb 4 \& my $policy = Mail::DKIM::AuthorDomainPolicy\->fetch( \& Protocol => \*(Aqdns\*(Aq, \& Author => \*(Aqjsmith@example.org\*(Aq, \& ); .Ve .PP If the \s-1ADSP\s0 record is found and appears to be valid, an object containing that record's information will be constructed and returned. If the \s-1ADSP\s0 record is blank or simply does not exist, an object representing the default policy will be returned instead. (See also \*(L"\fBis_implied_default_policy()\fR\*(R".) If a \s-1DNS\s0 error occurs (e.g. \s-1SERVFAIL\s0 or time-out), this method will \*(L"die\*(R". .SS "\fBnew()\fP" .IX Subsection "new()" Construct a default policy object. .PP .Vb 1 \& my $policy = Mail::DKIM::AuthorDomainPolicy\->new; .Ve .SS "\fBparse()\fP" .IX Subsection "parse()" Construct an \s-1ADSP\s0 record from a string. .PP .Vb 4 \& my $policy = Mail::DKIM::AuthorDomainPolicy\->parse( \& String => \*(Aqdkim=all\*(Aq, \& Domain => \*(Aqaaa.example\*(Aq, \& ); .Ve .SH "METHODS" .IX Header "METHODS" .SS "\fBapply()\fP" .IX Subsection "apply()" Apply the policy to the results of a \s-1DKIM\s0 verifier. .PP .Vb 1 \& my $result = $policy\->apply($dkim_verifier); .Ve .PP The caller must provide an instance of Mail::DKIM::Verifier, one which has already been fed the message being verified. .PP Possible results are: .IP "accept" 4 .IX Item "accept" The message is approved by the sender signing policy. .IP "reject" 4 .IX Item "reject" The message is rejected by the sender signing policy. It can be considered very suspicious. .IP "neutral" 4 .IX Item "neutral" The message is neither approved nor rejected by the sender signing policy. It can be considered somewhat suspicious. .PP Note: in the future, these values may become: none \- no \s-1ADSP\s0 record is published pass \- a passing signature is present fail \- \s-1ADSP\s0 record is \*(L"all\*(R" and no passing signature is found discard \- \s-1ADSP\s0 record is \*(L"discardable\*(R" and no passing signature is found nxdomain \- the \s-1DNS\s0 domain does not exist temperror \- transient error occurred permerror \- non-transient error occurred .SS "\fBis_implied_default_policy()\fP" .IX Subsection "is_implied_default_policy()" Tells whether this policy implied. .PP .Vb 1 \& my $is_implied = $policy\->is_implied_default_policy; .Ve .PP If you fetch the policy for a particular domain, but that domain does not have a policy published, then the \*(L"default policy\*(R" is in effect. Use this method to detect when that happens. .SS "\fBlocation()\fP" .IX Subsection "location()" Tells where the policy was fetched from. .PP If the policy is domain-wide, this will be domain where the policy was published. .PP If the policy is user-specific, \s-1TBD.\s0 .PP If nothing is published for the domain, and the default policy was returned instead, the location will be \f(CW\*(C`undef\*(C'\fR. .SS "\fBpolicy()\fP" .IX Subsection "policy()" Get or set the outbound signing policy (dkim=) tag. .PP .Vb 1 \& my $sp = $policy\->policy; .Ve .PP Outbound signing policy for the entity. Possible values are: .ie n .IP """unknown""" 4 .el .IP "\f(CWunknown\fR" 4 .IX Item "unknown" The default. The entity may sign some or all email. .ie n .IP """all""" 4 .el .IP "\f(CWall\fR" 4 .IX Item "all" All mail from the domain is expected to be signed, using a valid Author signature, but the author does not suggest discarding mail without a valid signature. .ie n .IP """discardable""" 4 .el .IP "\f(CWdiscardable\fR" 4 .IX Item "discardable" All mail from the domain is expected to be signed, using a valid Author signature, and the author is so confident that non-signed mail claiming to be from this domain can be automatically discarded by the recipient's mail server. .ie n .IP """NXDOMAIN""" 4 .el .IP "\f(CW``NXDOMAIN''\fR" 4 .IX Item """NXDOMAIN""" The domain is out of scope, i.e., the domain does not exist in the \&\s-1DNS.\s0 .SS "\fBsignall()\fP" .IX Subsection "signall()" True if policy is \*(L"all\*(R". .SS "\fBsignall_discardable()\fP" .IX Subsection "signall_discardable()" True if policy is \*(L"strict\*(R". .SH "BUGS" .IX Header "BUGS" .IP "\(bu" 4 Section 4.3 of the specification says to perform a query on the domain itself just to see if it exists. This class is not currently doing that, i.e. it might report \s-1NXDOMAIN\s0 because _adsp._domainkey.example.org is nonexistent, but it should not be treated the same as example.org being nonexistent. .SH "AUTHORS" .IX Header "AUTHORS" .IP "\(bu" 4 Jason Long .IP "\(bu" 4 Marc Bradshaw .IP "\(bu" 4 Bron Gondwana (\s-1ARC\s0) .SH "THANKS" .IX Header "THANKS" Work on ensuring that this module passes the \s-1ARC\s0 test suite was generously sponsored by Valimail (https://www.valimail.com/) .SH "COPYRIGHT AND LICENSE" .IX Header "COPYRIGHT AND LICENSE" .IP "\(bu" 4 Copyright (C) 2013 by Messiah College .IP "\(bu" 4 Copyright (C) 2010 by Jason Long .IP "\(bu" 4 Copyright (C) 2017 by Standcore \s-1LLC\s0 .IP "\(bu" 4 Copyright (C) 2020 by FastMail Pty Ltd .PP This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.6 or, at your option, any later version of Perl 5 you may have available.