org.faceless.pdf2
Class StandardEncryptionHandler

java.lang.Object
  extended by org.faceless.pdf2.EncryptionHandler
      extended by 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
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
StandardEncryptionHandler()
          Create a new StandardEncryptionHandler for encryption or decryption of documents.
 
Method Summary
 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

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-2013 Big Faceless Organization