com.entrust.toolkit.archive

Class ArchiveInputStream

java.lang.Object

java.io.InputStream

java.io.FilterInputStream

com.entrust.toolkit.archive.ArchiveInputStream

All Implemented Interfaces:

java.io.Closeable, java.lang.AutoCloseable

public class ArchiveInputStream
extends java.io.FilterInputStream

This class is used to read and unprotect messages in the Entrust Archive format. Such messages can be created by Entrust Entelligence, the Entrust C++ toolkits, or the ArchiveCreator class. The Entrust Archive format is a legacy format, and this class is provided for the purposes of extracting data contained within such files.

There are some important limitations to note about this class:

• The C++ toolkits and Entelligence can apply a timestamp to a protected file. This class does not verify timestamps, it just skips over them if they are there.
• The C++ toolkits and the Entrust/Client 3.0 could produce Archives containing multiple files. This class only supports Archives that contain a single file.
• It cannot read .ent files produced by any version of Entelligence for the Macintosh operating system.
• It cannot read .ent files produced by any version 1.x or 2.x Entrust software products.

This class generally behaves like a generic InputStream. The data returned is the original data that the given Archive protects. One important thing to note is that it does not throw exceptions if the signature fails to verify or the file protector's certificates are not valid. Once the close() method is called, it is important to examine the results of processing the Archive. These results are available by calling getArchiveResults()

Since:

7.0

Field Summary

Fields inherited from class java.io.FilterInputStream

in

Constructor Summary

Constructors

Constructor and Description
ArchiveInputStream(KeyAndCertificateSource keyAndCertificateSource, java.io.InputStream is) Constructor for ArchiveInputStream.

Method Summary

Modifier and Type	Method and Description
int	available() Returns 1 if at least one byte can be read from this input stream without blocking.
void	close() Close the input stream.
ArchiveResults	getArchiveResults() Returns the results of processing an Entrust Archive.
PemOptions	getFileProtectionOptions() Returns the options used when protecting the Archive.
java.lang.String	getIncludedFileName() Returns a String containing the name of the file that is protected by the Archive.
void	mark(int readlimit) This stream class does not support mark/reset, this method does nothing
boolean	markSupported() This method is inherited from FilterInputStream and always returns false.
int	read() Reads and unprotects a byte from the underlying stream.
int	read(byte[] b, int off, int len) Reads up to len bytes of data from this input stream into an array of bytes.
void	reset() reset() is not supported.
long	skip(long n) Does nothing.

Methods inherited from class java.io.FilterInputStream

read

Methods inherited from class java.lang.Object

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

Constructor Detail

ArchiveInputStream

public ArchiveInputStream(KeyAndCertificateSource keyAndCertificateSource,
                          java.io.InputStream is)

Constructor for ArchiveInputStream. Accepts a key and certificate source whose keys will be used to unprotect and verify the Archive, and an InputStream from which the Archive is read.

If the Archive was encrypted, the keyAndCertificateSource must contain a private key for which the Archive was encrypted.

Parameters:

keyAndCertificateSource - The source of decryption keys to unprotect the Archive, and a CertVerifier to validate certificates.

is - The InputStream from which the Archive is read. This stream will be closed once the Archive has been read from it.

Method Detail

getIncludedFileName

public java.lang.String getIncludedFileName()
                                     throws java.io.IOException,
                                            ArchiveException

Returns a String containing the name of the file that is protected by the Archive. Depending on the creating application, this may be an absolute path, a relative path, or just the file name itself.

If the reading of the Archive has not yet begun, this causes the Archive's header information to be read, which may result in an IOException.

Returns:

the name of the file protected by this Archive.

Throws:

ArchiveException - if the header read from the Stream is not a valid header for an Entrust Archive.

java.io.IOException - if an error occurs reading the Archive header from the stream.

getFileProtectionOptions

public PemOptions getFileProtectionOptions()
                                    throws java.io.IOException,
                                           ArchiveException

Returns the options used when protecting the Archive.

If the reading of the Archive has not yet begun, this causes the Archive's header information to be read, which may result in an IOException.

Returns:

the options used when protecting the Archive

Throws:

ArchiveException - if the header read from the Stream is not a valid header for an Entrust Archive.

java.io.IOException - if an error occurs reading the Archive header from the stream

read

public int read(byte[] b,
                int off,
                int len)
         throws java.io.IOException

Reads up to len bytes of data from this input stream into an array of bytes. This method blocks until some input is available.

Overrides:

read in class java.io.FilterInputStream

Parameters:

b - the buffer into which the data is read.

off - the start offset of the data.

len - the maximum number of bytes read.

Returns:

the total number of bytes read into the buffer, or -1 if there is no more data because the end of the stream has been reached.

Throws:

ArchiveException - if the Archive header is corrupt, or if the end of stream is reached before all of the data is read from the Archive.

java.io.IOException - if an I/O error occurs.

read

public int read()
         throws java.io.IOException

Reads and unprotects a byte from the underlying stream. This method blocks until some input is available.

Overrides:

read in class java.io.FilterInputStream

Returns:

the byte read as an integer from 0 to 255, or -1 if there is no more data because the end of the stream has been reached.

Throws:

ArchiveException - if the Archive header is corrupt, or if the end of stream is reached before all of the data is read from the Archive.

java.io.IOException - if an I/O error occurs.

close

public void close()
           throws java.io.IOException

Close the input stream. Causes the signature to be verified, and the certificates of the Archive creator to be validated. This method does not throw exceptions if the signature or certificates are not valid.

Note that the signature validation is performed on the bytes that have been read from the stream so far, so if not all the bytes have been read the signature validation will fail.

Specified by:

close in interface java.io.Closeable

Specified by:

close in interface java.lang.AutoCloseable

Overrides:

close in class java.io.FilterInputStream

Throws:

java.io.IOException - if an I/O error occurs closing the stream.

mark

public void mark(int readlimit)

This stream class does not support mark/reset, this method does nothing

Overrides:

mark in class java.io.FilterInputStream

Parameters:

readlimit - ignored

reset

public void reset()
           throws java.io.IOException

reset() is not supported. This method always throws an IOException.

Overrides:

reset in class java.io.FilterInputStream

Throws:

java.io.IOException - always

markSupported

public boolean markSupported()

This method is inherited from FilterInputStream and always returns false.

Overrides:

markSupported in class java.io.FilterInputStream

Returns:

false

available

public int available()
              throws java.io.IOException

Returns 1 if at least one byte can be read from this input stream without blocking.

Overrides:

available in class java.io.FilterInputStream

Returns:

1 if at least one byte can be read from this input stream without blocking. Returns 0 otherwise.

Throws:

java.io.IOException - if an I/O error occurs

skip

public long skip(long n)

Does nothing. Callers must manually skip over bytes.

Overrides:

skip in class java.io.FilterInputStream

Parameters:

n - ignored.

Returns:

0

getArchiveResults

public ArchiveResults getArchiveResults()
                                 throws ArchiveException

Returns the results of processing an Entrust Archive. These results should always be examined by the application reading from the stream to determine the validity of the data.

This method should only be called after close() has been called, calling before will cause an exception to be thrown.

Returns:

The results of processing the archive.

Throws:

ArchiveException - if close() has not yet been called.