Enhydra-Oyster 2.1-7 API

org.enhydra.oyster.smime
Class BaseSignedSMIMEObject

java.lang.Object
  extended byorg.enhydra.oyster.smime.BaseSMIMEObject
      extended byorg.enhydra.oyster.smime.BaseSignedSMIMEObject
All Implemented Interfaces:
KeyStoreConstants, SignedConstants
Direct Known Subclasses:
SignedAndEnvelopedSMIME, SignedSMIME

public class BaseSignedSMIMEObject
extends BaseSMIMEObject
implements SignedConstants

This class is used as super class for SignedSMIME and SignedAndEnvelopedSMIME classes. It contains the common methods for this two classes.


Field Summary
protected  java.util.Vector aditionalCerts
          Storage for additional certificates
protected  java.util.Vector capabilities
          Storage for capabilities (used for first type of addSigner function)
protected  java.util.Vector capabilities2
          Storage for capabilities (used for second type of addSigner function)
protected  java.util.Vector capabilitiesTemp
          Temporary storage for capabilities (after method addSigner, this object is copied to capabilities or capabilities2).
protected  java.util.Vector certChainArray
          Storage for certificate chain corresponding to appropriate signing session (used for second type of addSigner function)
protected  java.util.Vector digestArray
          Storage for digest algorithm corresponding to appropriate signing session (used for first type of addSigner function).
protected  java.util.Vector digestArray2
          Storage for digest algorithm corresponding to appropriate signing session (used for second type of addSigner function)
protected  java.util.Vector including
          Storage for byte[2] grouped indicators (used for first type of addSigner function).
protected  java.util.Vector including2
          Storage for byte[2] grouped indicators (used for second type of addSigner function)
protected  java.util.Vector ksArray
          Storage for .pfx files corresponding to appropriate signing session (used for first type of addSigner function).
protected  java.util.Vector privKeyArray
          Storage for private key corresponding to appropriate signing session (used for second type of addSigner function)
 
Fields inherited from class org.enhydra.oyster.smime.BaseSMIMEObject
bodyPartArray, certArray, charsetEnc, contentPresence, externalMessagePresence, indicatorTo, message
 
Fields inherited from interface org.enhydra.oyster.crypto.consts.SignedConstants
MD2_WITH_RSA, MD5_WITH_RSA, SHA1_WITH_DSA, SHA1_WITH_RSA
 
Fields inherited from interface org.enhydra.oyster.crypto.consts.KeyStoreConstants
BKS, JKS, PKCS12, UBER
 
Constructor Summary
protected BaseSignedSMIMEObject()
          Simple constructor.
protected BaseSignedSMIMEObject(javax.mail.internet.MimeMessage mimeMessage)
          Construction of message with external prepared MimeMessage object.
protected BaseSignedSMIMEObject(java.lang.String smtpHost, java.lang.String fromAddress, java.lang.String subject, java.lang.String charset)
          Initializes the JavaMail session for SMTP and the MimeMessage object for message which will be sent.
protected BaseSignedSMIMEObject(java.lang.String smtpHost, java.lang.String fromAddress, java.lang.String subject, java.lang.String content, java.lang.String charset)
          Initializes the JavaMail session for SMTP and the MimeMessage object for message which will be sent.
 
Method Summary
 void addCertificate(java.security.cert.X509Certificate cert)
          Adds additional certificate to signed message.
 void addSigner(java.security.KeyStore kStore, java.lang.String password, java.lang.String alias, java.lang.String signingAlg, boolean includingCert, boolean includingSignAttrib)
          Adds signer to signed and enveloped S/MIME message.
 void addSigner(java.lang.String pfxfileName, java.lang.String password, java.lang.String signingAlg, boolean includingCert, boolean includingSignAttrib)
          Adds signer to signed and enveloped S/MIME message.
 void addSigner(java.lang.String ksPath, java.lang.String ksType, java.lang.String password, java.lang.String alias, java.lang.String signingAlg, boolean includingCert, boolean includingSignAttrib)
          Adds signer to signed and enveloped S/MIME message.
 void addSigner(java.security.cert.X509Certificate[] chain, java.security.PrivateKey privKey, java.lang.String signingAlg, boolean includingCert, boolean includingSignAttrib)
          Adds signer to signed and enveloped S/MIME message.
 void reset()
          Resets all attributes in BaseSignedSMIMEObject to their initial values.
 void setCapabilities(java.lang.String type0, java.lang.String[] capability0)
          Sets Capabilities Attributes (method is optional, but if exists, must be performed before addSigner method).
 
Methods inherited from class org.enhydra.oyster.smime.BaseSMIMEObject
addAttachment, addAttachment, addAttachment, addAttachment, addAttachment, addAttachment, addRecipient, addRecipient, addRecipient, getMimeMessage, initMimeMessage, send, setCharsetEncoding, setContent, setContent, setContent, setContent, setContent, setContent, setContent, setContent, setContent, setContent, setReply
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

ksArray

protected java.util.Vector ksArray
Storage for .pfx files corresponding to appropriate signing session (used for first type of addSigner function).


digestArray

protected java.util.Vector digestArray
Storage for digest algorithm corresponding to appropriate signing session (used for first type of addSigner function).


including

protected java.util.Vector including
Storage for byte[2] grouped indicators (used for first type of addSigner function).


certChainArray

protected java.util.Vector certChainArray
Storage for certificate chain corresponding to appropriate signing session (used for second type of addSigner function)


privKeyArray

protected java.util.Vector privKeyArray
Storage for private key corresponding to appropriate signing session (used for second type of addSigner function)


digestArray2

protected java.util.Vector digestArray2
Storage for digest algorithm corresponding to appropriate signing session (used for second type of addSigner function)


including2

protected java.util.Vector including2
Storage for byte[2] grouped indicators (used for second type of addSigner function)


aditionalCerts

protected java.util.Vector aditionalCerts
Storage for additional certificates


capabilitiesTemp

protected java.util.Vector capabilitiesTemp
Temporary storage for capabilities (after method addSigner, this object is copied to capabilities or capabilities2).


capabilities

protected java.util.Vector capabilities
Storage for capabilities (used for first type of addSigner function)


capabilities2

protected java.util.Vector capabilities2
Storage for capabilities (used for second type of addSigner function)

Constructor Detail

BaseSignedSMIMEObject

protected BaseSignedSMIMEObject()
Simple constructor. Dynamically loads the BC and SUN provider necessary for cryptography processing. This constructor does not create MIME message object, so it is obligatory to invoke initMimeMessage() method after this constructor.


BaseSignedSMIMEObject

protected BaseSignedSMIMEObject(java.lang.String smtpHost,
                                java.lang.String fromAddress,
                                java.lang.String subject,
                                java.lang.String content,
                                java.lang.String charset)
                         throws SMIMEException
Initializes the JavaMail session for SMTP and the MimeMessage object for message which will be sent. Dynamically loads the BC and SUN provider necessary for cryptography processing. This constructor is used for creating message with text/plain content. For creating html formated content (text/html), other constructor should be used in combination with one of setContent methods. Note that after using this constructor setContent method can be used only if "content" argument of constructor was given as null, otherwise setContent method can't be used because content is already set as text/plain.

Parameters:
smtpHost - name of SMTP host used for sending email
fromAddress - email address of sender (FROM field in email header)
subject - subject of email (SUBJECT field in email header). This argument can be null, but email message will be sent withouth SUBJECT.
content - text/plain content of email message. This argument can be null, but later one of setContent() methods or one of addAttachment() methods should be called
charset - character set for passed subject and content. The given Unicode string will be charset-encoded using the specified charset. The charset is also used to set the "charset" parameter. For example German letters should be encoded by usage of 'ISO-8859-1' charset. If charset parameter is null and subject or content contains non US-ASCII characters, it will be encoded using the platform's default charset.
Throws:
SMIMEException - if smtpHost or fromAddress parameters are null. Also, it can be caused by non SMIMEException which is MessagingException.

BaseSignedSMIMEObject

protected BaseSignedSMIMEObject(java.lang.String smtpHost,
                                java.lang.String fromAddress,
                                java.lang.String subject,
                                java.lang.String charset)
                         throws SMIMEException
Initializes the JavaMail session for SMTP and the MimeMessage object for message which will be sent. Dynamically loads the BC and SUN provider necessary for cryptography processing. This constructor does not create content of message and it can be set later with one of setContent methods. Also, message can be left withouth content, but then at least one attachement must be added.

Parameters:
smtpHost - name of SMTP host used for sending email
fromAddress - email address of sender (FROM field in email header)
subject - subject of email (SUBJECT field in email header). This argument can be null, but email message will be sent withouth SUBJECT.
charset - character set for passed subject and content. The given Unicode string will be charset-encoded using the specified charset. The charset is also used to set the "charset" parameter. For example German letters should be encoded by usage of 'ISO-8859-1' charset. If charset parameter is null and subject or content contains non US-ASCII characters, it will be encoded using the platform's default charset.
Throws:
SMIMEException - if smtpHost or fromAddress parameters are null. Also, it can be caused by non SMIMEException which is MessagingException.

BaseSignedSMIMEObject

protected BaseSignedSMIMEObject(javax.mail.internet.MimeMessage mimeMessage)
                         throws SMIMEException
Construction of message with external prepared MimeMessage object. Usage of this constructor disables usage of setContent() and addAttachment() methods. Also, all recipients (TO, CC or BCC type) must be declared again via setRecipient() method, even if they were previously set. Be very carefull with usage of this constructor because all MimeBodyPart objects and MimeMultipart objects used in construction of given MimeMessage object, must have correct defined Content header arguments, and contents. Contents must be formed in format which can be recognised and appropriate interpreted in the process of sending mail. If there is any special content object added to MimeBodyPart object or MimeMultipart object, the appropriate DataContent handler must be created for that object and set to corresponding BodyPart.

Parameters:
mimeMessage - external created MimeMessage object
Throws:
SMIMEException - if smtpHost or fromAddress parameter is null. Also, it can be caused by non SMIMEException which is MessagingException.
Method Detail

setCapabilities

public void setCapabilities(java.lang.String type0,
                            java.lang.String[] capability0)
                     throws SMIMEException
Sets Capabilities Attributes (method is optional, but if exists, must be performed before addSigner method). Depending on parameter type0 (algorithm group type), other parameter contains array of algoriithms from specific group of algorithms in client prefered usage order. Groups of algorithms are:
SIGNATURE - MD2 with RSA, MD5 with RSA, SHA1 with RSA, SHA1 with DSA
SYMMETRIC - RC2 40 bits, RC2 64 bits, RC2 128 bits, DES, DES_EDE3
ENCIPHER - RSA
DEFAULT - sets the default values for all three algorithm group types

It is free to decide which algorithm will be included, or which group of algorithm will be included in Capabilities Attributes. If no groups are added, capabilities attributes won't be added to Signed Attributes. If two or more signers will sign the message, and their capabilities are different, this method should be performed before every signing if we wish to specify Capabilities Attributes for all particular signers. If type0 parameter is set as:

setCapabilities (CapabilitiesConstants.DEFAULT, new String[0])

it is equivalent to:

setCapabilities(CapabilitiesConstants.SYMMETRIC, new String[] {CapabilitiesConstants.RC2_CBC_40});
setCapabilities(CapabilitiesConstants.ENCIPHER, new String[] {CapabilitiesConstants.RSA });
setCapabilities(CapabilitiesConstants.SIGNATURE, new String[] {CapabilitiesConstants.SHA1_WITH_RSA });

Parameters:
type0 - sets group of algorithms for capabilities attributes. It can be set with values: SIGNATURE, SYMMETRIC, ENCIPHER or DEFAULT.
capability0 - array of user prefered algorithms in user prrefered order for each capabilityes group.
Throws:
SMIMEException - if same group is added more than once, invalid group type is used, or group is added after DEFAULT option.

addSigner

public void addSigner(java.lang.String pfxfileName,
                      java.lang.String password,
                      java.lang.String signingAlg,
                      boolean includingCert,
                      boolean includingSignAttrib)
               throws SMIMEException
Adds signer to signed and enveloped S/MIME message.

Parameters:
pfxfileName - path and file name with certificate and private key corresponding to the sender of the message (file with .p12 or .pfx extension)
password - used to access to .pfx or .p12 file
signingAlg - algorithm used for signing (can be SHA1_WITH_RSA, MD2_WITH_RSA, MD5_WITH_RSA or SHA1_WITH_DSA).
includingCert - including/not including certificates to signed message
includingSignAttrib - including/not including signed attributes to signed message. Must be set to true in case of implicit signing
Throws:
SMIMEException - caused by non SMIMEException which can be one of the following: FileNotFoundException, NoSuchProviderException, KeyStoreException CertificateException, NoSuchAlgorithmException or IOException.

addSigner

public void addSigner(java.security.cert.X509Certificate[] chain,
                      java.security.PrivateKey privKey,
                      java.lang.String signingAlg,
                      boolean includingCert,
                      boolean includingSignAttrib)
Adds signer to signed and enveloped S/MIME message.

Parameters:
chain - certificate chain. First certificate in array must be owner's certificate, and last certificate has to be root certificate
privKey - private key corresponding to owner's certificate (DSA or RSA depend on type of signing)
signingAlg - algorithm used for signing (can be SHA1_WITH_RSA, MD2_WITH_RSA, MD5_WITH_RSA or SHA1_WITH_DSA).
includingCert - including/not including certificates to signed message
includingSignAttrib - including/not including signed attributes to signed message. Must be set to true in case of implicit signing.

addSigner

public void addSigner(java.security.KeyStore kStore,
                      java.lang.String password,
                      java.lang.String alias,
                      java.lang.String signingAlg,
                      boolean includingCert,
                      boolean includingSignAttrib)
               throws SMIMEException
Adds signer to signed and enveloped S/MIME message.

Parameters:
kStore - instance of KeyStore class which represents an in-memory collection of keys and certificates.
password - password used to access the corresponding private key, stored in given KeyStore object.
alias - alias name which corresponds to desired private key. If alias is given as null, then reading results are unpredictable.
signingAlg - algorithm used for signing (can be SHA1_WITH_RSA, MD2_WITH_RSA, MD5_WITH_RSA or SHA1_WITH_DSA).
includingCert - including/not including certificates to signed message
includingSignAttrib - including/not including signed attributes to signed message. Must be set to true in case of implicit signing.
Throws:
SMIMEException - caused by non SMIMEException which can be one of the following: KeyStoreException, UnrecoverableKeyException or NoSuchAlgorithmException.

addSigner

public void addSigner(java.lang.String ksPath,
                      java.lang.String ksType,
                      java.lang.String password,
                      java.lang.String alias,
                      java.lang.String signingAlg,
                      boolean includingCert,
                      boolean includingSignAttrib)
               throws SMIMEException
Adds signer to signed and enveloped S/MIME message.

Parameters:
ksPath - is path to the file representation of KeyStore which holds collection of keys and certificates. This file can be PKCS12 type (file with .p12 or .pfx extension) or can be key store of other types readable by 'BouncyCastle' or 'Sun' KeyStore implementation.
ksType - is type of KeyStore. It can be one of the following types: JKS for 'Sun' KeyStore, 'BKS', 'PKCS12' or 'UBER') for 'BouncyCastle' KeyStore. If ksType is given as null it will be assumed that PKCS12 type is in use, and alias parameter will be ignored, so this method becomes equivalent to addSigner() method which deal only with .pfx or .p12 files.
password - password used to access the corresponding private key, stored in given KeyStore file.
alias - alias name which corresponds to desired private key. If alias is given as null, then reading results are unpredictable.
signingAlg - algorithm used for signing (can be SHA1_WITH_RSA, MD2_WITH_RSA, MD5_WITH_RSA or SHA1_WITH_DSA).
includingCert - including/not including certificates to signed message
includingSignAttrib - including/not including signed attributes to signed message. Must be set to true in case of implicit signing.
Throws:
SMIMEException - if wrong path to KeyStore file ia given. Also, it can be caused by non SMIMEException which can be one of the following: FileNotFoundException, KeyStoreException, IOException, CertificateException or NoSuchAlgorithmException.

addCertificate

public void addCertificate(java.security.cert.X509Certificate cert)
Adds additional certificate to signed message.

Parameters:
cert - X509 certificate

reset

public void reset()
Resets all attributes in BaseSignedSMIMEObject to their initial values. The attributes have the same values as when simple construcor is invoked. It means that after this method call, MIME message object is set to null, and it has to be rebuild again.

Overrides:
reset in class BaseSMIMEObject

Enhydra-Oyster 2.1-7 API