Attached is a reworked section 2 based on Michael's recent suggestions
and discussions with Tony and a couple of others.
I still believe the specification should at least allow a filter to make
and convey local policy judgments on the acceptability of a signature
whether or not it validates. A filter may not choose to use that
capability, but it should be provided.
I also agree with Tony that we don't need to force semantic meaning down
into the syntax level. The IANA registry of ptypes and propspecs toward
the end of the document is sufficient for this purpose.
Comments, please. Otherwise I'm prepared to post this as -13 and try to
move it along.
2. Definition and Format of the Header
This section gives a general overview of the format of the header
field being defined, and then provides more formal specification.
2.1. General Description
The new header field being defined here is called "Authentication-
Results". It is a Structured Header Field as defined in [MAIL] and
thus all of the related definitions in that document apply.
This new header field MUST be added at the top of the message as it
transits MTAs which do authentication checks so some idea of how far
away the checks were done can be inferred. It therefore should be
treated as a Trace Header Field as defined in [MAIL] and thus all of
the related definitions in that document apply.
The value of the header field (after removing [MAIL] comments)
consists of an authentication identifier and then a series of
"method=result" statements indicating which authentication method(s)
were applied and their respective results, and then, for each applied
method, one or more "property=value" statements indicating which
message properties were evaluated to reach that conclusion.
The header field MAY appear more than once in a single message, or
more than one result MAY be represented in a single header field, or
a combination of these MAY be applied.
2.2. Formal Definition
Formally, the header field is specified as follows using [ABNF]:
header = "Authentication-Results:" [CFWS] authserv-id
[CFWS [version]]
*( ";" methodspec
*( CFWS reasonspec )
*( CFWS propspec ) [CFWS] ) CRLF
authserv-id = dot-atom-text
; see below for a description of this element;
; "dot-atom-text" is defined in section 3.2.4 of [MAIL]
version = 1*DIGIT [CFWS]
; indicates which version of this specification is in use;
; this specification is version "1"; the absence of a version
; implies this version of the specification
Kucherawy Expires September 12, 2008 [Page 7]
Internet-Draft Authentication-Results Header March 2008
methodspec = [CFWS] method [CFWS] "=" [CFWS] result
; indicates which authentication method was evaluated
reasonspec = "reason=" dkim-quoted-printable
; a free-form comment on the reason the given result
; was returned; dkim-quoted-printable is defined in
; [DKIM]
propspec = ptype [CFWS] "." [CFWS] property [CFWS] "=" value
; an indication of which properties of the message
; were evaluated by the authentication scheme being
; applied to yield the reported result
method = token [ [CFWS] "/" [CFWS] version ]
; a method indicates which method's result is
; represented by "result", and is one of the methods
; explicitly defined as valid in this document
; or is an extension method as defined below
result = token
; indicates the results of the attempt to authenticate
; the message; see below for details
ptype = "smtp" / "header" / "body" / "policy"
; indicates whether the property being evaluated was
; a parameter to an [SMTP] command, or was a value taken
; from a message header field, or was some property of
; the message body, or some other property evaluated by
; the receiving MTA
property = token
; if "ptype" is "smtp", this indicates which [SMTP]
; command provided the value which was evaluated by the
; authentication scheme being applied; if "ptype" is
; "header", this indicates from which header field the
; value being evaluated was extracted; if "ptype" is
; "body", this indicates the offset into the body at which
; content of interest was detected; if "ptype" is "policy"
; then this indicates the name of the policy which caused
; this header field to be added (see below)
Kucherawy Expires September 12, 2008 [Page 8]
Internet-Draft Authentication-Results Header March 2008
value = [CFWS] ( token / addr-spec ) [CFWS]
; the value extracted from the message property defined
; by the "ptype.property" construction; if the value
; identifies an address, then it is an "addr-spec"
; as defined in section 3.4 of [MAIL]
The "token" is as defined in section 5.1 of [MIME].
The "token" used in a "result" above is further constrained by the
necessity of being enumerated in Section 2.4 or an amendment to it.
See Section 2.3 for a description of the "authserv-id" element.
The list of commands eligible for use with the "smtp" ptype can be
found in [SMTP] and subsequent amendments.
"CFWS" is as defined in section 3.2.3 of [MAIL].
The "propspec" may be omitted if for example the method was unable to
extract any properties to do its evaluation yet has a result to
report.
The "ptype" and "property" values used by each authentication method
should be defined in the specification for that method (or its
amendments).
The "ptype" and "property" are case-insensitive.
A "ptype" value of "policy" indicates a policy decision about the
message not specific to a property of the message that could be
extracted. For example, if a method would normally report a
"ptype.property" of "header.From" and no From: header field was
present, the method can use "policy" to indicate that no conclusion
about the authenticity of the message could be reached.
If the parsed "ptype.property" construction clearly identifies a
mailbox (in particular, smtp.mailfrom, smtp.rcpt, header.from,
header.sender), then the "value" MUST be an "addr-spec". Other
properties (e.g. smtp.helo) may be evaluated, but the property MUST
still be expressed as a "token" for simplified parsing.
2.3. Authentication Identifier Fields
Every Authentication-Results header field has an authentication
identifier field ("authserv-id" above). This is similar in syntax to
a fully-qualified domain name.
The authentication identifier field provides a unique identifier that
Kucherawy Expires September 12, 2008 [Page 9]
Internet-Draft Authentication-Results Header March 2008
refers to the authenticating service within a given mail
administrative domain. The uniqueness of the identifier is
guaranteed by the mail administrative domain that generates it and
must pertain to exactly that one mail administrative domain. This
identifier is intended to be machine-readable and not necessarily
meaningful to users. MUAs may use this identifier to determine
whether or not the data contained in an Authentication-Results header
field can be trusted.
For tracing and debugging purposes, the authentication identifier
SHOULD be the domain name of the MTA performing the authentication
check whose result is being reported.
Examples of valid authentication identifiers are mail.example.org,
engineering.example.net and ms1.newyork.example.com.
2.4. Result Values
Each individual authentication method returns one of a set of
specific result values. The subsections below define these results
for the authentication methods specifically supported by this memo.
New methods not specified in this document intended to be supported
by the header field defined in this memo MUST include a similar
result table either in its defining memo or in a supplementary one.
2.4.1. DKIM and DomainKeys Results
The result values used by [DKIM] and [DOMAINKEYS] are as follows:
none: The message was not signed.
pass: The message was signed, the signature(s) is (were) acceptable
to the verifier, and the signature(s) passed verification tests.
fail: The message was signed and the signature(s) is (were)
acceptable to the verifier, but it (they) failed the verification
test(s).
policy: The message was signed but the signature(s) is (were) not
acceptable to the verifier.
neutral: The message was signed but the signature(s) contained
syntax errors or were not otherwise able to be processed. This
result SHOULD also be used for other failures not covered
elsewhere in this list.
Kucherawy Expires September 12, 2008 [Page 10]
Internet-Draft Authentication-Results Header March 2008
temperror: The message could not be verified due to some error which
is likely transient in nature, such as a temporary inability to
retrieve a public key. A later attempt may produce a final
result.
permerror: The message could not be verified due to some error which
is unrecoverable, such as a required header field being absent. A
later attempt is unlikley to produce a final result.
A signature is "acceptable to the verifier" if it passes local policy
checks (or there are no specific local policy checks). For example,
a verifier might require that the signature(s) on the message be
added by the domain identified in the From: header field of the
message, thus making third-party signatures unacceptable.
2.4.2. DKIM ASP Results
The result values are used by [I-D.DRAFT-IETF-DKIM-SSP] as follows:
none: No DKIM policy author signing practises (ASP) record was
published.
pass: A DKIM ASP policy was published which indicated the mail
should be signed with an author signature, and this message had
such a signature that validated.
unknown: No valid author signature was found on the message and
either the published ASP policy was "unknown", or no policy was
published.
signed: A valid author signature was found on the message and the
published ASP policy was "unknown".
fail: No valid author signature was found on the message and the
published ASP record indicated an "all" policy.
discard: No valid author signature was found on the message and the
published ASP record indicated a "discardable" policy.
nxdomain: Evaluating the ASP for the author's domain indicated that
the author's domain does not exist.
temperror: A DKIM policy could not be retrieved due to some error
which is likely transient in nature, such as a temporary DNS
error. A later attempt may produce a final result.
Kucherawy Expires September 12, 2008 [Page 11]
Internet-Draft Authentication-Results Header March 2008
permerror: A DKIM policy could not be retrieved due to some error
which is likely not transient in nature, such as a permanent DNS
error. A later attempt is unlikely to produce a final result.
2.4.3. SPF and Sender-ID Results
The result values are used by [SPF] and [SENDERID] as follows:
none: No policy records were published by the sender's domain.
neutral: The sender's domain has asserted that it cannot or does not
want to assert a policy record suitable for evaluation of the
authentication method.
pass: The client is authorized to inject or relay mail on behalf of
the sender's domain.
hardfail: This client is explicitly not authorized to inject or
relay mail on behalf of the sender's domain.
softfail: The sender's domain believes the client was not authorized
to inject or relay mail on its behalf but is unwilling to make a
strong assertion to that effect.
temperror: The message could not be verified due to some error which
is likely transient in nature, such as a temporary inability to
retrieve a policy record from DNS. A later attempt may produce a
final result.
permerror: The message could not be verified due to some error which
is unrecoverable, such as a required header field being absent. A
later attempt is unlikley to produce a final result.
2.4.4. iprev Results
The result values are used by the "iprev" method, defined in
Section 3, are as follows:
pass: The reverse DNS evaluation succeeded, i.e. the "reverse" and
"forward" lookup results were in agreement.
hardfail: The reverse DNS evaluation failed. In particular, the
"reverse" and "forward" lookups each produced results but they
were not in agreement.
Kucherawy Expires September 12, 2008 [Page 12]
Internet-Draft Authentication-Results Header March 2008
softfail: The reverse DNS evaluation failed. In particular, one or
both of the "reverse" and forward lookups returned no data (i.e. a
DNS reply code of NODATA).
temperror: The reverse DNS evaluation could not be completed due to
some error which is likely transient in nature, such as a
temporary DNS error. A later attempt may produce a final result.
permerror: The reverse DNS evaluation could not be completed due to
some error which is unrecoverable (e.g. a DNS reply code of
NXDOMAIN). A later attempt is unlikely to produce a final result.
2.4.5. SMTP AUTH Results
The result values are used by the [AUTH] method are as follows:
none: SMTP authentication was not attempted.
pass: The SMTP client had authenicated to the server reporting the
result using the protocol described in [AUTH].
hardfail: The SMTP client had attempted to authenticate to the
server using the protocol described in [AUTH] but was not
successful, yet continued to send the message about which a result
is being reported.
temperror: The SMTP client attempted to authenticate using the
protocol described in [AUTH] but was not able to complete the
attempt due to some error which is likely transient in nature,
such as a temporary LDAP lookup error. A later attempt may
produce a final result.
Note that an agent making use of the data provided by this header
field SHOULD consider "hardfail" and "temperror" to be the synonymous
in terms of message authentication, i.e. the client did not
authenticate.
2.5. Definition Of Initial Methods
As they are currently existing specifications for message
authentication, it is appropriate to define an authentication method
identifier for each of [AUTH], [DKIM], [DOMAINKEYS], [SENDERID] and
[SPF]. Therefore, the authentication method identifiers "auth",
"dkim", "domainkeys", "senderid" and "spf" respectively are hereby
defined for MTAs applying those specifications for e-mail message
authentication. See Section 7 for details.
Kucherawy Expires September 12, 2008 [Page 13]
Internet-Draft Authentication-Results Header March 2008
2.6. Extension Methods
Additional authentication method identifiers (extension methods) may
be defined in the future by later revisions or extensions to this
specification. Extension methods beginning with "x-" will never be
defined as standard fields; such names are reserved for experimental
use. Method identifiers not beginning with "x-" MUST be registered
with the Internet Assigned Numbers Authority (IANA) and published in
an RFC. See Section 7 for further details.
Extension methods may be defined for the following reasons:
1. To allow additional information from new authentication systems
to be communicated to MUAs. The names of such identifiers should
reflect the name of the method being defined, but should not be
needlessly long.
2. To allow the creation of "sub-identifiers" which indicate
different levels of authentication and differentiate between
their relative strengths, e.g. "auth1-weak" and "auth1-strong".
Implementations of new methods MUST use the "x-" prefix until such
time as the new method is registered by IANA.
Authentication method implementors are encouraged to provide adequate
information, via [MAIL] comments if necessary, to allow an MUA
developer to understand or relay ancilliary details of authentication
results. For example, if it might be of interest to relay what data
was used to perform an evaluation, such information could be relayed
as a comment in the header field, such as:
Authentication-Results: mx.example.com;
foo=pass bar.baz=blob (2 of 3 tests OK)
Experimental method identifiers MUST only be used within trust
domains that have explicitly consented to use them. These method
identifiers and the parameters associated with them are not
documented in RFCs. Therefore, they are subject to change at any
time and not suitable for production use. Any MTA or MUA intended
for production use SHOULD ignore or delete any Authentication-Results
header that includes an experimental method identifier.
_______________________________________________
NOTE WELL: This list operates according to
http://mipassoc.org/dkim/ietf-list-rules.html