org.faceless.pdf2
Class EncryptionHandler

java.lang.Object
  extended byorg.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 (setObject(int, int), getEncryptionStream(java.io.OutputStream)), then 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)

Constructor Summary
protected EncryptionHandler()
           
 
Method Summary
 Object clone()
           
protected  boolean containsKey(String key)
          Return true if the Encrypt dictionary contains the specified key
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.
protected  int getArrayValueSize(String key)
          Return the size of the specified Array from the Encrypt dictionary, or -1 if no such field exists
protected  boolean getBooleanValue(String key)
          Return a Boolean from the Encrypt dictionary as a boolean or false if no such field exists
abstract  OutputStream getDecryptionStream(OutputStream out)
          Return a FilterOutputStream that will decrypt anything written to it.
protected  Set getDictionaryValueKeys(String key)
          Return the Set of keys of the specified Dictionary from the Encrypt dictionary, or null if no such field exists.
abstract  OutputStream getEncryptionStream(OutputStream out)
          Return a FilterOutputStream that will encrypt anything written to it.
protected  byte[] getFileId()
          This method returns the the file ID of the document, as set by setFileId(byte[]).
abstract  String getFilterName()
          Return the name of the "Filter" field in the Encryption dictionary.
protected  String getNameValue(String key)
          Return a Name from the Encrypt dictionary as a String or null if no such field exists
protected  float getNumericValue(String key)
          Return a Number from the Encrypt dictionary as a float or Float.NaN if no such field exists
protected  byte[] getStringValue(String key)
          Return a String from the Encrypt dictionary as a byte array or null if no such field exists
abstract  String getSubFilterName()
          Return the name of the "Subfilter" field in the Encryption dictionary.
protected  String getTextStringValue(String key)
          Return a Text String from the Encrypt dictionary as a String or null if no such field exists
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.
protected  void putArrayValue(String key)
          Add (or replace) an Array to the Encrypt dictionary.
protected  void putBooleanValue(String key, boolean val)
          Add (or replace) a Boolean to the Encrypt dictionary.
protected  void putDictionaryValue(String key)
          Add (or replace) a Dictionary to the Encrypt dictionary.
protected  void putNameValue(String key, String val)
          Add (or replace) a Name to the Encrypt dictionary.
protected  void putNumericValue(String key, float val)
          Add (or replace) a Number to the Encrypt dictionary.
protected  void putStringValue(String key, byte[] val)
          Add (or replace) a String to the Encrypt dictionary.
protected  void putTextStringValue(String key, String val)
          Add (or replace) a Text String to the Encrypt dictionary.
 void setFileId(byte[] in)
          This method is called to set the file ID of the document.
abstract  void setObject(int object, int generation)
          This method is called just before each object is encrypted.
 
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

EncryptionHandler

protected EncryptionHandler()
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)
Return a FilterOutputStream that will encrypt anything written to it. The encryption parameters should have already been set by the call to prepareToEncrypt(), which is called once at the start of the render, and setObject(int, int), which is called just before each object is rendered.


getDecryptionStream

public abstract OutputStream getDecryptionStream(OutputStream out)
Return a FilterOutputStream that will decrypt anything written to it. The decryption parameters should have already been set by the call to prepareToDecrypt(), which is called once at the start of the PDF read, and setObject(int, int), which is called just before each object is read.


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.


setObject

public abstract void setObject(int object,
                               int generation)
This method is called just before each object is encrypted. It is expected that the values that are passed in are used to change the stream returned by the getEncryptionStream(java.io.OutputStream) and getEncryptionStream(java.io.OutputStream) methods


setFileId

public final void setFileId(byte[] in)
This method is called to set the file ID of the document.


getFileId

protected final byte[] getFileId()
This method returns the the file ID of the document, as set by setFileId(byte[]).


clone

public Object clone()

containsKey

protected boolean containsKey(String key)
Return true if the Encrypt dictionary contains the specified key


getStringValue

protected final byte[] getStringValue(String key)
Return a String from the Encrypt dictionary as a byte array or null if no such field exists


getTextStringValue

protected final String getTextStringValue(String key)
Return a Text String from the Encrypt dictionary as a String or null if no such field exists


getNameValue

protected final String getNameValue(String key)
Return a Name from the Encrypt dictionary as a String or null if no such field exists


getNumericValue

protected final float getNumericValue(String key)
Return a Number from the Encrypt dictionary as a float or Float.NaN if no such field exists


getBooleanValue

protected final boolean getBooleanValue(String key)
Return a Boolean from the Encrypt dictionary as a boolean or false if no such field exists


getArrayValueSize

protected final int getArrayValueSize(String key)
Return the size of the specified Array from the Encrypt dictionary, or -1 if no such field exists


getDictionaryValueKeys

protected final Set getDictionaryValueKeys(String key)
Return the Set of keys of the specified Dictionary from the Encrypt dictionary, or null if no such field exists.


putStringValue

protected final void putStringValue(String key,
                                    byte[] val)
Add (or replace) a String to the Encrypt dictionary. A value of null removes the entry.


putTextStringValue

protected final void putTextStringValue(String key,
                                        String val)
Add (or replace) a Text String to the Encrypt dictionary. A value of null removes the entry


putNumericValue

protected final void putNumericValue(String key,
                                     float val)
Add (or replace) a Number to the Encrypt dictionary. A value of Float.NaN removes the entry.


putNameValue

protected final void putNameValue(String key,
                                  String val)
Add (or replace) a Name to the Encrypt dictionary. A value of null removes the entry.


putBooleanValue

protected final void putBooleanValue(String key,
                                     boolean val)
Add (or replace) a Boolean to the Encrypt dictionary. A value of null removes the entry.


putArrayValue

protected final void putArrayValue(String key)
Add (or replace) an Array to the Encrypt dictionary.


putDictionaryValue

protected final void putDictionaryValue(String key)
Add (or replace) a Dictionary to the Encrypt dictionary.



Copyright © 2001-2004 Big Faceless Organization