ArchiveInputStreamMac ("Entrust Authority Security Toolkit for the Java Platform")

java.lang.Object
- java.io.InputStream
- - java.io.FilterInputStream
  - - com.entrust.toolkit.archive.ArchiveInputStreamMac

All Implemented Interfaces:

java.io.Closeable, java.lang.AutoCloseable
```
public class ArchiveInputStreamMac
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
`ArchiveInputStreamMac(KeyAndCertificateSource keyAndCertificateSource, java.io.InputStream is)` Constructor for ArchiveInputStream.

Method Summary

All Methods Instance Methods Concrete Methods
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.
`ArchiveResultsMac`	`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.
`boolean`	`hasResourceFork()` Returns `true` if the archive has a resource fork in it.
`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.
`void`	`startResourceFork()` Tries to read the beginning tags for the resource fork and resets the booleans tracking that the header and file were read.

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
  - ArchiveInputStreamMac
```
public ArchiveInputStreamMac(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.
  - hasResourceFork
```
public boolean hasResourceFork()
```
    Returns true if the archive has a resource fork in it. This function can only be called once the data fork data has been read and a read() call returns -1. The startResourceFork() method can be used to access the resource fork. Once startResourceFork() is called, this method returns false.
    
    Returns:
    
    true if the archive has a resource fork in it. Returns false otherwise.
  - startResourceFork
```
public void startResourceFork()
                       throws java.io.IOException
```
    Tries to read the beginning tags for the resource fork and resets the booleans tracking that the header and file were read. This allow the reading of an additional [ENTRUST MAC RES FORK START] section. Use the various read() methods as would be used for a normal file.
    
    Throws:
    
    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.
    
    Also note that if a resource fork exists in the archive, it should be read before calling close(). If the resource fork is not read before calling close(), it's signature will not be verified. Legacy code may safely ignore the resource fork for backward compatibility.
    
    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 ArchiveResultsMac 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.

Class ArchiveInputStreamMac

Field Summary

Fields inherited from class java.io.FilterInputStream

Constructor Summary

Method Summary

Methods inherited from class java.io.FilterInputStream

Methods inherited from class java.lang.Object

Constructor Detail

ArchiveInputStreamMac

Method Detail

getIncludedFileName

getFileProtectionOptions

read

read

hasResourceFork

startResourceFork

close

mark

reset

markSupported

available

skip

getArchiveResults