badpenguin.dkim
Class Canonicaliser

java.lang.Object
  badpenguin.dkim.Canonicaliser

public class Canonicaliser
extends java.lang.Object

The Canonicaliser class is responsible for preparing a message for signing or verification. It understands the DKIM canonical methods simple and relaxed, as well as the DomainKey methods simple and nofws.

Author:

Mark Boddington <dk_NO_im@_SP_bad_AM_penguin.co.uk>
http://www.badpenguin.co.uk

Constructor Summary

Canonicaliser()
Create a new canonicaliser instance.

Canonicaliser(java.lang.String sigPref)
Create a new canonicaliser instance, which will prefer to use the Signature type specified in sigPref (either "DomainKey" or "DKIM").

Method Summary

java.util.Stack<java.lang.String>	getDkimHeaders() If the Canonicaliser was initialised for verification with initVerify(headerStream), then all DKIM signatures will be available in a Stack.
java.util.Stack<java.lang.String>	getDomKeyHeaders() If the Canonicaliser was initialised for verification with initVerify(headerStream), then all DomainKey signatures will be available in a Stack.
java.lang.String	getRecommendedHeaders() Return a colon separated list of headers, which were found in this message, and are recommended for signing by the DKIM RFC.
void	initSign(java.io.ByteArrayOutputStream headerStream) Initialise this canonicaliser for use in signing.
void	initVerify(java.io.ByteArrayOutputStream headerStream) Initialise this Canonicaliser for Verification.
java.lang.String	initVerify(java.io.ByteArrayOutputStream headerStream, boolean fallback) Initialise this Canonicaliser for Verification.
java.lang.String	processBody(java.io.ByteArrayOutputStream bodyStream, long length, CanonicalMethod method) Read the body from the given byte stream and process it with the specified canonicalisation method.
java.lang.String	processHeaders(DkimSignature dkimSig) Process the headers provided during initialisation.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Canonicaliser

public Canonicaliser(java.lang.String sigPref)

Create a new canonicaliser instance, which will prefer to use the Signature type specified in sigPref (either "DomainKey" or "DKIM"). If you initialise this instance for signing, then we will create the appropriate header based on this preference. If this instance is initialised for Verification, then we will attempt to verify the header of this preference, if both are present.

Parameters:

sigPref - - Signature preference, DKIM or DomainKey

Canonicaliser

public Canonicaliser()

Create a new canonicaliser instance. This instance will prefer to use the DKIM signature. If you initialise this instance for signing, then we will create a DKIM-Signature. If you initialise for Verification, then we will chose a DKIM-Signature over a DomainKey-Signature, should both be present.

Method Detail

getRecommendedHeaders

public java.lang.String getRecommendedHeaders()
                                       throws DkimException

Return a colon separated list of headers, which were found in this message, and are recommended for signing by the DKIM RFC. The string returned is in an appropriate format for use in the DkimSignature.setHtag(String) method.
We will throw a DkimException if you attempt to call this method, before you have called initHeaders()

Returns:

Colon separated header list

Throws:

DkimException

processBody

public java.lang.String processBody(java.io.ByteArrayOutputStream bodyStream,
                                    long length,
                                    CanonicalMethod method)
                             throws DkimException

Read the body from the given byte stream and process it with the specified canonicalisation method. If the length argument is greater than -1, then we will truncate the body data to the given length. this method returns the body data in a String, ready to be signed or verified.

Parameters:

bodyStream - - The body data to be processed

length - - The length at which to truncate the body, or -1

method - - The CanonicalMethod to use

Returns:

A string containing the canonicalised body

Throws:

DkimException

processHeaders

public java.lang.String processHeaders(DkimSignature dkimSig)
                                throws DkimException

Process the headers provided during initialisation. We will read the Canonicalisation method, as well as other data from the provided DkimSignature object. This method returns the headers in a String, ready to be signed or verified.

Parameters:

dkimSig - - The DkimSignature object which relates to these headers

Returns:

The processed headers, ready for signing/verifying

Throws:

DkimException

initVerify

public java.lang.String initVerify(java.io.ByteArrayOutputStream headerStream,
                                   boolean fallback)
                            throws DkimException

Initialise this Canonicaliser for Verification. We will read in the headers from the message, and they will be placed onto a stack for later processing with processHeaders(). This method will return either the DKIM or DomainKey signature based on the preference set during initialisation. If the fallback option is set to true, then we will return the other signature, should the preferred signature be unavailable.

Parameters:

headerStream - - The message headers to be read

fallback - - Should we fall back to the other DomainKey header?

Returns:

The DKIM-Signature or DomainKey-Signature

Throws:

DkimException

initVerify

public void initVerify(java.io.ByteArrayOutputStream headerStream)
                throws DkimException

Initialise this Canonicaliser for Verification. We will read in the headers from the message, and they will be placed onto a stack for later processing with processHeaders(). This method will store all DKIM and DomainKey Signatures inside Stacks, which can then be accessed via....

Parameters:

headerStream -

Throws:

DkimException

initSign

public void initSign(java.io.ByteArrayOutputStream headerStream)
              throws DkimException

Initialise this canonicaliser for use in signing. A flag will be set to indicate the that the DKIM-signature is being created and not to be expected in the mail headers.

Parameters:

headerStream - - The message headers to be read.

Throws:

DkimException

getDkimHeaders

public java.util.Stack<java.lang.String> getDkimHeaders()
                                                 throws DkimException

If the Canonicaliser was initialised for verification with initVerify(headerStream), then all DKIM signatures will be available in a Stack. The Stack is ordered in a LIFO manner, so the last DKIM Signature found will be at index 0.
Please note that the returned Stack may be empty.
We will throw a DkimException if the Stack is uninitialised, the most likely cause of which is that initVerify(headerStream, fallback) was called, which returns a single Signature itself, and does not store multiple signatures.

Returns:

Stack of DKIM Signatures

Throws:

DkimException

getDomKeyHeaders

public java.util.Stack<java.lang.String> getDomKeyHeaders()
                                                   throws DkimException

If the Canonicaliser was initialised for verification with initVerify(headerStream), then all DomainKey signatures will be available in a Stack. The Stack is ordered in a LIFO manner, so the last DomainKey Signature found will be at index 0.
Please note that the returned Stack may be empty.
We will throw a DkimException if the Stack is uninitialised, the most likely cause of which is that initVerify(headerStream, fallback) was called, which returns a single Signature itself, and does not store multiple signatures.

Returns:

Stack of DomainKey Signatures

Throws:

DkimException