IAIK High-Level API
version 1.1

iaik.hlapi
Class SMimeSignerEncrypter

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

IAIK High-Level API
version 1.1

Copyright © 2007, IAIK, Graz University of Technology
Copyright © 2007, Stiftung SIC