com.lacinato.tools.bdkim
Class BdkimAnalyzer.SignatureResults

java.lang.Object
  extended by 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.


Nested Class Summary
static class BdkimAnalyzer.SignatureResults.DkimStatus
          DomainKey and DKIM results.
 
Constructor Summary
BdkimAnalyzer.SignatureResults()
          Creates an empty set of results (number of signaures == 0)
 
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
 

Constructor Detail

BdkimAnalyzer.SignatureResults

public BdkimAnalyzer.SignatureResults()
Creates an empty set of results (number of signaures == 0)

Method Detail

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