com.lacinato.tools.bdkim
Class BdkimAnalyzer

java.lang.Object
  extended by com.lacinato.tools.bdkim.BdkimAnalyzer

public class BdkimAnalyzer
extends java.lang.Object

A Java client to the BDKIM perl server process, this class provides convenience methods for sending a message to the perl server and receiving the evaluated DomainKey and DKIM results. It does not handle signing of messages, only verification.

See determineDkimStatuses() for basic usage.

For more information, see http://lacinato.com/cm/software/emailrelated/bdkim

Version:
1.0
Author:
Casey Connor -- lacinato.com

Nested Class Summary
static class BdkimAnalyzer.SignatureResults
          A structured data object that holds the results of the DomainKey/DKIM evaluation.
 
Field Summary
static int DEFAULT_CONNECT_TRIES
          Default 3 total attempts to connect to non-responsive server port
static int DEFAULT_CONNECTION_TIMEOUT
          Default 15 seconds
static int DEFAULT_DATA_TIMEOUT
          Default 300 seconds - DNS calls could take a while on the perl side
static java.lang.String DEFAULT_HOST
          Default "localhost"
static int DEFAULT_PORT
          Default 12300
 
Constructor Summary
BdkimAnalyzer()
           
 
Method Summary
 BdkimAnalyzer.SignatureResults determineDkimStatuses(java.lang.String raw_message)
          This is the main API call into BdkimAnalyzer.
 BdkimAnalyzer.SignatureResults determineDkimStatuses(java.lang.String raw_message, boolean check_for_headers)
          Given a raw message (headers and all), this method will return the DK/DKIM results from the perl BDKIM server.
 int getConnectionTimeout()
           
 int getConnectTries()
           
 int getDataTimeout()
           
 java.lang.String getHost()
           
 int getPort()
           
 boolean hasDkOrDkimHeaders(java.lang.String message_txt)
          This method is public as a possible convenience only.
 void setConnectionTimeout(int s)
          Set the connection timeout value for connection to the BDKIM perl server, value specified in seconds; this only applies when first creating the connection, not during data transmission.
 void setConnectTries(int t)
          Set the number of attempts to be made to connect to the server before failing a given connection attempt (for one message)
 void setDataTimeout(int s)
          Set the connection timeout value for connection to the BDKIM perl server, value specified in seconds; this only applies when sending data to the server, not when making the original connection.
 void setHost(java.lang.String h)
          host name, or IP address in String form, pointing to the BDKIM perl server, e.g.
 void setPort(int p)
          Port to use when contacting the BDKIM perl serevr -- must be between 0 and 65535, inclusive
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

DEFAULT_PORT

public static final int DEFAULT_PORT
Default 12300

See Also:
Constant Field Values

DEFAULT_HOST

public static final java.lang.String DEFAULT_HOST
Default "localhost"

See Also:
Constant Field Values

DEFAULT_CONNECTION_TIMEOUT

public static final int DEFAULT_CONNECTION_TIMEOUT
Default 15 seconds

See Also:
Constant Field Values

DEFAULT_DATA_TIMEOUT

public static final int DEFAULT_DATA_TIMEOUT
Default 300 seconds - DNS calls could take a while on the perl side

See Also:
Constant Field Values

DEFAULT_CONNECT_TRIES

public static final int DEFAULT_CONNECT_TRIES
Default 3 total attempts to connect to non-responsive server port

See Also:
Constant Field Values
Constructor Detail

BdkimAnalyzer

public BdkimAnalyzer()
Method Detail

determineDkimStatuses

public BdkimAnalyzer.SignatureResults determineDkimStatuses(java.lang.String raw_message)
                                                     throws AuthVerificationException
This is the main API call into BdkimAnalyzer.

Given a raw message (headers and all), this method will return the DK/DKIM results from the perl BDKIM server. It will throw an AuthVerificationException (with explanatory copy inside it) on errors, timeouts, etc. (Note that DKIM results of "temperror" et al. will not throw exceptions, but will return as results in the SignatureResults object.) See the SignatureResults documentation for important information about interpreting results.

Line endings are important in evaluating the DK/DKIM results of email messages. Message lines are supposed to end with \r\n. This method will make sure the lines have those endings before sending to the perl server, so you don't have to worry about it.

This class will do character encoding and decoding based on whatever the system character set is. It is a good idea that it use the same character set as your perl-side BDKIM server or the verification may have trouble.

On first use, this class will ensure that it can resolve the name of the server it will be connecting to and throw an AuthVerificationException if it can not.

This version of determineDkimStatuses will reflect to determineDkimStatuses(String, boolean) with "true" for the boolean.

Throws:
AuthVerificationException

determineDkimStatuses

public BdkimAnalyzer.SignatureResults determineDkimStatuses(java.lang.String raw_message,
                                                            boolean check_for_headers)
                                                     throws AuthVerificationException
Given a raw message (headers and all), this method will return the DK/DKIM results from the perl BDKIM server. It will throw an AuthVerificationException (with explanatory copy inside it) on errors, timeouts, etc. (Note that DKIM "permerror" et al. will not throw exceptions, but will return as results in the SignatureResults object.) See the SignatureResults documentation for important information about interpreting results.

If "check for headers" is true, then this method will check the headers of the email message for DomainKey and DKIM signatures. If it finds none, it will not bother to send the messasge to the BDKIM server and will return an empty SignatureResults object. Use this feature if you are verifying messages that may not have such headers in them. If you know that the messages you are verifying have signatures in them, then you can pass this as "false" to save a tiny bit of wasted effort. Note that whatever the setting of this boolean, the BDKIM perl server does its own check of the headers before bothering to compute the results of the entire message (see private method queryBDKIM() for more on that).

Line endings are important in evaluating the DK/DKIM results of email messages. Message lines are supposed to end with \r\n. This method will make sure the lines have those endings before sending to the perl server, so you don't have to worry about it.

This class will do character encoding and decoding based on whatever the system character set is. It is a good idea that it use the same character set as your perl-side BDKIM server or the verification may have trouble.

On first use, this class will ensure that it can resolve the name of the server it will be connecting to and throw an AuthVerificationException if it can not.

Throws:
AuthVerificationException

hasDkOrDkimHeaders

public boolean hasDkOrDkimHeaders(java.lang.String message_txt)
This method is public as a possible convenience only. You don't need it, generally.

Returns:
true if the raw email message represented by message_txt contains any DomainKey or DKIM headers in the header section (case-insensitive)

setPort

public void setPort(int p)
Port to use when contacting the BDKIM perl serevr -- must be between 0 and 65535, inclusive


getPort

public int getPort()

setHost

public void setHost(java.lang.String h)
host name, or IP address in String form, pointing to the BDKIM perl server, e.g. "localhost" or "127.0.0.1" or "123.123.123.123"


getHost

public java.lang.String getHost()

setConnectionTimeout

public void setConnectionTimeout(int s)
Set the connection timeout value for connection to the BDKIM perl server, value specified in seconds; this only applies when first creating the connection, not during data transmission.


getConnectionTimeout

public int getConnectionTimeout()
Returns:
the timeout value, in seconds

setDataTimeout

public void setDataTimeout(int s)
Set the connection timeout value for connection to the BDKIM perl server, value specified in seconds; this only applies when sending data to the server, not when making the original connection.


getDataTimeout

public int getDataTimeout()
Returns:
the timeout value, in seconds

setConnectTries

public void setConnectTries(int t)
Set the number of attempts to be made to connect to the server before failing a given connection attempt (for one message)


getConnectTries

public int getConnectTries()