com.lacinato.tools.bdkim
Class BdkimAnalyzer.SignatureResults
java.lang.Object
com.lacinato.tools.bdkim.BdkimAnalyzer.SignatureResults
- Enclosing class:
- BdkimAnalyzer
public static class BdkimAnalyzer.SignatureResults
- extends java.lang.Object
A structured data object that holds the results of the DomainKey/DKIM evaluation.
A count of the number of signatures encountered is kept. Using getNumberOfSignatures(),
you can iterate through the results using the other access methods. The results are
indexed starting at 0.
Any signature, whether valid or not, will get an entry in this results object. As long
as the header name is present, it will be evaluated and a result will be found here.
Method Summary |
java.lang.String |
getDomain(int index)
Return the domain purportedly responsible for the signature with no whitespace, etc. |
java.lang.String[] |
getHeaderList(int index)
This method returns the list of signed headers for the signature specified by the
index argument as an array of string values containing no whitespace or colons. |
int |
getNumberOfSignatures()
Returns the number of signtures represented in this SignatureResults object. |
java.lang.String |
getRawHeaderList(int index)
Returns the raw string from Mail::DKIM representing the (colon-separated) list of headers that were
signed by the signature at the given index. |
java.lang.String |
getRawResult(int index)
Returns the raw result string from Mail::DKIM. |
BdkimAnalyzer.SignatureResults.DkimStatus |
getResult(int index)
Returns the result of the evaluation of the signature at the given index in the results
arrays. |
BdkimAnalyzer.SignatureResults.DkimStatus |
getSummaryResult()
If you say: "I just want one single pass/fail/none/invalid result for my message instead of an over-complex set of methods", then
this method may be for you. |
static java.lang.String |
resultToString(BdkimAnalyzer.SignatureResults.DkimStatus result)
Useful for translating the DkimStatus values into readable strings. |
java.lang.String |
toString()
Generates a sort-of-pretty one-line string version of the contents of this SignatureResults object. |
Methods inherited from class java.lang.Object |
equals, getClass, hashCode, notify, notifyAll, wait, wait, wait |
BdkimAnalyzer.SignatureResults
public BdkimAnalyzer.SignatureResults()
- Creates an empty set of results (number of signaures == 0)
getNumberOfSignatures
public int getNumberOfSignatures()
- Returns the number of signtures represented in this SignatureResults object. You can use this
value to loop through the results. If this returns X>0, then you can call, for example,
getResult(0) through getResult(X-1) to get the results for the various signatures.
- Returns:
- the number of signtures represented in this SignatureResults object.
getSummaryResult
public BdkimAnalyzer.SignatureResults.DkimStatus getSummaryResult()
- If you say: "I just want one single pass/fail/none/invalid result for my message instead of an over-complex set of methods", then
this method may be for you.
Most verifiers will give you such a shorthand result (one of the main Mail::DKIM::Verifier methods, not used by BdkimAnalyzer, does so),
but they all make algorithmic decisions on how to handle cases where signatures disagree (e.g. what if one says pass,
one says fail, or if one says pass and one says invalid, or two say pass and one says fail, etc.) The best thing is for you to use
the various get() methods for the SignatureResults object and make your own algorithm which could, for example, take into account
which headers were signed. But if you just want "one answer" you can use this method.
Mail::DKIM's technique: ":In case of multiple signatures, the signature with the "best" result
will be returned. Best is defined as "pass", followed by "fail", "invalid", and "none"".
Implemented here is the same algorithm as Mail::DKIM, with the added note that this ranking
goes as: pass, fail, policy, invalid, none, temperror, and permerror (but see documentation for getResult() about those results -- not
all are actually currently possible).
This will return from among the same group results at getResult() with the exception that this method can also return "none" if
the results object is empty (i.e. no signatures were present, whether valid or not).
getResult
public BdkimAnalyzer.SignatureResults.DkimStatus getResult(int index)
- Returns the result of the evaluation of the signature at the given index in the results
arrays. Mail::DKIM returns more verbose information, but this method strips that out and gives one of
the following: "pass", "invalid", "fail", or "temperror". Note
that this method could technically return "permerror" or "policy" as well, but Mail::DKIM never
actually returns those values (as of version 0.39). Also note that since these are results for specific signatures,
you won't see "none". A DomainKey/DKIM "none" result is indicated by getNumberOfSignatures() == 0.
This method will return null for bad values of index or other strangeness.
Regarding "temperror", Mail::DKIM says: "Returned if a DKIM-Signature could not be checked
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 better result."
- See Also:
- http://www.dkim.org/specs/draft-kucherawy-sender-auth-header-14.html#rfc.section.2.4.1 for more info on DK/DKIM results.
getRawResult
public java.lang.String getRawResult(int index)
- Returns the raw result string from Mail::DKIM.
Mail::DKIM returns results for each signature with some verbosity. The getResult() method strips that information out,
but this method will return the raw string that Mail::DKIM returned. This may be useful if, for example, you get a
DkimStatus.FAIL or INVALID or TEMPERROR and want to do something with the explanation string that Mail::DKIM returned,
such as log it or present it to a person as part of an explanation of why a message was denied, etc.
This method will return null for bad values of index or other strangeness.
resultToString
public static java.lang.String resultToString(BdkimAnalyzer.SignatureResults.DkimStatus result)
- Useful for translating the DkimStatus values into readable strings.
- Returns:
- "none", "pass", "invalid", etc.
getHeaderList
public java.lang.String[] getHeaderList(int index)
- This method returns the list of signed headers for the signature specified by the
index argument as an array of string values containing no whitespace or colons.
DomainKey and DKIM signatures specify which of the message headers
are signed by the signature -- this method lets you know which ones were signed.
This method returns null on errors.
Note that a Mail::DKIM limitation means that DomainKey-Signature headers that lack the
optional h= tag will return no header list at all even though in that case all headers
are signed (that tag is optional for DK, but not for DKIM).
Note that there is a chance there will be some whitespace in a given header... I can't
confirm with total certainty that in all cases Mail::DKIM won't generate whitespace
(e.g. malformed signatures, etc), so if you care, run your own check (e.g. do a
trim() and replace whitespace with ""). There won't be any newlines or
carriage returns in a header returned by this method..
getRawHeaderList
public java.lang.String getRawHeaderList(int index)
- Returns the raw string from Mail::DKIM representing the (colon-separated) list of headers that were
signed by the signature at the given index.
This method will return null for bad values of index or other strangeness.
getDomain
public java.lang.String getDomain(int index)
- Return the domain purportedly responsible for the signature with no whitespace, etc.
This method will return null for bad values of index or other strangeness.
toString
public java.lang.String toString()
- Generates a sort-of-pretty one-line string version of the contents of this SignatureResults object.
- Overrides:
toString
in class java.lang.Object