com.entrust.toolkit.archive

Class PemInputStream

java.lang.Object

java.io.InputStream

java.io.FilterInputStream

com.entrust.toolkit.archive.PemInputStream

All Implemented Interfaces:

java.io.Closeable, java.lang.AutoCloseable

public class PemInputStream
extends java.io.FilterInputStream

This class reads data created by PemOutputStream. It will decrypt, verify, Base64 decode, and uncompresses the data, depending on what options were specified when the message was created.

The PEM format accepted by this class is not fully compatible with PEM protection as specified by RFC 1421. It is compatible with the PEM format output by Entrust's C++ toolkits, with the exception that it does not support the "minimal header" format.

Note: this class does not perform certificate validation when reading a message. This validation must be performed by callers.

Since:

7.0

See Also:

PemOutputStream

Field Summary

Fields inherited from class java.io.FilterInputStream

in

Constructor Summary

Constructors

Constructor and Description
PemInputStream(java.io.InputStream dataStream, boolean base64Encoded, java.io.InputStream headerStream, int headerLength) Constructor for PemInputStream.
PemInputStream(KeyAndCertificateSource keyAndCertificateSource, java.io.InputStream dataStream, boolean isBase64Encoded, java.io.InputStream headerStream, int headerLength) Constructor for PemInputStream.

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() This method closes the data stream, and verifies the message signature, if necessary.
PemParsedHeader	getHeader() Return the header parsed from the message.
java.security.SignatureException	getSignatureException() Return any exception that may have occurred when validating the signature.
boolean	isSignatureValid() Return whether or not the signature on the data is valid.
void	mark(int readlimit) Inherited from FilterInputStream.
boolean	markSupported() This method is inherited from FilterInputStream and always returns false.
int	read() Reads and unprotects the next byte of data from the data stream, returning the original plaintext value.
int	read(byte[] b, int off, int len) Reads and unprotects up to len bytes of data from this input stream into an array of bytes.
void	reset() reset() is not supported.
void	setDecryptionKey(java.security.PrivateKey decryptionKey, java.lang.String keyId) Set the decryption key and its key id to be used to decrypt the message.

Methods inherited from class java.io.FilterInputStream

read, skip

Methods inherited from class java.lang.Object

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

Constructor Detail

PemInputStream

public PemInputStream(KeyAndCertificateSource keyAndCertificateSource,
                      java.io.InputStream dataStream,
                      boolean isBase64Encoded,
                      java.io.InputStream headerStream,
                      int headerLength)

Constructor for PemInputStream. This constructor requires two input streams, one from which the message header is read, and one from which the data itself is read. Calls to read() return bytes from the data stream, not the header stream.

By using this constructor, the message decryption key is automatically obtained from the supplied key source.

Parameters:

keyAndCertificateSource - the object from which the private decryption key is to be obtained. In other words, it contains the private key of one of the message recipients.

dataStream - the stream from which the PEM-protected data is read

isBase64Encoded - a flag indicating whether or not the message is Base64 encoded

headerStream - the stream from which the PEM header is read. This can be the same stream as dataStream

headerLength - the number of bytes to read from headerStream.

PemInputStream

public PemInputStream(java.io.InputStream dataStream,
                      boolean base64Encoded,
                      java.io.InputStream headerStream,
                      int headerLength)

Constructor for PemInputStream. This constructor requires two input streams, one from which the message header is read, and one from which the data itself is read. Calls to read() return bytes from the data stream, not the header stream.

Parameters:

dataStream - the stream from which the PEM-protected data is read

base64Encoded - a flag indicating whether or not the message is Base64 encoded

headerStream - the stream from which the PEM header is read. This can be the same stream as dataStream

headerLength - the number of bytes to read from headerStream.

Method Detail

read

public int read()
         throws java.io.IOException

Reads and unprotects the next byte of data from the data stream, returning the original plaintext value. The value of the byte is returned as an int in the range 0 to 255. If no byte is available because the end of the stream has been reached, the value -1 is returned. This method blocks until input data is available, the end of the stream is detected, or an exception is thrown.

Overrides:

read in class java.io.FilterInputStream

Returns:

the next byte of unprotected data, or -1 if the end of the stream is reached.

Throws:

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

read

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

Reads and unprotects 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:

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

ArchiveException -

• if an error occurs calculating the signature.
• if there is no private key available with which to decrypt the message

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

close

public void close()
           throws java.io.IOException

This method closes the data stream, and verifies the message signature, if necessary. It does not close the header stream.

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 data stream.

mark

public void mark(int readlimit)

Inherited from FilterInputStream. Has no effect, as this stream does not support mark() or reset()

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

isSignatureValid

public boolean isSignatureValid()

Return whether or not the signature on the data is valid. The value returned is only meaningful for signed data streams, and then only after the close() method has been called. A return value of true after close() is called indicates that the validation succeeded.

false will always be returned for messages that were not signed.

Returns:

any exception that occurred when validating the signature.

getSignatureException

public java.security.SignatureException getSignatureException()

Return any exception that may have occurred when validating the signature. The value returned is only meaningful after the close() method has been called. A return value of null after close() is called indicates that the validation succeeded.

null will always be returned for messages that were not signed.

Returns:

any exception that occurred when validating the signature.

getHeader

public PemParsedHeader getHeader()
                          throws ArchiveException

Return the header parsed from the message.

Returns:

an object representing the parsed header.

Throws:

ArchiveException - if this call causes the header to be parsed, and there is a problem with the header.

See Also:

PemParsedHeader

setDecryptionKey

public void setDecryptionKey(java.security.PrivateKey decryptionKey,
                             java.lang.String keyId)

Set the decryption key and its key id to be used to decrypt the message. The key id should be one of the keys contained in the Map returned by getHeader().getRecipientKeyInfo()

If this object was constructed by passing in a User object, it is not necessary to call this method. If this object was constructed without a User object and the message was encrypted, this must be called before the first call to read() or there is no way to decrypt the message, and an exception will be thrown.

Parameters:

decryptionKey - the private key to be used to decrypt the message.

keyId - the key identifier for the decryption key.