badpenguin.dkim
Class Canonicaliser

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


© Copyright 2009 Mark Boddington (www.badpenguin.co.uk)