iaik.hlapi
Class SMimeSignerEncrypter

java.lang.Object
  iaik.hlapi.SignerEncrypter
      iaik.hlapi.SMimeSignerEncrypter

public class SMimeSignerEncrypter
extends SignerEncrypter

This SignerEncrypter implementation creates S/MIME messages according to RFC 3851. It creates application/pkcs7-mime signed data and enveloped data.

It takes the e-mail address of the signing certificate automatically and adds a FROM header field. It does the same with added recipient certificates. Also, it adds the signing time and the certificate chain to the signature. Moreover, it selects a signature algorithm automatically depending on the given signature key. If the given key is a RSA key, it will select a suitable hash algorithm depending on the key length.

It selects a content encryption algorithm automatically depending on the given recipient key. Typically, it will select Triple DES or AES.

The default content type is application/octet-stream and the default char set is us-ascii. This class applies a base64 content transfer encoding.

If the application does not set a signing key nor a recipient certificate, the output will be unsigned and unencrypted, but it will still be an e-mail message.

Constructor Summary

SMimeSignerEncrypter()
Construct a new object for signing and/or encrypting data.

Method Summary

void	addRecipient(String address) Add a recipient e-mail address to the list of recipients.
void	addRecipient(X509Certificate recipientCert) Add one recipient of the encrypted data.
void	clearRecipients() Clear the list of recipients.
void	dropSigningKey() Release all references to any previously set signing key.
OutputStream	process(OutputStream out) This method returns an OutputStream.
void	setCharacterSet(String charset) Set the character encoding (charset parameter) of the content.
void	setContentType(String contentType) Set the content type for the signed MIME entity (i.e. the content data), e.g. text/plain.
void	setFrom(String address) Set the sender e-mail address as a RFC 822 address string.
void	setHeaders(Map headers) Set custom header fields using name and value.
void	setSigningKey(KeyAndCertificate signingKey) Set the signing key.
void	setSubject(String subject) Set the subject string that should be used as subject of the e-mail.

Methods inherited from class iaik.hlapi.SignerEncrypter

process

Methods inherited from class java.lang.Object

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

Constructor Detail

SMimeSignerEncrypter

public SMimeSignerEncrypter()

Construct a new object for signing and/or encrypting data.

Method Detail

setSigningKey

public void setSigningKey(KeyAndCertificate signingKey)
                   throws HlApiException

Description copied from class: SignerEncrypter

Set the signing key. The certificate chain should also be set. All certificates of the given chain will be included in the signature. To include one certificate only, simply provide a certificate chain of with only that certificate.

Overrides:

setSigningKey in class SignerEncrypter

Parameters:

signingKey - The signing key with the certificate chain.

Throws:

HlApiException - If handling the certificate fails.

dropSigningKey

public void dropSigningKey()

Description copied from class: SignerEncrypter

Release all references to any previously set signing key.

Overrides:

dropSigningKey in class SignerEncrypter

addRecipient

public void addRecipient(X509Certificate recipientCert)
                  throws HlApiException

Description copied from class: SignerEncrypter

Add one recipient of the encrypted data.

The certificate must contain a public key which is applicable for encryption (key wrapping to be more precise). The implementation may also require that the certificate has the required key-usage bits set.

Call SignerEncrypter.clearRecipients() to clear all recipients which have been added so far. An encryption operation does not clear this list.

Overrides:

addRecipient in class SignerEncrypter

Parameters:

recipientCert - The X.509 certificate of the recipient.

Throws:

HlApiException - If the certificate is invalid for encryption.

See Also:

SignerEncrypter.clearRecipients()

clearRecipients

public void clearRecipients()

Clear the list of recipients.

Overrides:

clearRecipients in class SignerEncrypter

See Also:

SignerEncrypter.addRecipient(X509Certificate)

process

public OutputStream process(OutputStream out)
                     throws IOException,
                            HlApiException

Description copied from class: SignerEncrypter

This method returns an OutputStream. The application can write to this stream all data that it wants to sign and/or encrypt. The application finishes writing data by closing the stream. The method will write the signed and/or encrypted data to out.

Note that the application must set a signing key in advance using SignerEncrypter.setSigningKey(KeyAndCertificate) to sign the data. To encrypt the data, it must have set one or more recipient certificates.

Specified by:

process in class SignerEncrypter

Parameters:

out - The stream which receives the signed and/or encrypted data.

Returns:

The OutputStream to which the application writes the data to be signed and/or encrypted.

Throws:

IOException - If writing to the given stream fails.

HlApiException - If signing fails.

addRecipient

public void addRecipient(String address)

Add a recipient e-mail address to the list of recipients. It is recommended that this string contains only ASCII characters.

Note that addRecipient(X509Certificate) adds the recipient address string in the certificate automatically.

Parameters:

address - The RFC 822 email address string.

Preconditions

(address != null)

setFrom

public void setFrom(String address)

Set the sender e-mail address as a RFC 822 address string.

Please note that calling setSigningKey(KeyAndCertificate) sets the sender e-mail address automatically. Calling this method in addition is only required, if the application wants to use a different address string than that which is inside the signer certificate.

Parameters:

address - The sender's e-mail address.

Preconditions

(address != null)

setSubject

public void setSubject(String subject)

Set the subject string that should be used as subject of the e-mail. It is recommended that this string contains only ASCII characters.

Parameters:

subject - The subject string.

Preconditions

(subject != null)

setContentType

public void setContentType(String contentType)

Set the content type for the signed MIME entity (i.e. the content data), e.g. text/plain. Omit any parameters like charset. Use setCharacterSet(String) instead.

Parameters:

contentType - The content type.

Preconditions

(contentType != null)

setCharacterSet

public void setCharacterSet(String charset)

Set the character encoding (charset parameter) of the content. When this class is used to sign text, it takes this encoding into account automatically.

Parameters:

charset - The character set.

Preconditions

(charset != null)

setHeaders

public void setHeaders(Map headers)

Set custom header fields using name and value. These headers will be written into the resulting e-mail message in the iteration order of the provided map. The application can use a LinkedHashMap if the order is important. The specified headers are written out before this object may write additional headers like FROM, TO or SUBJECT.

It writes the entries in this format:
key ':' SPACE value CRLF

If this map contains header fields which can be set by other methods of this class, the values in this table have higher priority. For example, if this table contains a DATE entry, this class will not write another header field with the current date.

Parameters:

headers - The header fields. Set to null to set no custom headers.