com.entrust.toolkit

Class PKCS7EncodeStream

java.lang.Object

java.io.OutputStream

java.io.FilterOutputStream

com.entrust.toolkit.PKCS7EncodeStream

All Implemented Interfaces:

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

public class PKCS7EncodeStream
extends java.io.FilterOutputStream

The PKCS7EncodeStream class performs data encryption and signing operations according to the PKCS#7 standard.

Use PKCS7DecodeStream to read data written with PKCS7EncodeStream.

Note

This class does not handle large amounts of data by default. If you are encoding large files, use the setBlockSize method to specify a non-zero block size in bytes.

Once you have started writing to the stream, you cannot change the stream's properties.

This class is not thread safe.

See Also:

PKCS7DecodeStream, PKCS #7: Cryptographic Message Syntax Version 1.5 (RFC 2315)

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
class	PKCS7EncodeStream.ConsumerInputStream Represents the buffer of a producer/consumer scheme as an input stream from which the consumer reads.

Field Summary

Fields

Modifier and Type	Field and Description
static int	CLEAR_SIGN Indicator for clear signing data; signing without including the data in the structure.
static int	ENCRYPT_ONLY Indicator for encrypting data without signing it.
static int	EXPORT_CERTIFICATES Indicator for exporting certificates (data cannot be written).
static int	SIGN_AND_ENCRYPT Indicator for signing and encrypting data.
static int	SIGN_ONLY Indicator for signing data without encrypting it.

Fields inherited from class java.io.FilterOutputStream

out

Constructor Summary

Constructors

Constructor and Description
PKCS7EncodeStream(KeyAndCertificateSource keyAndCertSource, java.io.OutputStream out, int operation) Creates a new PKCS7EncodeStream object to encrypt and/or sign data.
PKCS7EncodeStream(KeyAndCertificateSource keyAndCertSource, java.io.OutputStream out, java.io.OutputStream signature) Creates a new PKCS7EncodeStream to clear sign data.
PKCS7EncodeStream(User user, java.io.OutputStream out, int operation) Creates a new PKCS7EncodeStream object to encrypt and/or sign data.
PKCS7EncodeStream(User user, java.io.OutputStream out, java.io.OutputStream signature) Creates a new PKCS7EncodeStream to clear sign data.

Method Summary

Methods

Modifier and Type	Method and Description
void	close() Closes this output stream and releases any system resources associated with the stream.
void	flush() Flushes this output stream forcing any buffered output bytes to be written to the stream.
Attribute[]	getAuthenticatedAttributes() This method returns the set of authenticated attributes in the PKCS7 Message.
byte[]	getDigest() Returns the digest that was calculated over the data during a signing operation.
AlgorithmID	getDigestAlgorithm() Returns the message digest algorithm used to sign the data.
AlgorithmID	getEncryptionAlgorithm() Returns the algorithm used to encrypt the data during the PKCS7 encode operation.
CertificateSet	getIncludedCertificates() Returns the certificates that are to be included in the PKCS#7 message.
int	getOperation() Returns the security operation that is to be performed on the data written to this stream.
CertificateSet	getRecipients() Returns the set of certificates for the public keys used to encrypt the data.
void	requestTimeStamp(TimeStampClient timeStampClient) Requests that the signature be time-stamped.
void	setAuthenticatedAttributes(Attribute[] attributes) This method sets additional authenticated attributes to be included in this PKCS7 Message.
void	setBlockSize(int blockSize) Sets the size of the data parts in the underlying ASN.1 structure.
void	setDigestAlgorithm(AlgorithmID digest) Specifies the message digest algorithm to use for signing the data.
void	setEncryptionAlgorithm(AlgorithmID encryptionAlg) Specifies the encryption algorithm to be used during an PKCS7 encode operation that involves data being encrypted.
void	setEncryptionAlgorithm(AlgorithmID encryptionAlg, int keyLength) Specifies the encryption algorithm and encryption key length to be used during an PKCS7 encode operation that involves data being encrypted.
CertificateSet	setIncludedCertificates(CertificateSet certs) Specifies the certificates that are included in the PKCS#7 message.
void	setOAEPParams(java.security.spec.AlgorithmParameterSpec params) Sets Optimal Asymmetric Encryption Padding (OAEP) parameters.
CertificateSet	setRecipients(CertificateSet recipients) Specifies the public keys with which to encrypt the message.
void	setTrustedRecipients(CertificateSet recipients) Specifies the validated public keys with which to encrypt the message.
void	write(byte[] b) Signs and encrypts, or just encrypts, b.length bytes and writes them to the output stream.
void	write(byte[] b, int off, int len) Signs and encrypts, or just encrypts, len bytes from the specified byte array.
void	write(int b) Signs and encrypts, or just encrypts, the specified byte and writes it to the output stream.

Methods inherited from class java.lang.Object

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

Field Detail

SIGN_AND_ENCRYPT

public static final int SIGN_AND_ENCRYPT

Indicator for signing and encrypting data.

See Also:

Constant Field Values

ENCRYPT_ONLY

public static final int ENCRYPT_ONLY

Indicator for encrypting data without signing it.

See Also:

Constant Field Values

SIGN_ONLY

public static final int SIGN_ONLY

Indicator for signing data without encrypting it.

See Also:

Constant Field Values

EXPORT_CERTIFICATES

public static final int EXPORT_CERTIFICATES

Indicator for exporting certificates (data cannot be written).

See Also:

Constant Field Values

CLEAR_SIGN

public static final int CLEAR_SIGN

Indicator for clear signing data; signing without including the data in the structure.

See Also:

Constant Field Values

Constructor Detail

PKCS7EncodeStream

public PKCS7EncodeStream(User user,
                 java.io.OutputStream out,
                 int operation)
                  throws InvalidUserException,
                         java.lang.IllegalArgumentException,
                         java.lang.NullPointerException

Creates a new PKCS7EncodeStream object to encrypt and/or sign data.

The PKCS7EncodeStream object encrypts and/or signs data as it writes it to the underlying output stream. The User must be logged in before the application makes the call to this constructor.

To clear sign data and to write the signed data to an output stream, use PKCS7EncodeStream(User, OutputStream, OutputStream).

Note that this constructor uses the default signing and encryption keys from user. If user has extra key pairs beyond the default that need to be used, use PKCS7EncodeStream(KeyAndCertificateSource,OutputStream,int) and set the keys to be used in the KeyAndCertificateSource object.

Parameters:

user - the User object for which the data is to be signed and/or encrypted. If the data is signed, it is signed with the user's signing certificate.

out - the underlying output stream to which the PKCS7 encoded data is written.

operation - the operation to perform. Use one of:

• SIGN_AND_ENCRYPT = 1
• ENCRYPT_ONLY = 2
• SIGN_ONLY = 3
• EXPORT_CERTIFICATES = 4
• CLEAR_SIGN = 5

Throws:

java.lang.NullPointerException - thrown if user or data is null

java.lang.IllegalArgumentException - thrown if operation is a value other than one of the values listed above.

InvalidUserException - thrown if the user is not logged on

PKCS7EncodeStream

public PKCS7EncodeStream(KeyAndCertificateSource keyAndCertSource,
                 java.io.OutputStream out,
                 int operation)
                  throws java.lang.IllegalArgumentException,
                         java.lang.NullPointerException

Creates a new PKCS7EncodeStream object to encrypt and/or sign data.

To clear sign data and to write the signed data to an output stream, use PKCS7EncodeStream(User, OutputStream, OutputStream).

Parameters:

keyAndCertSource - the KeyAndCertSource object that supplies certificates and private keys. If the data is to be signed, the signing information must be set in this object. If the data is to be encrypted, the encryption information must be set.

out - the underlying output stream to which the PKCS7 encoded data is written.

operation - the operation to perform. Use one of:

• SIGN_AND_ENCRYPT = 1
• ENCRYPT_ONLY = 2
• SIGN_ONLY = 3
• EXPORT_CERTIFICATES = 4
• CLEAR_SIGN = 5

Throws:

java.lang.NullPointerException - thrown if keyAndCertSource or data is null

java.lang.IllegalArgumentException - thrown if operation is a value other than one of the values listed above, or if necessary key material is not provided in keyAndCertSource.

Since:

7.0

PKCS7EncodeStream

public PKCS7EncodeStream(User user,
                 java.io.OutputStream out,
                 java.io.OutputStream signature)
                  throws InvalidUserException,
                         java.lang.NullPointerException,
                         java.lang.IllegalArgumentException

Creates a new PKCS7EncodeStream to clear sign data.

The PKCS7EncodeStream object clear signs data while writing the data to the underlying output stream. The user must be logged in before the application calls this constructor.

Note that this constructor uses the default signing keys from user. If user has extra signing key pairs beyond the default that need to be used, use PKCS7EncodeStream(KeyAndCertificateSource,OutputStream,OutputStream) and set the keys to be used in the KeyAndCertificateSource object.

To use other PKCS #7 operations or to export certificates, use PKCS7EncodeStream(User, OutputStream, int).

Parameters:

user - the User object for which the data is to be clear signed. If the data is signed, they are signed with this user's signing certificate.

out - the underlying output stream to which the data is written. When out is null, the constructor call is equivalent to PKCS7EncodeStream(User, OutputStream, PKCS7EncodeStream.CLEAR_SIGN).

signature - the stream to which the signature is written

Throws:

InvalidUserException - thrown if the user is not logged on

java.lang.NullPointerException - thrown if user or signature is null

java.lang.IllegalArgumentException - If user does not have a signing key.

PKCS7EncodeStream

public PKCS7EncodeStream(KeyAndCertificateSource keyAndCertSource,
                 java.io.OutputStream out,
                 java.io.OutputStream signature)
                  throws java.lang.NullPointerException,
                         java.lang.IllegalArgumentException

Creates a new PKCS7EncodeStream to clear sign data.

The PKCS7EncodeStream object clear signs data while writing the data to the underlying output stream.

To use other PKCS #7 operations or to export certificates, use PKCS7EncodeStream(User, OutputStream, int).

Parameters:

keyAndCertSource - the KeyAndCertSource object that supplies the signing private keys and verification certificate.

out - the underlying output stream to which the data is written. When out is null, the constructor call is equivalent to PKCS7EncodeStream(User, OutputStream, PKCS7EncodeStream.CLEAR_SIGN).

signature - the stream to which the signature is written

Throws:

java.lang.NullPointerException - thrown if keyAndCertSource or signature is null

java.lang.IllegalArgumentException - If keyAndCertSource does not contain a signing key.

Since:

7.0

Method Detail

getOperation

public int getOperation()

Returns the security operation that is to be performed on the data written to this stream.

getOperation() returns one of the following security constants:

• SIGN_AND_ENCRYPT
• ENCRYPT_ONLY
• SIGN_ONLY
• EXPORT_CERTIFICATES
• CLEAR_SIGN

Returns:

the security operation performed on the data

setBlockSize

public void setBlockSize(int blockSize)
                  throws PropertyChangeException

Sets the size of the data parts in the underlying ASN.1 structure.

If blockSize is set to a value below 1 byte, all the data is written in one block. The default block size is 0 bytes.

Note

If you are encoding large files, specify a non-zero block size.

If you write all the data in one block, the data has to fit completely in memory. It is written to the underlying stream only when this stream is closed.

Parameters:

blockSize - the size of the individual blocks (in bytes) within the constructed octet string of the PKCS#7 data

Throws:

PropertyChangeException - thrown if the block size is changed to less than 1 after data has been written to the underlying stream

setOAEPParams

public void setOAEPParams(java.security.spec.AlgorithmParameterSpec params)
                   throws java.security.spec.InvalidParameterSpecException

Sets Optimal Asymmetric Encryption Padding (OAEP) parameters.

The method tells the encoding stream to use RSA-ES-OAEP as the padding scheme for encrypting the symmetric key. For more information on the RSA-ES-OAEP padding scheme, see PKCS#1 v2.0.

This method must be called before any data is written to the stream, otherwise it will be ignored.

Parameters:

params - the cryptographic parameters

Throws:

java.security.spec.InvalidParameterSpecException

setDigestAlgorithm

public void setDigestAlgorithm(AlgorithmID digest)
                        throws PropertyChangeException,
                               java.lang.NullPointerException,
                               java.security.NoSuchAlgorithmException

Specifies the message digest algorithm to use for signing the data.

The default message digest algorithm is SHA1. The algorithm is irrelevant if the data is not signed.

Possible choices for the digest algorithm are:

• AlgorithmID.sha1 - if a DSA, ECDSA, or RSA signing key is being used.
• AlgorithmID.sha256 - if an RSA signing key is being used.
• AlgorithmID.sha384 - if an RSA signing key is being used.
• AlgorithmID.sha512 - if an RSA signing key is being used.
• AlgorithmID.md5 - if an RSA signing key is being used.

Note

The message digest algorithm cannot be changed once data has been written to the stream.

Parameters:

digest - the algorithm to use for hashing the data

Throws:

java.lang.NullPointerException - thrown if digest is null

java.security.NoSuchAlgorithmException - thrown if digest is not recognized as a message digest algorithm in the user's environment, or if the algorithm specified is not a valid choice of digest algorithm.

PropertyChangeException - thrown if data has already been written to the stream

getDigestAlgorithm

public AlgorithmID getDigestAlgorithm()

Returns the message digest algorithm used to sign the data.

If the data is not signed, this method returns null.

Returns:

the algorithm used to hash the data, or null if the data is not signed

setEncryptionAlgorithm

public void setEncryptionAlgorithm(AlgorithmID encryptionAlg)
                            throws PropertyChangeException,
                                   java.security.NoSuchAlgorithmException

Specifies the encryption algorithm to be used during an PKCS7 encode operation that involves data being encrypted.

The default encryption algorithm is CAST5/CBC/PKCS5Padding, with no parameters. The encryption algorithm is irrelevant if the data is not being encrypted during the PKCS7 encode operation.

Note

The encryption algorithm cannot be changed once the encode operation has begun (data has been written to the stream).

Parameters:

encryptionAlg - the encryption algorithm to be used for encrypting data during the PKCS7 encode operation

Throws:

java.security.NoSuchAlgorithmException - thrown if a Cipher implementation or a KeyGenerator implementation for the encryption algorithm is not provided by any of the installed JCA providers

PropertyChangeException - thrown if the encode operation has already begun (data has been written to the stream)

setEncryptionAlgorithm

public void setEncryptionAlgorithm(AlgorithmID encryptionAlg,
                          int keyLength)
                            throws PropertyChangeException,
                                   java.security.NoSuchAlgorithmException

Specifies the encryption algorithm and encryption key length to be used during an PKCS7 encode operation that involves data being encrypted.

The key length parameter will be ignored if the encryption algorithm identifier itself indicates a key length. Some algorithm identifiers implicitly indicate a key length (AlgorithmID.aes_128_CBC) while others can indicate the key length in the parameters that are included in the algorithm identifier (AlgorithmID.cast5_CBC containing a CAST128ParameterSpec).

If the key length is not indicated by the encryption algorithm identifier, but the key length paraemter contains a value that is invalid for the encryption algorithm, it will be ignored and the default key length for the algorithm will be used instead.

The default encryption algorithm is CAST5/CBC/PKCS5Padding, with no parameters. The encryption algorithm is irrelevant if the data is not being encrypted during the PKCS7 encode operation.

Note

The encryption algorithm cannot be changed once the encode operation has begun (data has been written to the stream).

Parameters:

encryptionAlg - the encryption algorithm to be used for encrypting data during the PKCS7 encode operation

keyLength - the requested key length of the encryption key in bits

Throws:

java.security.NoSuchAlgorithmException - thrown if a Cipher implementation or a KeyGenerator implementation for the encryption algorithm is not provided by any of the installed JCA providers

PropertyChangeException - thrown if the encode operation has already begun (data has been written to the stream)

getEncryptionAlgorithm

public AlgorithmID getEncryptionAlgorithm()

Returns the algorithm used to encrypt the data during the PKCS7 encode operation.

If PKCS7 encode operation does not involve the data being encrypted, null is returned.

Returns:

AlgorithmID the encryption algorithm

setAuthenticatedAttributes

public void setAuthenticatedAttributes(Attribute[] attributes)

This method sets additional authenticated attributes to be included in this PKCS7 Message. By default, a PKCS7 message encoded with this class will include the ObjectID.contentType authenticated attribute as well as the ObjectID.signingTime authenticated attribute set to the current time.

Parameters:

attributes - an Array list of Authenticated attributes to add to this PKCS7 message

getAuthenticatedAttributes

public Attribute[] getAuthenticatedAttributes()

This method returns the set of authenticated attributes in the PKCS7 Message.

Returns:

the Array of Attributes that were set by calling setAuthenticatedAttributes(Attribute[])

setRecipients

public CertificateSet setRecipients(CertificateSet recipients)
                             throws PropertyChangeException

Specifies the public keys with which to encrypt the message.

Recipients that were set by previous calls to setRecipients or setTrustedRecipients are discarded. The user specified in the constructor is always a recipient and does not have to be included in the recipients list. If no recipient is specified, the message is encrypted only for the originator (that is, the user specified in the constructor).

If, for some reason, one or more certificates in the recipients set fails validation, and is therefore not acceptable as an encryption certificate, this method returns a set of all rejected certificates. These certificates are removed from recipients.

The default certificate is the user's encryption certificate specified in the constructor.

Note

The recipients cannot be changed once data has been written to the stream.

This method is irrelevant if the data is not encrypted.

Parameters:

recipients - the encryption certificates of those users who are able to decrypt the data. Rejected certificates are removed from this set.

Returns:

a set containing all rejected certificates, or null if all recipients' certificates are accepted.

Throws:

PropertyChangeException - if data has been written to the stream already

See Also:

CertVerifier

setTrustedRecipients

public void setTrustedRecipients(CertificateSet recipients)
                          throws PropertyChangeException

Specifies the validated public keys with which to encrypt the message.

Recipients that were set by previous calls to setRecipients or setTrustedRecipients are discarded. The user specified in the constructor is always a recipient and does not have to be included in the recipients list. If no recipient is specified, the message is encrypted only for the originator (that is, the user specified in the constructor).

The method assumes that all the certificates are valid, and does not do the validation checking. To validate the certificates, use setRecipients.

The default certificate is the user's encryption certificate specified in the constructor.

Note

The recipients cannot be changed once data has been written to the stream.

This method is irrelevant if the data is not encrypted.

Parameters:

recipients - the validated encryption certificates of those users who are able to decrypt the data.

Throws:

PropertyChangeException - if data has been written to the stream already

getRecipients

public CertificateSet getRecipients()

Returns the set of certificates for the public keys used to encrypt the data.

This list always includes the user specified in the constructor.

Returns:

the set of encryption certificates with which the data has been encrypted. Return value is null if the data is not encrypted.

setIncludedCertificates

public CertificateSet setIncludedCertificates(CertificateSet certs)
                                       throws PropertyChangeException

Specifies the certificates that are included in the PKCS#7 message.

If one or more certificates fails validation and is therefore not acceptable as an included certificate, this method returns a set of all rejected certificates. These certificates are removed from certs.

By default, the user's verification and encryption certificates and the user's CA's verification certificate are included with the message.

If the operation is ENCRYPT_ONLY, no certificates are included and this method is irrelevant.

Note

The included certificates cannot be changed once data has been written to the stream.

Parameters:

certs - a set of the certificates included in the PKCS#7 message

Returns:

a set containing all rejected certificates, or null if all certificates are accepted

Throws:

PropertyChangeException - if data has been written to the stream already

See Also:

CertVerifier

getIncludedCertificates

public CertificateSet getIncludedCertificates()

Returns the certificates that are to be included in the PKCS#7 message.

Returns:

all included X.509 certificates, or null if the operation is ENCRYPT_ONLY

write

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

Signs and encrypts, or just encrypts, the specified byte and writes it to the output stream.

If the operation is EXPORT_CERTIFICATES, this method returns without doing anything.

Overrides:

write in class java.io.FilterOutputStream

Parameters:

b - the byte to sign and/or encrypt

Throws:

java.io.IOException - thrown if an I/O error occurs in the underlying stream

write

public void write(byte[] b)
           throws java.io.IOException

Signs and encrypts, or just encrypts, b.length bytes and writes them to the output stream.

This method calls write(byte, int, int) with the arguments: b, 0, and b.length. If the operation is EXPORT_CERTIFICATES, this method returns without doing anything.

Overrides:

write in class java.io.FilterOutputStream

Parameters:

b - the data to be signed and/or encrypted

Throws:

java.io.IOException - thrown if an I/O error occurs in the underlying stream

write

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

Signs and encrypts, or just encrypts, len bytes from the specified byte array.

The method starts at offset off and writes to the output stream. If the operation is EXPORT_CERTIFICATES, this method returns without doing anything.

Overrides:

write in class java.io.FilterOutputStream

Parameters:

b - the data to be signed and/or encrypted

off - the start offset in the data

len - the number of bytes to sign and/or encrypt

Throws:

java.io.IOException - thrown if an I/O error occurs in the underlying stream

flush

public void flush()
           throws java.io.IOException

Flushes this output stream forcing any buffered output bytes to be written to the stream.

Specified by:

flush in interface java.io.Flushable

Overrides:

flush in class java.io.FilterOutputStream

Throws:

java.io.IOException - thrown if an I/O error occurs in the underlying stream

close

public void close()
           throws java.io.IOException

Closes this output stream and releases any system resources associated with the 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 - thrown if an I/O error occurs in the underlying stream

requestTimeStamp

public void requestTimeStamp(TimeStampClient timeStampClient)

Requests that the signature be time-stamped.

For operations that involve signing (SIGN_AND_ENCRYPT, SIGN_ONLY, or CLEAR_SIGN), when the SignerInfo structure this stream contains is encoded to an ASN1 object, a time-stamp will automatically be requested from the TimeStamp Authority indicated, and added to the SignerInfo structure as an unsigned attribute.

A time-stamp will only be requested when timeStampClient is not set to null.

Note:

The time-stamp is not actually requested until the PKCS7EncodeStream encoding is done, which occurs during a close operation. Thus, if the time-stamp client that was used to request that the signature be time-stamped is modified (hash algorithm changed, TSA policy changed, ...) before the close operation, these changes will apply to the time-stamp that is requested during the encoding.

Parameters:

timeStampClient - the time-stamp client that will be used to request a time-stamp for the signature value from a TimeStamp Authority

Since:

7.0

getDigest

public byte[] getDigest()

Returns the digest that was calculated over the data during a signing operation.

This is only accessible following a successful signing operation, and only after the stream has been closed. If the stream has not been closed, an error occurred during the P7 operation, or the P7 operation did not involve signing, null is returned.

Returns:

the digest

Since:

7.0