IAIK High-Level API
version 1.1

iaik.hlapi
Class SignerEncrypter

java.lang.Object
  extended by iaik.hlapi.SignerEncrypter
Direct Known Subclasses:
CMSSignerEncrypter, SMimeSignerEncrypter, XMLSignerEncrypter

public abstract class SignerEncrypter
extends Object

Objects of this class sign and/or encrypt arbitrary data. They can process data given as a single byte array or data written to a stream.

Before the application can sign data, it has to provide the signing key using setSigningKey(KeyAndCertificate). After setting the signing key, the application can create several signatures without the need for setting the signature key again. The class will select a suitable signature algorithm automatically based on the type and size of the signing key.

If the application does not set a signing key, the data will not be signed.

The application may call addRecipient(X509Certificate) more than once if there are more recipients for the encrypted data. Calling process(byte[]) or process(OutputStream) does not clear the internal list of recipients. This means another call to any of these methods will encrypt the message for the same recipients as the call before. To clear the list of recipients call clearRecipients().

This class selects a suitable encryption algorithm automatically based on the key size and algorithm of the recipient keys. The selection prefers international standard algorithms and recommended key sizes. For recommendations, have a look at the information published in by the ECRYPT project in Yearly Report on Algorithms and Keysizes (2006). See also http://www.keylength.com.

If the application does not set a recipient certificate, the data will not be encrypted. If the application does not set a signing key nor a recipient certificate, the concrete implementation of this class may still encode the processed data, but it will not sign or encrypt it. At least, it must pass through the data as it is, if it cannot process it otherwise.

To sign and encrypt data, set the signing key and recipient certificates like this:

  SignerEncrypter signerEncrypter = new CMSSignerEncrypter();

  signerEncrypter.setSigningKey(signingKey);
  signerEncrypter.addRecipient(recipientCert);
 
To sign and encrypt a single block of data, use the object like this:
  byte[] data = ...
  byte[] result = signerEncrypter.process(data);
 

To sign all data written to a stream, use it like this:

  OutputStream out = ... // receives the signed and encrypted data
  byte[] data = ...
  OutputStream dataStream = signerEncrypter.process(out);
  dataStream.write(data);
  dataStream.close();
 


Method Summary
 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.
 byte[] process(byte[] data)
          Sign and/or encrypt the given block of data.
abstract  OutputStream process(OutputStream out)
          This method returns an OutputStream.
 void setSigningKey(KeyAndCertificate signingKey)
          Set the signing key.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Method Detail

setSigningKey

public void setSigningKey(KeyAndCertificate signingKey)
                   throws HlApiException
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.

Parameters:
signingKey - The signing key with the certificate chain.
Throws:
HlApiException - If handling the certificate fails.
Preconditions
(signingKey != null)

dropSigningKey

public void dropSigningKey()
Release all references to any previously set signing key.


addRecipient

public void addRecipient(X509Certificate recipientCert)
                  throws HlApiException
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 clearRecipients() to clear all recipients which have been added so far. An encryption operation does not clear this list.

Parameters:
recipientCert - The X.509 certificate of the recipient.
Throws:
HlApiException - If the certificate is invalid for encryption.
See Also:
clearRecipients()
Preconditions
(recipientCert != null)
Postconditions
(result != null)

clearRecipients

public void clearRecipients()
Clear the list of recipients.

See Also:
addRecipient(X509Certificate)

process

public byte[] process(byte[] data)
               throws HlApiException
Sign and/or encrypt the given block of data.

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

Parameters:
data - The complete data.
Returns:
The signed and/or encrypted data.
Throws:
HlApiException - If signing and/or encrypting fails.
Preconditions
(data != null)
Postconditions
(result != null)

process

public abstract OutputStream process(OutputStream out)
                              throws IOException,
                                     HlApiException
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 setSigningKey(KeyAndCertificate) to sign the data. To encrypt the data, it must have set one or more recipient certificates.

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.
Preconditions
(out != null)
Postconditions
(result != null)

IAIK High-Level API
version 1.1

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