org.faceless.pdf2
Class EncryptionHandler

java.lang.Object
  extended by 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)

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
 int getDecryptedStreamLength(int length)
          Return the length that an encrypted stream o the specified length would be after decryption.
abstract  InputStream getDecryptionStream(InputStream in, int object, int generation)
          Return a FilterInputStream that will decrypt anything read from 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.
 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.
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
 boolean hasRight(String right)
          Returns true if the EncryptionHandler wil grant the specified right to the PDF library.
 boolean isEmbeddedFileEncrypted()
          This method returns true if Embedded Files in the document should be stored encrypted.
 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.
 boolean isStreamEncrypted()
          This method returns true if Streams in the document should be stored encrypted.
 boolean isStringEncrypted()
          This method returns true if Strings in the document should be stored encrypted.
protected  void markChanged()
          This method should be called whenever a field in the EncryptionHandler is changed so that the encryption would be changed.
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.
 
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,
                                                 int object,
                                                 int generation)
Return a FilterOutputStream that will encrypt anything written to it. The encryption parameters are set in prepareToEncrypt(), which is called once at the start of the render.

Parameters:
out - the OuptutStream that should be written to
object - the object number of the top-level object
generation - the generation number of the top-level object

getDecryptionStream

public abstract InputStream getDecryptionStream(InputStream in,
                                                int object,
                                                int generation)
Return a FilterInputStream that will decrypt anything read from it. The decryption parameters are set in prepareToDecrypt(), which is called once at the start of the PDF read.

Parameters:
in - the InputStream that should be read from
object - the object number of the top-level object
generation - the generation number of the top-level object

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

getDecryptedStreamLength

public int getDecryptedStreamLength(int length)
Return the length that an encrypted stream o the specified length would be after decryption. Generally this will be the same as the input length, which is what this method returns unless overridden. However for some encryption algorithms like AES the size will be altered. If an exact number is known this method should return it, or if it's not possible to deduce the decrypted length from the input length this method should return -1.

Since:
2.10.3

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

isStringEncrypted

public boolean isStringEncrypted()
This method returns true if Strings in the document should be stored encrypted. By default this method returns true.

Since:
2.10.3

isStreamEncrypted

public boolean isStreamEncrypted()
This method returns true if Streams in the document should be stored encrypted. By default this method returns true.

Since:
2.10.3

isEmbeddedFileEncrypted

public boolean isEmbeddedFileEncrypted()
This method returns true if Embedded Files in the document should be stored encrypted. By default this method returns true.

Since:
2.10.3

markChanged

protected void markChanged()
This method should be called whenever a field in the EncryptionHandler is changed so that the encryption would be changed. This method is required because documents that are both digitally signed and encrypted cannot have their encryption changed without invalidating the signature. When this method is called, if the document contains any signed signatures an IllegalStateException is called

Throws:
IllegalStateException - if the document has any digital signatures that would be invalidated by this change
Since:
2.4

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 super.hasRight() 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

getFileId

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


clone

public Object clone()
Overrides:
clone in class Object

containsKey

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


getStringValue

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


getTextStringValue

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


getNameValue

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


getNumericValue

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


getBooleanValue

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


getArrayValueSize

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


getDictionaryValueKeys

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.


putStringValue

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


putTextStringValue

protected 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 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 void putNameValue(String key,
                            String val)
Add (or replace) a Name to the Encrypt dictionary. A value of null removes the entry.


putBooleanValue

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


putArrayValue

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


putDictionaryValue

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



Copyright © 2001-2013 Big Faceless Organization