org.apache.james.transport.mailets.smime
Class SMIMEAbstractSign

java.lang.Object
  org.apache.mailet.GenericMailet
      org.apache.james.transport.mailets.smime.SMIMEAbstractSign

All Implemented Interfaces:

Mailet, MailetConfig

Direct Known Subclasses:

SMIMESign

public abstract class SMIMEAbstractSign
extends GenericMailet

Abstract mailet providing common SMIME signature services.
It can be subclassed to make authoring signing mailets simple.
By extending it and overriding one or more of the following methods a new behaviour can be quickly created without the author having to address any issue other than the relevant one:

• initDebug(), setDebug(boolean) and isDebug() manage the debugging mode.
• initExplanationText(), setExplanationText(java.lang.String) and getExplanationText() manage the text of an attachment that will be added to explain the meaning of this server-side signature.
• initKeyHolder(), setKeyHolder(org.apache.james.security.KeyHolder) and getKeyHolder() manage the KeyHolder object that will contain the keys and certificates and will do the crypto work.
• initPostmasterSigns(), setPostmasterSigns(boolean) and isPostmasterSigns() determines whether messages originated by the Postmaster will be signed or not.
• initRebuildFrom(), setRebuildFrom(boolean) and isRebuildFrom() determines whether the "From:" header will be rebuilt to neutralize the wrong behaviour of some MUAs like Microsoft Outlook Express.
• initSignerName(), setSignerName(java.lang.String) and getSignerName() manage the name of the signer to be shown in the explanation text.
• isOkToSign(org.apache.mailet.Mail) controls whether the mail can be signed or not.
• The abstract method getWrapperBodyPart(org.apache.mailet.Mail) returns the massaged MimeBodyPart that will be signed, or null if the message has to be signed "as is".

Handles the following init parameters:

• <debug>: if true some useful information is logged. The default is false.
• <keyStoreFileName>: the KeyStore full file name.
• <keyStorePassword>: the KeyStore password. If given, it is used to check the integrity of the keystore data, otherwise, if null, the integrity of the keystore is not checked.
• <keyAlias>: the alias name to use to search the Key using KeyStore.getKey(java.lang.String, char[]). The default is to look for the first and only alias in the keystore; if zero or more than one is found a KeyStoreException is thrown.
• <keyAliasPassword>: the alias password. The default is to use the KeyStore password. At least one of the passwords must be provided.
• <keyStoreType>: the type of the keystore. The default will use KeyStore.getDefaultType().
• <postmasterSigns>: if true the message will be signed even if the sender is the Postmaster. The default is false.
• <rebuildFrom>: If true will modify the "From:" header. For more info see isRebuildFrom(). The default is false.
• <signerName>: the name of the signer to be shown in the explanation text. The default is to use the "CN=" property of the signing certificate.
• <explanationText>: the text of an explanation of the meaning of this server-side signature. May contain the following substitution patterns (see also getReplacedExplanationText(java.lang.String, java.lang.String, java.lang.String, java.lang.String, java.lang.String)): [signerName], [signerAddress], [reversePath], [headers]. It should be included in the signature. The actual presentation of the text depends on the specific concrete mailet subclass: see for example SMIMESign. The default is to not have any explanation text.

Since:

2.2.1

Version:

CVS $Revision: 494012 $ $Date: 2007-01-08 10:23:58 +0000 (lun, 08 gen 2007) $

Constructor Summary

SMIMEAbstractSign()

Method Summary

protected boolean	fromAddressSameAsReverse(Mail mail) Utility method that checks if there is at least one address in the "From:" header same as the reverse-path.
protected abstract java.lang.String[]	getAllowedInitParameters() Gets the expected init parameters.
java.lang.String	getExplanationText() Getter for property explanationText.
protected KeyHolder	getKeyHolder() Getter for property keyHolder.
protected java.lang.String	getMessageHeaders(javax.mail.internet.MimeMessage message) Utility method for obtaining a string representation of the Message's headers
protected java.lang.String	getReplacedExplanationText(java.lang.String explanationText, java.lang.String signerName, java.lang.String signerAddress, java.lang.String reversePath, java.lang.String headers) Prepares the explanation text making substitutions in the explanationText template string.
java.lang.String	getSignerName() Getter for property signerName.
protected abstract javax.mail.internet.MimeBodyPart	getWrapperBodyPart(Mail mail) Creates the MimeBodyPart that will be signed.
void	init() Mailet initialization routine.
protected void	initDebug() Initializer for property debug.
protected void	initExplanationText() Initializer for property explanationText.
protected void	initKeyHolder() Initializer for property keyHolder.
protected void	initPostmasterSigns() Initializer for property postmasterSigns.
protected void	initRebuildFrom() Initializer for property rebuildFrom.
protected void	initSignerName() Initializer for property signerName.
boolean	isDebug() Getter for property debug.
protected boolean	isOkToSign(Mail mail) Checks if the mail can be signed.
boolean	isPostmasterSigns() Getter for property postmasterSigns.
boolean	isRebuildFrom() Getter for property rebuildFrom.
void	service(Mail mail) Service does the hard work, and signs
void	setDebug(boolean debug) Setter for property debug.
void	setExplanationText(java.lang.String explanationText) Setter for property explanationText.
protected void	setKeyHolder(KeyHolder keyHolder) Setter for property keyHolder.
void	setPostmasterSigns(boolean postmasterSigns) Setter for property postmasterSigns.
void	setRebuildFrom(boolean rebuildFrom) Setter for property rebuildFrom.
void	setSignerName(java.lang.String signerName) Setter for property signerName.

Methods inherited from class org.apache.mailet.GenericMailet

destroy, getInitParameter, getInitParameter, getInitParameterNames, getMailetConfig, getMailetContext, getMailetInfo, getMailetName, init, log, log

Methods inherited from class java.lang.Object

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

Constructor Detail

SMIMEAbstractSign

public SMIMEAbstractSign()

Method Detail

getAllowedInitParameters

protected abstract java.lang.String[] getAllowedInitParameters()

Gets the expected init parameters.

Returns:

An array containing the parameter names allowed for this mailet.

initDebug

protected void initDebug()

Initializer for property debug.

isDebug

public boolean isDebug()

Getter for property debug.

Returns:

Value of property debug.

setDebug

public void setDebug(boolean debug)

Setter for property debug.

Parameters:

debug - New value of property debug.

initExplanationText

protected void initExplanationText()

Initializer for property explanationText.

getExplanationText

public java.lang.String getExplanationText()

Getter for property explanationText. Text to be used in the SignatureExplanation.txt file.

Returns:

Value of property explanationText.

setExplanationText

public void setExplanationText(java.lang.String explanationText)

Setter for property explanationText.

Parameters:

explanationText - New value of property explanationText.

initKeyHolder

protected void initKeyHolder()
                      throws java.lang.Exception

Initializer for property keyHolder.

Throws:

java.lang.Exception

getKeyHolder

protected KeyHolder getKeyHolder()

Getter for property keyHolder. It is protected instead of public for security reasons.

Returns:

Value of property keyHolder.

setKeyHolder

protected void setKeyHolder(KeyHolder keyHolder)

Setter for property keyHolder. It is protected instead of public for security reasons.

Parameters:

keyHolder - New value of property keyHolder.

initPostmasterSigns

protected void initPostmasterSigns()

Initializer for property postmasterSigns.

isPostmasterSigns

public boolean isPostmasterSigns()

Getter for property postmasterSigns. If true will sign messages signed by the postmaster.

Returns:

Value of property postmasterSigns.

setPostmasterSigns

public void setPostmasterSigns(boolean postmasterSigns)

Setter for property postmasterSigns.

Parameters:

postmasterSigns - New value of property postmasterSigns.

initRebuildFrom

protected void initRebuildFrom()
                        throws javax.mail.MessagingException

Initializer for property rebuildFrom.

Throws:

javax.mail.MessagingException

isRebuildFrom

public boolean isRebuildFrom()

Getter for property rebuildFrom. If true will modify the "From:" header.

The modification is as follows: assuming that the signer mail address in the signer certificate is trusted-server@xxx.com> and that From: "John Smith" we will get From: "John Smith" " <trusted-server@xxx.com>.

If the "ReplyTo:" header is missing or empty it will be set to the original "From:" header.

Such modification is necessary to achieve a correct behaviour with some mail clients (e.g. Microsoft Outlook Express).

Returns:

Value of property rebuildFrom.

setRebuildFrom

public void setRebuildFrom(boolean rebuildFrom)

Setter for property rebuildFrom.

Parameters:

rebuildFrom - New value of property rebuildFrom.

initSignerName

protected void initSignerName()

Initializer for property signerName.

getSignerName

public java.lang.String getSignerName()

Getter for property signerName.

Returns:

Value of property signerName.

setSignerName

public void setSignerName(java.lang.String signerName)

Setter for property signerName.

Parameters:

signerName - New value of property signerName.

init

public void init()
          throws javax.mail.MessagingException

Mailet initialization routine.

Overrides:

init in class GenericMailet

Throws:

javax.mail.MessagingException - if an exception occurs that interrupts the mailet's normal operation

service

public void service(Mail mail)
             throws javax.mail.MessagingException

Service does the hard work, and signs

Specified by:

service in interface Mailet

Specified by:

service in class GenericMailet

Parameters:

mail - the mail to sign

Throws:

javax.mail.MessagingException - if a problem arises signing the mail

isOkToSign

protected boolean isOkToSign(Mail mail)
                      throws javax.mail.MessagingException

Checks if the mail can be signed.

Rules:

1. The reverse-path != null (it is not a bounce).
2. The sender user must have been SMTP authenticated.
3. Either:
• The reverse-path is the postmaster address and isPostmasterSigns() returns true
• or the reverse-path == the authenticated user and there is at least one "From:" address == reverse-path.
.
4. The message has not already been signed (mimeType != multipart/signed and != application/pkcs7-mime).

Parameters:

mail - The mail object to check.

Returns:

True if can be signed.

Throws:

javax.mail.MessagingException

getWrapperBodyPart

protected abstract javax.mail.internet.MimeBodyPart getWrapperBodyPart(Mail mail)
                                                                throws javax.mail.MessagingException,
                                                                       java.io.IOException

Creates the MimeBodyPart that will be signed. For example, may attach a text file explaining the meaning of the signature, or an XML file containing information that can be checked by other MTAs.

Parameters:

mail - The mail to massage.

Returns:

The massaged MimeBodyPart to sign, or null to have the whole message signed "as is".

Throws:

javax.mail.MessagingException

java.io.IOException

fromAddressSameAsReverse

protected final boolean fromAddressSameAsReverse(Mail mail)

Utility method that checks if there is at least one address in the "From:" header same as the reverse-path.

Parameters:

mail - The mail to check.

Returns:

True if an address is found, false otherwise.

getMessageHeaders

protected final java.lang.String getMessageHeaders(javax.mail.internet.MimeMessage message)
                                            throws javax.mail.MessagingException

Utility method for obtaining a string representation of the Message's headers

Parameters:

message - The message to extract the headers from.

Returns:

The string containing the headers.

Throws:

javax.mail.MessagingException

getReplacedExplanationText

protected final java.lang.String getReplacedExplanationText(java.lang.String explanationText,
                                                            java.lang.String signerName,
                                                            java.lang.String signerAddress,
                                                            java.lang.String reversePath,
                                                            java.lang.String headers)

Prepares the explanation text making substitutions in the explanationText template string. Utility method that searches for all occurrences of some pattern strings and substitute them with the appropriate params.

Parameters:

explanationText - The template string for the explanation text.

signerName - The string that will replace the [signerName] pattern.

signerAddress - The string that will replace the [signerAddress] pattern.

reversePath - The string that will replace the [reversePath] pattern.

headers - The string that will replace the [headers] pattern.

Returns:

The actual explanation text string with all replacements done.