org.faceless.pdf2
Class EncryptionHandler

java.lang.Object
  org.faceless.pdf2.EncryptionHandler

All Implemented Interfaces:

Cloneable

Direct Known Subclasses:

PublicKeyEncryptionHandler, StandardEncryptionHandler

public abstract class EncryptionHandler
extends Object
implements Cloneable

An EncryptionHandler is the abstract superclass of all algorithms that are used to encrypt a PDF document before saving. Encryption is required to enforce any sorts of restriction on a PDF, whether it be that it requires a password to open, it can only be opened by a user posessing a certain private key, or just that it can't be printed or altered.

Although currently the PDF library is only supplied with a single implementation of this class (the StandardEncryptionHandler), it is possible for end-users to implement their own versions of this class to allow PDF's to be created for custom encryption handlers, such as might be required for e-Books (for example).

The following information is for those who will be creating a concrete implementation of this class.

When encrypting, the PDF.render(java.io.OutputStream) method will call the prepareToEncrypt() method, followed by n number of calls to getEncryptionStream(java.io.OutputStream, int, int) and finally followed by a call to finishedEncrypt() (the decryption process is the same, except substitute the word "Decrypt" for Encrypt in the method names above).

The two prepare... methods can store and retrieve values out of the Encrypt dictionary by calling the various get... and put... methods. These methods expect the key to be specified as a String. At it's simplest, a method call like putNameValue("Filter", "Standard") would create a PDF Name object called "Filter" in the Encrypt dictionary. For nested objects, Arrays and Dictionary objects can be referenced by placing a "." between field names. For example, "MyArray.2.Name" references the object called "Name" in the Dictionary which is the second entry in the "MyArray" array of the Encrypt dictionary. All objects added this way are "direct" - it is not possible to add indirect objects to the encryption dictionary or it's children.

An EncryptionHandler may be used for both decryption and encryption if the document is read and then written again, so it's important that any values read from the Encrypt dictionary during the prepareToDecrypt() method are available to be reused in the prepareToEncrypt() method.

Finally, care needs to be taken about any references to Object instances when an instance is cloned - which it will be when a PDF containing an EncryptionHandler is cloned.

Since:

2.0

See Also:

PDF.setEncryptionHandler(org.faceless.pdf2.EncryptionHandler), PDFReader.PDFReader(InputStream, EncryptionHandler)

Method Summary

Object	clone()
abstract void	finishedDecrypt() This method is called after the PDF has been read.
abstract void	finishedEncrypt() This method is called after the PDF has been written.
abstract InputStream	getDecryptionStream(InputStream in, int object, int generation) Return a FilterInputStream that will decrypt anything read from it.
int	getEncryptedStreamLength(int length) Return the length that a stream of the specified length would be after encryption.
abstract OutputStream	getEncryptionStream(OutputStream out, int object, int generation) Return a FilterOutputStream that will encrypt anything written to it.
abstract String	getFilterName() Return the name of the "Filter" field in the Encryption dictionary.
abstract String	getSubFilterName() Return the name of the "Subfilter" field in the Encryption dictionary.
boolean	hasRight(String right) Returns true if the EncryptionHandler wil grant the specified right to the PDF library.
boolean	isMetadataEncrypted() This method returns true if XMP MetaData should be stored encrypted, or false otherwise.
abstract boolean	isRequired() This method should return true if the document needs to be encrypted.
abstract void	prepareToDecrypt() This method is called just before the PDF is read in.
abstract void	prepareToEncrypt() This method is called when the PDF is about to be written out.
void	setFileId(byte[] in) This method is called to set the file ID of the document.

Methods inherited from class java.lang.Object

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

Method Detail

getFilterName

public abstract String getFilterName()

Return the name of the "Filter" field in the Encryption dictionary. This is used to determine whether an appropriate filter has been supplied by the decryption process. For example, the StandardEncryptionHandler class returns "Standard" from this method.

getSubFilterName

public abstract String getSubFilterName()

Return the name of the "Subfilter" field in the Encryption dictionary. This is used to determine whether an appropriate filter has been supplied by the decryption process. As "Subfilter" is an optional field, this method may return null.

getEncryptionStream

public abstract OutputStream getEncryptionStream(OutputStream out,
                                                 int object,
                                                 int generation)

Return a FilterOutputStream that will encrypt anything written to it. Theencryption parameters should be set from the information provided to prepareToEncrypt(), which is called once at the start of the render, and the object and generation parameters.

Parameters:

out - the OuptutStream that should be written to

object - the object number of this object in the PDF

generation - the generation number of this object in the PDF

Since:

2.10 (a similar method existed from 2.0 but with a different signature)

getDecryptionStream

public abstract InputStream getDecryptionStream(InputStream in,
                                                int object,
                                                int generation)

Return a FilterInputStream that will decrypt anything read from it. The decryption parameters should be set from the information provided to prepareToDecrypt(), which is called once at the start of the PDF read, and the object and generation parameters.

Parameters:

in - the InputStream that should be read from

object - the object number of this object in the PDF

generation - the generation number of this object in the PDF

Since:

2.10 (a similar method existed from 2.0 but with a different signature)

getEncryptedStreamLength

public int getEncryptedStreamLength(int length)

Return the length that a stream of the specified length would be after encryption. Generally this will be the same same as the input length (and that's what this method returns, unless overridden), but for some Encryption algorithms like AES, the size may be rounded up to the nearest block size.

Since:

2.4

prepareToDecrypt

public abstract void prepareToDecrypt()
                               throws IOException

This method is called just before the PDF is read in. It is expected that this method will read various parameters from the Encrypt dictionary by way of the various get... methods, and use them and the value of getFileId() to set its internal state so that it's ready to start decryption. It may throw an IOException if these parameters are invalid, in which case the document cannot be read.

Throws:

IOException

prepareToEncrypt

public abstract void prepareToEncrypt()
                               throws IOException

This method is called when the PDF is about to be written out. It is expected that this method will write various parameters which have been set by the user to the Encrypt dictionary (including the "Filter" field) by way of the various put... methods, and will use these and the value of getFileId() to set its internal state so that it's ready to start encryption. It may throw an IOException if these parameters are in any way invalid, in which case the document cannot be written.

Throws:

IOException

finishedDecrypt

public abstract void finishedDecrypt()

This method is called after the PDF has been read. It may be used to clean up any internal state that needs to be cleaned.

finishedEncrypt

public abstract void finishedEncrypt()

This method is called after the PDF has been written. It may be used to clean up any internal state that needs to be cleaned.

isRequired

public abstract boolean isRequired()

This method should return true if the document needs to be encrypted. For example, the StandardEncryptionHandler returns false here if and only if no passwords are set and the document is set to allow full access.

isMetadataEncrypted

public boolean isMetadataEncrypted()

This method returns true if XMP MetaData should be stored encrypted, or false otherwise. The default implementation returns true, subclasses should override as necessary.

Since:

2.8.2

setFileId

public void setFileId(byte[] in)

This method is called to set the file ID of the document.

hasRight

public boolean hasRight(String right)

Returns true if the EncryptionHandler wil grant the specified right to the PDF library. The default implementation of this method returns true, but subclasses will override this method based on the rights applied to the document. This method should always return true if it doesn't recognise the value of "right"

Parameters:

right - an interned() String defining the usage right the PDF library is querying.

Since:

2.8.2

clone

public Object clone()

Overrides:

clone in class Object