Canonicaliser
Date: 2009-06-07

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## 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`

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

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