org.faceless.pdf2

## Class StandardEncryptionHandler

- java.lang.Object
- - org.faceless.pdf2.EncryptionHandler
  - - org.faceless.pdf2.StandardEncryptionHandler

- All Implemented Interfaces:
    Cloneable
  Direct Known Subclasses:
    PasswordPromptEncryptionHandler

      public class StandardEncryptionHandler
      extends EncryptionHandler

  Represents the standard Acrobat encryption algorithm, both 40-bit and 128-bit variants. The only methods the end-user need worry about are `setUserPassword(java.lang.String)`, `setOwnerPassword(java.lang.String)`, `setAcrobat3Level(boolean, boolean, boolean, boolean)` and `setAcrobat5Level(int, int, int)` - all the other methods are used by the encryption process itself.

  A typical use would be to create a PDF document that cannot be printed. This is done like so:

        StandardEncryptionHandler encrypt = new StandardEncryptionHandler();
        encrypt.setAcrobat3Level(false, true, true, true);
        pdf.setEncryptionHandler(encrypt);

  For reading a document with a password, the `PDFReader` class has a convenience method whereby a password can be passed in as a `String` to decrypt. However, if you wanted to pass in an `EncryptionHandler` that would have the same result, you could do this:

        StandardEncryptionHandler encrypt = new StandardEncryptionHandler();
        encrypt.setUserPassword("secret");
        PDFReader reader = new PDFReader(inputstream, encrypt);
        inputstream.close();
        PDF pdf = new PDF(reader);

  Since:
    2.0
  See Also:
    `PDF.setEncryptionHandler(org.faceless.pdf2.EncryptionHandler)`, `PDFReader.PDFReader(InputStream,EncryptionHandler)`

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static int` | `CHANGE_ALL` Parameter to `setAcrobat5Level(int, int, int)` to allow the document to be modified in any way
    `static int` | `CHANGE_ANNOTATIONS` Parameter to `setAcrobat5Level(int, int, int)` to allow form fields and annotations to be added or modified
    `static int` | `CHANGE_FORMS` Parameter to `setAcrobat5Level(int, int, int)` to allow only form fields to be completed
    `static int` | `CHANGE_LAYOUT` Parameter to `setAcrobat5Level(int, int, int)` to allow only pages to be inserted, deleted, rotated and reordered
    `static int` | `CHANGE_NONE` Parameter to `setAcrobat5Level(int, int, int)` to disallow all changes to the document
    `static int` | `EXTRACT_ACCESSIBILITY` Parameter to `setAcrobat5Level(int, int, int)` to allow the limited copying of images and text for the purposes of accessibility for disabled users
    `static int` | `EXTRACT_ALL` Parameter to `setAcrobat5Level(int, int, int)` to allow copying of images and text from the document.
    `static int` | `EXTRACT_NONE` Parameter to `setAcrobat5Level(int, int, int)` to prevent any copying of images of text
    `static int` | `PRINT_HIGHRES` Parameter to `setAcrobat5Level(int, int, int)` to allow full print access
    `static int` | `PRINT_LOWRES` Parameter to `setAcrobat5Level(int, int, int)` to limit printing to lo-res (theoretically about 150dpi)
    `static int` | `PRINT_NONE` Parameter to `setAcrobat5Level(int, int, int)` to prevent printing altogether

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `StandardEncryptionHandler()` Create a new StandardEncryptionHandler for encryption or decryption of documents.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods Deprecated Methods
    Modifier and Type | Method and Description
    --- | ---
    `Object` | `clone()`
    `boolean` | `equals(Object o)`
    `void` | `finishedDecrypt()` This method is called after the PDF has been read.
    `void` | `finishedEncrypt()` This method is called after the PDF has been written.
    `int` | `getChange()` Return the value of the "Change" flags
    `int` | `getDecryptedStreamLength(int len)` Return the length that an encrypted stream o the specified length would be after decryption.
    `InputStream` | `getDecryptionStream(InputStream in, int num, int gen)` Return a `FilterInputStream` that will decrypt anything read from it.
    `String` | `getDescription()` Return a textual description of the algorithm used
    `int` | `getEncryptedStreamLength(int len)` Return the length that a stream of the specified length would be after encryption.
    `OutputStream` | `getEncryptionStream(OutputStream out, int num, int gen)` Return a `FilterOutputStream` that will encrypt anything written to it.
    `int` | `getExtract()` Return the value of the "Extract" flags
    `String` | `getFilterName()` Return the name of the "Filter" field in the Encryption dictionary.
    `int` | `getPrint()` Return the value of the "Print" flags
    `String` | `getSubFilterName()` Return the name of the "Subfilter" field in the Encryption dictionary.
    `int` | `getVersion()` Return the version of the encryption algorithm used.
    `int` | `hashCode()`
    `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.
    `boolean` | `isOwnerPasswordKnown()` Return true if the Owner password was used to open this PDF, false if the User password was used.
    `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.
    `void` | `prepareToDecrypt()` This method is called just before the PDF is read in.
    `void` | `prepareToEncrypt()` This method is called when the PDF is about to be written out.
    `void` | `setAcrobat3Level(boolean print, boolean annotations, boolean extraction, boolean change)` Set the access levels for Acrobat 3 and greater.
    `void` | `setAcrobat5Level(int print, int extraction, int change)` Set the access levels for Acrobat 5 and greater.
    `void` | `setAcrobat6Level(int print, int extraction, int change, boolean encryptmetadata)` Set the access levels for Acrobat 6 and greater.
    `void` | `setAcrobat7Level(int print, int extraction, int change, boolean encryptmetadata)` Set the access levels for Acrobat 7 and greater.
    `void` | `setAcrobat9Level(int print, int extraction, int change, boolean encryptmetadata)` Deprecated. the encryption algorithm used by Acrobat 9 has ben found to be less secure than the algorithm used by Acrobat 7, so as of 2.11.19 a request for Acrobat 9 encryption will fall back to Acrobat 7 encryption.
    `void` | `setAcrobatXLevel(int print, int extraction, int change, boolean encryptmetadata)` Set the access levels for Acrobat X and greater.
    `void` | `setOwnerPassword(String password)` Set the "security" password for the PDF document - the password required to change the security settings of the document (the access level and the open password).
    `void` | `setUserPassword(String password)` Set the password required to open the document (also called the "User" password).

    - ### Methods inherited from class org.faceless.pdf2.EncryptionHandler

      `containsKey, getArrayValueSize, getBooleanValue, getDictionaryValueKeys, getFileId, getNameValue, getNumericValue, getStringValue, getTextStringValue, markChanged, putArrayValue, putBooleanValue, putDictionaryValue, putNameValue, putNumericValue, putStringValue, putTextStringValue, setFileId`

    - ### Methods inherited from class java.lang.Object

      `finalize, getClass, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### PRINT_NONE

          public static final int PRINT_NONE

      Parameter to `setAcrobat5Level(int, int, int)` to prevent printing altogether
      See Also:
        Constant Field Values

    - #### PRINT_LOWRES

          public static final int PRINT_LOWRES

      Parameter to `setAcrobat5Level(int, int, int)` to limit printing to lo-res (theoretically about 150dpi)
      See Also:
        Constant Field Values

    - #### PRINT_HIGHRES

          public static final int PRINT_HIGHRES

      Parameter to `setAcrobat5Level(int, int, int)` to allow full print access
      See Also:
        Constant Field Values

    - #### EXTRACT_NONE

          public static final int EXTRACT_NONE

      Parameter to `setAcrobat5Level(int, int, int)` to prevent any copying of images of text
      See Also:
        Constant Field Values

    - #### EXTRACT_ACCESSIBILITY

          public static final int EXTRACT_ACCESSIBILITY

      Parameter to `setAcrobat5Level(int, int, int)` to allow the limited copying of images and text for the purposes of accessibility for disabled users
      See Also:
        Constant Field Values

    - #### EXTRACT_ALL

          public static final int EXTRACT_ALL

      Parameter to `setAcrobat5Level(int, int, int)` to allow copying of images and text from the document.
      See Also:
        Constant Field Values

    - #### CHANGE_NONE

          public static final int CHANGE_NONE

      Parameter to `setAcrobat5Level(int, int, int)` to disallow all changes to the document
      See Also:
        Constant Field Values

    - #### CHANGE_LAYOUT

          public static final int CHANGE_LAYOUT

      Parameter to `setAcrobat5Level(int, int, int)` to allow only pages to be inserted, deleted, rotated and reordered
      See Also:
        Constant Field Values

    - #### CHANGE_FORMS

          public static final int CHANGE_FORMS

      Parameter to `setAcrobat5Level(int, int, int)` to allow only form fields to be completed
      See Also:
        Constant Field Values

    - #### CHANGE_ANNOTATIONS

          public static final int CHANGE_ANNOTATIONS

      Parameter to `setAcrobat5Level(int, int, int)` to allow form fields and annotations to be added or modified
      See Also:
        Constant Field Values

    - #### CHANGE_ALL

          public static final int CHANGE_ALL

      Parameter to `setAcrobat5Level(int, int, int)` to allow the document to be modified in any way
      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### StandardEncryptionHandler

          public StandardEncryptionHandler()

      Create a new StandardEncryptionHandler for encryption or decryption of documents. The default access level is 40-bit RC4 encryption with everything allowed (ie. the same as calling `setAcrobat3Level(true,true,true,true)`)
      Since:
        2.0

  - ### Method Detail

    - #### hashCode

          public int hashCode()

      Overrides:
        `hashCode` in class `Object`

    - #### equals

          public boolean equals(Object o)

      Overrides:
        `equals` in class `Object`

    - #### clone

          public Object clone()

      Overrides:
        `clone` in class `EncryptionHandler`

    - #### setOwnerPassword

          public void setOwnerPassword(String password)

      Set the "security" password for the PDF document - the password required to change the security settings of the document (the access level and the open password). If you don't anticipate changing the security settings at a later date, you can leave this blank.

      Since:
        2.0

    - #### setUserPassword

          public void setUserPassword(String password)

      Set the password required to open the document (also called the "User" password). It can be left blank, in which case anyone can open the document with out a password
      Since:
        2.0

    - #### setAcrobat3Level

          public void setAcrobat3Level(boolean print,
                                       boolean annotations,
                                       boolean extraction,
                                       boolean change)

      Set the access levels for Acrobat 3 and greater. The document will be encrypted using 40-bit RC4 encryption, so that any browser after Acrobat 3 can open the document.
      Parameters:
        `print` - true if the document can be printed
        `annotations` - true if form field and other annotations can be added or edited
        `extraction` - true if text and images can be copied from the document
        `change` - true if the document can have pages added, deleted, reordered or rotated
      Since:
        2.0

    - #### setAcrobat5Level

          public void setAcrobat5Level(int print,
                                       int extraction,
                                       int change)

      Set the access levels for Acrobat 5 and greater. The document will be encrypted using 128-bit RC4 encryption, so that only Acrobat 5.0 and later browsers can open the document.

      The various parameter control the level of printing, the level of data extraction and the types of changes that can be made to the document.

      Parameters:
        `print` - one of `PRINT_NONE` `PRINT_LOWRES` `PRINT_HIGHRES`
        `extraction` - one of `EXTRACT_NONE` `EXTRACT_ACCESSIBILITY` `EXTRACT_ALL`
        `change` - one of `CHANGE_NONE` `CHANGE_LAYOUT` `CHANGE_FORMS` `CHANGE_ANNOTATIONS` `CHANGE_ALL`
      Since:
        2.0

    - #### setAcrobat6Level

          public void setAcrobat6Level(int print,
                                       int extraction,
                                       int change,
                                       boolean encryptmetadata)

      Set the access levels for Acrobat 6 and greater. Acrobat 6 encryption is identical to Acrobat 5 except that it optionally allows leaving XMP MetaData unencrypted. Because of this, if the `encryptmetadata` param is set to true, this method is identical to calling `setAcrobat5Level(int, int, int)`.

      Parameters:
        `print` - one of `PRINT_NONE` `PRINT_LOWRES` `PRINT_HIGHRES`
        `extraction` - one of `EXTRACT_NONE` `EXTRACT_ACCESSIBILITY` `EXTRACT_ALL`
        `change` - one of `CHANGE_NONE` `CHANGE_LAYOUT` `CHANGE_FORMS` `CHANGE_ANNOTATIONS` `CHANGE_ALL`
        `encryptmetadata` - whether to encrypt the XMP metadata
      Since:
        2.0.1

    - #### setAcrobat7Level

          public void setAcrobat7Level(int print,
                                       int extraction,
                                       int change,
                                       boolean encryptmetadata)
                                throws NoSuchAlgorithmException

      Set the access levels for Acrobat 7 and greater. Acrobat 7 encryption is identical to Acrobat 6 except that the Advanced Encryption Standard (AES) is used as the block cipher rather than RC4. Documents encrypted with AES can only be opened in Acrobat 7.0 or later. AES encryption requires the JCE to be installed - in practice this means Java 1.4 or later is required.

      Parameters:
        `print` - one of `PRINT_NONE` `PRINT_LOWRES` `PRINT_HIGHRES`
        `extraction` - one of `EXTRACT_NONE` `EXTRACT_ACCESSIBILITY` `EXTRACT_ALL`
        `change` - one of `CHANGE_NONE` `CHANGE_LAYOUT` `CHANGE_FORMS` `CHANGE_ANNOTATIONS` `CHANGE_ALL`
        `encryptmetadata` - whether to encrypt the XMP metadata
      Throws:
        `NoSuchAlgorithmException` - if the AES cipher isn't available
      Since:
        2.4.3

    - #### setAcrobat9Level

          @Deprecated
          public void setAcrobat9Level(int print,
                                                   int extraction,
                                                   int change,
                                                   boolean encryptmetadata)
                                            throws NoSuchAlgorithmException

      Deprecated. the encryption algorithm used by Acrobat 9 has ben found to be less secure than the algorithm used by Acrobat 7, so as of 2.11.19 a request for Acrobat 9 encryption will fall back to Acrobat 7 encryption.

      Set the access levels for Acrobat 9 and greater. Acrobat 9 encryption is identical to Acrobat 7 except that the key length for the AES block cipher is 256 bit rather than 128. Documents encrypted this way can only be opened with Acrobat 9.0 or later.

      Users of Sun JVMs will require the "unlimited strength" policy files to use AES256 encryption, and other JVMs may have similar requirements.

      Parameters:
        `print` - one of `PRINT_NONE` `PRINT_LOWRES` `PRINT_HIGHRES`
        `extraction` - one of `EXTRACT_NONE` `EXTRACT_ACCESSIBILITY` `EXTRACT_ALL`
        `change` - one of `CHANGE_NONE` `CHANGE_LAYOUT` `CHANGE_FORMS` `CHANGE_ANNOTATIONS` `CHANGE_ALL`
        `encryptmetadata` - whether to encrypt the XMP metadata
      Throws:
        `NoSuchAlgorithmException` - if the AES cipher isn't available
      Since:
        2.11

    - #### setAcrobatXLevel

          public void setAcrobatXLevel(int print,
                                       int extraction,
                                       int change,
                                       boolean encryptmetadata)
                                throws NoSuchAlgorithmException

      Set the access levels for Acrobat X and greater. Acrobat X encryption is identical to Acrobat 7 except that the key length for the AES block cipher is 256 bit rather than 128. Documents encrypted this way can only be opened with Acrobat X or later.

      Users of Sun JVMs will require the "unlimited strength" policy files to use AES256 encryption, and other JVMs may have similar requirements.

      Parameters:
        `print` - one of `PRINT_NONE` `PRINT_LOWRES` `PRINT_HIGHRES`
        `extraction` - one of `EXTRACT_NONE` `EXTRACT_ACCESSIBILITY` `EXTRACT_ALL`
        `change` - one of `CHANGE_NONE` `CHANGE_LAYOUT` `CHANGE_FORMS` `CHANGE_ANNOTATIONS` `CHANGE_ALL`
        `encryptmetadata` - whether to encrypt the XMP metadata
      Throws:
        `NoSuchAlgorithmException` - if the AES cipher isn't available
      Since:
        2.11.23

    - #### getVersion

          public int getVersion()

      Return the version of the encryption algorithm used.
      Returns:
        1 for 40-bit RC4 as used by Acrobat 3 and later, 2 for 128-bit RC4 as used by Acrobat 5 and later, or 4 for the variant in Acrobat 6 or later and 5 for the variant in Acrobat 9 or later.
      Since:
        2.0

    - #### isOwnerPasswordKnown

          public boolean isOwnerPasswordKnown()

      Return true if the Owner password was used to open this PDF, false if the User password was used.
      Since:
        2.11.8

    - #### isMetadataEncrypted

          public boolean isMetadataEncrypted()

      Description copied from class: `EncryptionHandler`
      This method returns true if XMP MetaData should be stored encrypted, or false otherwise. The default implementation returns true, subclasses should override as necessary.
      Overrides:
        `isMetadataEncrypted` in class `EncryptionHandler`

    - #### isStreamEncrypted

          public boolean isStreamEncrypted()

      Description copied from class: `EncryptionHandler`
      This method returns true if Streams in the document should be stored encrypted. By default this method returns true.
      Overrides:
        `isStreamEncrypted` in class `EncryptionHandler`

    - #### isStringEncrypted

          public boolean isStringEncrypted()

      Description copied from class: `EncryptionHandler`
      This method returns true if Strings in the document should be stored encrypted. By default this method returns true.
      Overrides:
        `isStringEncrypted` in class `EncryptionHandler`

    - #### isEmbeddedFileEncrypted

          public boolean isEmbeddedFileEncrypted()

      Description copied from class: `EncryptionHandler`
      This method returns true if Embedded Files in the document should be stored encrypted. By default this method returns true.
      Overrides:
        `isEmbeddedFileEncrypted` in class `EncryptionHandler`

    - #### getChange

          public int getChange()

      Return the value of the "Change" flags
      Returns:
        one of `CHANGE_NONE` `CHANGE_LAYOUT` `CHANGE_FORMS` `CHANGE_ANNOTATIONS` or `CHANGE_ALL`
      Since:
        2.2.6

    - #### getExtract

          public int getExtract()

      Return the value of the "Extract" flags
      Returns:
        one of `EXTRACT_NONE` `EXTRACT_ACCESSIBILITY` `EXTRACT_ALL`
      Since:
        2.2.6

    - #### getPrint

          public int getPrint()

      Return the value of the "Print" flags
      Returns:
        one of `PRINT_NONE` `PRINT_LOWRES` `PRINT_HIGHRES`
      Since:
        2.2.6

    - #### hasRight

          public boolean hasRight(String right)

      Description copied from class: `EncryptionHandler`
      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"
      Overrides:
        `hasRight` in class `EncryptionHandler`
      Parameters:
        `right` - an interned() String defining the usage right the PDF library is querying.

    - #### getFilterName

          public String getFilterName()

      Description copied from class: `EncryptionHandler`
      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.
      Specified by:
        `getFilterName` in class `EncryptionHandler`

    - #### getSubFilterName

          public String getSubFilterName()

      Description copied from class: `EncryptionHandler`
      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`.
      Specified by:
        `getSubFilterName` in class `EncryptionHandler`

    - #### getDescription

          public String getDescription()

      Return a textual description of the algorithm used
      Since:
        2.8.2

    - #### isRequired

          public boolean isRequired()

      Description copied from class: `EncryptionHandler`
      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.
      Specified by:
        `isRequired` in class `EncryptionHandler`

    - #### getDecryptedStreamLength

          public int getDecryptedStreamLength(int len)

      Description copied from class: `EncryptionHandler`
      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.
      Overrides:
        `getDecryptedStreamLength` in class `EncryptionHandler`

    - #### getEncryptedStreamLength

          public int getEncryptedStreamLength(int len)

      Description copied from class: `EncryptionHandler`
      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.
      Overrides:
        `getEncryptedStreamLength` in class `EncryptionHandler`

    - #### getEncryptionStream

          public OutputStream getEncryptionStream(OutputStream out,
                                                  int num,
                                                  int gen)

      Description copied from class: `EncryptionHandler`
      Return a `FilterOutputStream` that will encrypt anything written to it. The encryption parameters are set in `EncryptionHandler.prepareToEncrypt()`, which is called once at the start of the render.
      Specified by:
        `getEncryptionStream` in class `EncryptionHandler`
      Parameters:
        `out` - the OuptutStream that should be written to
        `num` - the object number of the top-level object
        `gen` - the generation number of the top-level object

    - #### getDecryptionStream

          public InputStream getDecryptionStream(InputStream in,
                                                 int num,
                                                 int gen)

      Description copied from class: `EncryptionHandler`
      Return a `FilterInputStream` that will decrypt anything read from it. The decryption parameters are set in `EncryptionHandler.prepareToDecrypt()`, which is called once at the start of the PDF read.
      Specified by:
        `getDecryptionStream` in class `EncryptionHandler`
      Parameters:
        `in` - the InputStream that should be read from
        `num` - the object number of the top-level object
        `gen` - the generation number of the top-level object

    - #### prepareToDecrypt

          public void prepareToDecrypt()
                                throws IOException

      Description copied from class: `EncryptionHandler`
      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 `EncryptionHandler.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.
      Specified by:
        `prepareToDecrypt` in class `EncryptionHandler`
      Throws:
        `IOException`

    - #### prepareToEncrypt

          public void prepareToEncrypt()
                                throws IOException

      Description copied from class: `EncryptionHandler`
      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 `EncryptionHandler.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.
      Specified by:
        `prepareToEncrypt` in class `EncryptionHandler`
      Throws:
        `IOException`

    - #### finishedEncrypt

          public void finishedEncrypt()

      Description copied from class: `EncryptionHandler`
      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.
      Specified by:
        `finishedEncrypt` in class `EncryptionHandler`

    - #### finishedDecrypt

          public void finishedDecrypt()

      Description copied from class: `EncryptionHandler`
      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.
      Specified by:
        `finishedDecrypt` in class `EncryptionHandler`

Copyright © 2001-2015 Big Faceless Organization