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)`

- - ### Constructor Summary

    Constructors
    Modifier | Constructor and Description
    --- | ---
    `protected` | `EncryptionHandler()`

  - ### Method Summary

    All Methods Instance Methods Abstract Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `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<String>` | `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<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.

Copyright © 2001-2015 Big Faceless Organization