com.entrust.toolkit.archive

Class PemOutputStream

java.lang.Object

java.io.OutputStream

java.io.FilterOutputStream

com.entrust.toolkit.archive.PemOutputStream

All Implemented Interfaces:

java.io.Closeable, java.io.Flushable, java.lang.AutoCloseable

public class PemOutputStream
extends java.io.FilterOutputStream

This class writes data to a stream, in a format that is based on, but not compliant to, the PEM standard of RFC1421. The data output is compatible with the PEM format used by the Entrust C++ toolkits, and is used as the basis of the Entrust Archive format.

To be able to actually the stream the data being protected, this class requires two output streams, one to write the protected data to, and another to write the message header to.

Since:

7.0

Field Summary

Fields inherited from class java.io.FilterOutputStream

out

Constructor Summary

Constructors

Constructor and Description
PemOutputStream(java.security.PrivateKey signingKey, X509Certificate verificationCertificate, X509Certificate originatorCertificate, PemOptions options, java.io.OutputStream outStream, java.io.OutputStream headerStream) Creates a PEM message, signed with the given signing key, with the given certificates used as those of the originator.
PemOutputStream(User user, PemOptions options, java.io.OutputStream outStream) Create a PemOutputStream that does not write the header.
PemOutputStream(User user, PemOptions options, java.io.OutputStream outStream, java.io.OutputStream headerStream) Create a PemOutputStream that writes the protected data and header to separate streams.

Method Summary

Modifier and Type	Method and Description
void	addRecipients(X509Certificate[] recipients) Adds the certificates in the given array as message recipients.
void	close() Creates the message signature if applicable, and writes the header to the header stream.
int	countCRLFBytesWrittenDuringBase64Encoding() Returns the number of CRLF bytes (carriage return '\r' and line feed '\n') that were written to the underlying output stream during Base64 encoding of the protected data.
PemHeader	getHeader() Returns the PEM header.
void	useOAEP(boolean useOAEP) Indicate whether or not OAEP padding should be used when encrypting the message.
void	write(byte[] b, int off, int len) Writes len bytes from the specified byte array starting at offset off to this output stream.
void	write(int b) Writes the specified byte to this output stream.

Methods inherited from class java.io.FilterOutputStream

flush, write

Methods inherited from class java.lang.Object

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

Constructor Detail

PemOutputStream

public PemOutputStream(User user,
                       PemOptions options,
                       java.io.OutputStream outStream,
                       java.io.OutputStream headerStream)
                throws ArchiveException,
                       UserNotLoggedInException

Create a PemOutputStream that writes the protected data and header to separate streams.

Parameters:

user - the user that will encrypt and/or sign the message

options - the message protection options

outStream - the stream to write the protected data to

headerStream - the stream to write the PEM header to. This should be different from outStream

Throws:

UserNotLoggedInException - if the supplied user is not logged in

ArchiveException - if the parameters are incorrect, or there is an error initializing the encryption or signing operation.

PemOutputStream

public PemOutputStream(User user,
                       PemOptions options,
                       java.io.OutputStream outStream)
                throws ArchiveException,
                       UserNotLoggedInException

Create a PemOutputStream that does not write the header. The header can be retrieved after message processing with getHeader()

Parameters:

user - the user that will encrypt and/or sign the message

options - the message protection options

outStream - the stream to write the protected data to

Throws:

UserNotLoggedInException - if the supplied user is not logged in

ArchiveException - if the parameters are incorrect, or there is an error initializing the encryption or signing operation.

PemOutputStream

public PemOutputStream(java.security.PrivateKey signingKey,
                       X509Certificate verificationCertificate,
                       X509Certificate originatorCertificate,
                       PemOptions options,
                       java.io.OutputStream outStream,
                       java.io.OutputStream headerStream)
                throws ArchiveException

Creates a PEM message, signed with the given signing key, with the given certificates used as those of the originator.

Parameters:

signingKey - the private key to be used to sign the message. Set to null if the message is not signed.

verificationCertificate - the verification certificate corresponding to signingKey. Set to null if the message is not signed.

originatorCertificate - the encryption certificate of the message encryptor. Set to null if the message is not encrypted.

options - the message protection options

outStream - the stream to write the protected data to

headerStream - the stream to write the PEM header to. This should be different from outStream

Throws:

ArchiveException - if the parameters are incorrect, or there is an error initializing the encryption or signing operation.

Method Detail

write

public void write(int b)
           throws java.io.IOException

Writes the specified byte to this output stream.

Overrides:

write in class java.io.FilterOutputStream

Parameters:

b - the byte to write.

Throws:

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

write

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

Writes len bytes from the specified byte array starting at offset off to this output stream.

Overrides:

write in class java.io.FilterOutputStream

Parameters:

b - the data.

off - the start offset in the data.

len - the number of bytes to write.

Throws:

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

close

public void close()
           throws java.io.IOException

Creates the message signature if applicable, and writes the header to the header stream. Closes the underlying output stream.

Specified by:

close in interface java.io.Closeable

Specified by:

close in interface java.lang.AutoCloseable

Overrides:

close in class java.io.FilterOutputStream

Throws:

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

addRecipients

public void addRecipients(X509Certificate[] recipients)

Adds the certificates in the given array as message recipients. Encrypted messages will be encrypted for all the given recipients.

The certificates are checked to make sure the key usage is appropriate for encryption, but other than that no validity checks are performed. Certificates that are not appropriate for encryption are ignored.

Parameters:

recipients - the recipients to encrypt the message for

getHeader

public PemHeader getHeader()

Returns the PEM header. For signed messages, this method should not be called until after close(), or the signature value will not be correct.

Returns:

the message header.

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

countCRLFBytesWrittenDuringBase64Encoding

public int countCRLFBytesWrittenDuringBase64Encoding()

Returns the number of CRLF bytes (carriage return '\r' and line feed '\n') that were written to the underlying output stream during Base64 encoding of the protected data.

This only applys when the data is being Base64 encoded; when Base64 encoding is not used, this API returns 0.

For example, if one CRLF was written, this API will return 2 (each CRLF consists of two bytes). The CRLF byte count is required during Entrust Archive file creation; the Archive format contains a component representing the total content bytes excluding and CRLF bytes.

Returns:

the number of CRLF bytes that were written to the underlying output stream during Base64 encoding of the protected data