|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectorg.faceless.pdf2.EncryptionHandler
public abstract class EncryptionHandler
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.
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 |
---|
protected EncryptionHandler()
Method Detail |
---|
public abstract String getFilterName()
StandardEncryptionHandler
class returns "Standard" from this method.
public abstract String getSubFilterName()
null
.
public abstract OutputStream getEncryptionStream(OutputStream out, int object, int generation)
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.
out
- the OuptutStream that should be written toobject
- the object number of the top-level objectgeneration
- the generation number of the top-level objectpublic abstract InputStream getDecryptionStream(InputStream in, int object, int generation)
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.
in
- the InputStream that should be read fromobject
- the object number of the top-level objectgeneration
- the generation number of the top-level objectpublic int getEncryptedStreamLength(int length)
public int getDecryptedStreamLength(int length)
public abstract void prepareToDecrypt() throws IOException
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.
IOException
public abstract void prepareToEncrypt() throws IOException
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.
IOException
public abstract void finishedDecrypt()
public abstract void finishedEncrypt()
public abstract boolean isRequired()
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.
public boolean isMetadataEncrypted()
public boolean isStringEncrypted()
public boolean isStreamEncrypted()
public boolean isEmbeddedFileEncrypted()
protected void markChanged()
IllegalStateException
is called
IllegalStateException
- if the document has any digital signatures that would
be invalidated by this changepublic void setFileId(byte[] in)
public boolean hasRight(String right)
super.hasRight()
if it doesn't recognise the value of "right"
right
- an interned() String defining the usage right the PDF library
is querying.protected byte[] getFileId()
setFileId(byte[])
.
public Object clone()
clone
in class Object
protected boolean containsKey(String key)
Encrypt
dictionary contains the specified key
protected byte[] getStringValue(String key)
Encrypt
dictionary as a byte array
or null
if no such field exists
protected String getTextStringValue(String key)
Encrypt
dictionary as a String
or null
if no such field exists
protected String getNameValue(String key)
Encrypt
dictionary as a String
or null
if no such field exists
protected float getNumericValue(String key)
Encrypt
dictionary as a float
or Float.NaN
if no such field exists
protected boolean getBooleanValue(String key)
Encrypt
dictionary as a boolean
or false
if no such field exists
protected int getArrayValueSize(String key)
Encrypt
dictionary,
or -1
if no such field exists
protected Set getDictionaryValueKeys(String key)
Encrypt
dictionary,
or null
if no such field exists.
protected void putStringValue(String key, byte[] val)
Encrypt
dictionary.
A value of null
removes the entry.
protected void putTextStringValue(String key, String val)
Encrypt
dictionary.
A value of null
removes the entry
protected void putNumericValue(String key, float val)
Encrypt
dictionary.
A value of Float.NaN
removes the entry.
protected void putNameValue(String key, String val)
Encrypt
dictionary.
A value of null
removes the entry.
protected void putBooleanValue(String key, boolean val)
Encrypt
dictionary.
A value of null
removes the entry.
protected void putArrayValue(String key)
Encrypt
dictionary.
protected void putDictionaryValue(String key)
Encrypt
dictionary.
|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |