TUTORIALS

 How to use password security

As easy as 1, 2, 3...

Introduction

In the following sections we will show how to use Password Security to apply permissions to a document and cipher its contents.

A typical protected document is secured using two passwords:

1. The user password: Used by readers, it can eventually be left empty to allow public access.
2. The author password: Used by the author who, implicitly, has all permissions.

Opening a ciphered document

The code below will open the file using the given password.

// Open a protected document:
PasswordCredentials openCredentials = new PasswordCredentials("myPassword");
PdfDocument docSrc= new PdfDocument("MyCipheredDocument.pdf", openCredentials );

Please note that if the password is incorrect, jPDF Viewer will show a dialog box with a prompt for credentials. This behavior can be controlled by a setting in the ShowAuthenticationGUI property in the Preferences.

Creating a ciphered document

First, let's open the unprotected document we will be working on.

// Open the document to be encrypted:
PdfDocument docSrc= new PdfDocument("MyDocument.pdf");

Select the new permissions and encryption parameters

Now let's set the new permissions that will apply to standard users.
Permissions are set via different flags as summarized in the following table:

Attributes	Description
Assembly	The Assembly Permission includes: Pages insertion, rotation or deletion Bookmarks creation Thumbnail images creation NOTE: If the document is encrypted with a 40 bit key length or in a 1.3 PDF version compliant (Acrobat 3.0 or later), this attribute will be overwritten by the "Modification" one.
Extraction	Controls the right to copy/extract text and graphics contents. NOTE: If the document is encrypted with a 40 bit key length or in a 1.3 PDF version compliant (Acrobat 3.0 or later), this attribute will overwrite the one controlled by "Extraction for Screen Readers".
Extraction for Screen Readers	Controls the right to copy/extract text and graphics contents in support of accessibility to disabled users. NOTE: If the document is encrypted with a 40 bit key length or in a 1.3 PDF version compliant (Acrobat 3.0 or later), this attribute will be overwritten by the "Extraction" one.
Fill Form Field	Controls the right to fill form fields (and sign signatures). NOTE: If the document is encrypted with a 40 bit key length or in a 1.3 PDF version compliant (acrobat 3.0 or later), this attribute will be overwritten by the "Modification of Annotation" one.
Modification of Annotation	Controls the right to add/modify text annotations. NOTE: Allowing this permission along with the one controlled by the attribute "Modification" will allow the addition/modification of form fields.
Modification	Controls the right to modify the document via operations other than those controlled by: Modification of Annotation Fill Form Field Assembly NOTE 1: Allowing this permission along with the one controlled by the attribute "Modification of Annotation" will allow the addition/modification of form fields including signature. NOTE 2: If the document is encrypted with a 40 bit key length or in a 1.3 PDF version compliant (Acrobat 3.0 or later), this attribute will overwrite the one controlled by "Assembly".
Printing	Controls the right to print the document or not.
Printing Quality	This attribute controls the quality of the printout when printing permission is given. This can be set to High or Low Quality. NOTE: If the document is encrypted with a 40 bit key length or in a 1.3 PDF version compliant (Acrobat 3.0 or later), this attribute will be overwritten with the High Quality value.

In the example below, we want to allow printing only in high quality.
The document will be ciphered using password security.
We will define two sets of users: normal users who do not need any password to access the document ("") and authors (with the "admin" password).
Since we are using Password Security, we need to use a PasswordCredentialsCreation to hold this information.

The code then looks like this:

// Create the object containing all the permissions to be applied:
Preferences preferences = new Preferences();

// Allow printing rights only in High Quality:
Permissions permissions = new Permissions();
permissions.setDenyAll();
permissions.setCanPrint(true);
permissions.setPrintQuality(Permissions.QUALITY_HIGH);

// Create the password credentials:
PasswordCredentialsCreation credentials = new PasswordCredentialsCreation("admin", "", permissions);
preferences.setDefaultCredentials(credentials);

Pick the encryption and authentication types

The document will be ciphered using RC4-128 with password security. But we could use different parameters.

Encryption Type	Key length	Description
ENCRYPTION_RC4	40	This is the legacy encryption which appeared in earlier versions of PDF. It is now considered weak and should be avoided in favor of AES.
ENCRYPTION_RC4	128	Ron's Code 4 (RC4) using a 128 bits key - provides decent encryption level.
ENCRYPTION_AES	128	Advanced Encryption Standard (AES) is the best encryption level available for PDF at this time. It can only be read by client applications that support PDF 1.5 or better (jPDF Viewer or Acrobat 7).

// Set the default encryption parameters:
preferences.setDefaultEncryptionKeyLength(128);
preferences.setDefaultSecurityType(Preferences.SECURITY_PASSWORD_PROTECTED);
preferences.setDefaultEncryptionType(Preferences.ENCRYPTION_RC4);

Process and save the new document

Now that the all settings are in place, we need only process the document. (Note that even if PDF supports incremental updates, it is not possible to have a document use different encryption types: the whole document must use the same settings. For this reason, when you change credentials or permissions, the whole file needs to be reprocessed.)

// Create the encrypted document:
document.getEncryptionModule().processTo(dst, preferences);

// Close the original document:
document.close();