Package org.faceless.pdf2

Class 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(InputStream, EncryptionHandler)

    • 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

      • isChanged

        public boolean isChanged()
        Return true if the PDF has been marked as changed
        Since:
        2.18.2
        See Also:
        markChanged()

      • 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[]).

      • 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

      • getIntegerValue

        protected int getIntegerValue​(String key)
        Return a Number from the Encrypt dictionary as an integer or 0 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<String> 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.