com.entrust.toolkit.archive

Class ArchiveCreator

java.lang.Object

com.entrust.toolkit.archive.ArchiveCreator

public class ArchiveCreator
extends java.lang.Object

This class is used to create messages in the Entrust Archive format. The Entrust Archive format can only be used for files located on disk, it cannot be used to encrypt or sign data from an arbitrary location.

Due to the format of an Entrust Archive, it is not possible to stream them during creation. This means that all the data in the file must be buffered internally, making this format not well suited for encrypting or signing large files.

Use of this class is not recommended. The Entrust Archive format is a proprietary format used by older Entrust products, and is not interoperable. PKCS7 or SMIME should be used instead for interoperability purposes.

Since:

7.0

See Also:

ArchiveInputStream

Constructor Summary

Constructors

Constructor and Description
ArchiveCreator(User user, java.io.File toProtect, PemOptions pemOptions, LargeFileOptions largeFileOptions, java.io.OutputStream outStream) This constructor provides support for protection of large files (larger than available memory) with Entrust Archive format.
ArchiveCreator(User user, java.io.File toProtect, PemOptions options, java.io.OutputStream outStream) This constructor only supports protection of small files (smaller than available memory) with Entrust Archive format.

Method Summary

Modifier and Type	Method and Description
void	abort() Abort the operation of protecting data.
X509Certificate[]	addRecipients(X509Certificate[] recipients) Adds each certificate in the given array as a message recipient.
void	addTrustedRecipients(X509Certificate[] recipients) Adds each certificate in the given array as a message recipient.
int	process() This method should be called repeatedly to read data from the input file, and protect the data.
void	useOAEP(boolean useOAEP) Indicate whether or not OAEP padding should be used when encrypting the message.

Methods inherited from class java.lang.Object

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

Constructor Detail

ArchiveCreator

public ArchiveCreator(User user,
                      java.io.File toProtect,
                      PemOptions options,
                      java.io.OutputStream outStream)
               throws ArchiveException,
                      UserNotLoggedInException,
                      java.io.FileNotFoundException

This constructor only supports protection of small files (smaller than available memory) with Entrust Archive format.

During archive creation, all data will be buffered to memory. When used with large files, an OutOfMemoryError can occur.

Parameters:

user - The user creating the Archive

toProtect - The File to protect

options - The options used to protect the file.

outStream - A stream to write the protected file to. This stream will be closed once processing is finished.

Throws:

UserNotLoggedInException - if the given user is not logged in.

ArchiveException - if the given parameters are not valid, or there is an error initializing the cryptographic operations.

java.io.FileNotFoundException - if the file to protect cannot be found

ArchiveCreator

public ArchiveCreator(User user,
                      java.io.File toProtect,
                      PemOptions pemOptions,
                      LargeFileOptions largeFileOptions,
                      java.io.OutputStream outStream)
               throws ArchiveException,
                      UserNotLoggedInException,
                      java.io.FileNotFoundException

This constructor provides support for protection of large files (larger than available memory) with Entrust Archive format.

During archive creation, all data will be buffered to a combination of memory and temporary files. For details on large file support, refer to LargeFileOptions.

Parameters:

user - The user creating the Archive

toProtect - The File to protect

pemOptions - PEM related options used to protect the file

largeFileOptions - options related to the protection of large files

outStream - A stream to write the protected file to. This stream will be closed once processing is finished.

Throws:

UserNotLoggedInException - if the given user is not logged in.

ArchiveException - if the given parameters are not valid, or there is an error initializing the cryptographic operations.

java.io.FileNotFoundException - if the file to protect cannot be found

Since:

7.1 Patch

Method Detail

addRecipients

public X509Certificate[] addRecipients(X509Certificate[] recipients)

Adds each certificate in the given array as a message recipient. That is, the data is encrypted for each certificate in the array.

For each certificate, this method makes sure the key usage is appropriate for encryption, and that the certificate is valid. It does not ensure the uniqueness of recipients.

Parameters:

recipients - the encryption certificates of the intended message recipients

Returns:

an array containing the certificates that were not acceptable recipients

addTrustedRecipients

public void addTrustedRecipients(X509Certificate[] recipients)
                          throws ArchiveException

Adds each certificate in the given array as a message recipient. That is, the data is encrypted for each certificate in the array.

This method does not validate certificates, only that the key usage is appropriate for encryption. It does not ensure the uniqueness of recipients. Certificates that are not appropriate for encryption are ignored.

Parameters:

recipients - the encryption certificates of the intended message recipients

Throws:

ArchiveException - if the user is not allowed to trust arbitrary certificates. This is equivalent to saying the user is not permitted to use a personal address book.

See Also:

ClientSettings.getPermitPAB()

useOAEP

public void useOAEP(boolean useOAEP)

Indicate whether or not OAEP padding should be used when encrypting the message. Note that older software, and many PKCS11 devices, cannot process OAEP padding.

Parameters:

useOAEP - whether or not OAEP padding should be used

process

public int process()
            throws java.io.IOException,
                   ArchiveException

This method should be called repeatedly to read data from the input file, and protect the data. It should be called until it returns -1. After it returns -1, the OutputStream where the Archive was being written to is closed.

Returns:

a positive integer if there is still data to process, -1 if all the data has been processed.

Throws:

java.io.IOException - if an error occurs reading from the file being protected, or writing to the output stream.

ArchiveException - if the processing was aborted by abort(), or if any other error, such as signature calculation, occurs.

abort

public void abort()

Abort the operation of protecting data. Closes all streams, and prevents further processing of the data.