org.icepdf.core.pobjects.security
Class StandardSecurityHandler

java.lang.Object
  org.icepdf.core.pobjects.security.SecurityHandler
      org.icepdf.core.pobjects.security.StandardSecurityHandler

All Implemented Interfaces:

SecurityHandlerInterface

public class StandardSecurityHandler
extends SecurityHandler

ICEpdf's standard security handler allows access permissions and up to two passwords to be specified for a document: an owner password and a user password. An application's decision to encrypt a document is based on whether the user creating the document specifies any passwords or access restrictions (for example, in a security settings dialog that the user can invoke before saving the PDF file); if so, the document is encrypted, and the permissions and information required to validate the passwords are stored in the encryption dictionary. (An application may also create an encrypted document without any user interaction, if it has some other source of information about what passwords and permissions to use.)

If a user attempts to open an encrypted document that has a user password, the viewer application should prompt for a password. Correctly supplying either password allows the user to open the document, decrypt it, and display it on the screen. If the document does not have a user password, no password is requested; the viewer application can simply open, decrypt, and display the document. Whether additional operations are allowed on a decrypted document depends on which password (if any) was supplied when the document was opened and on any access restrictions that were specified when the document was created:

• Opening the document with the correct owner password (assuming it is not the same as the user password) allows full (owner) access to the document. This unlimited access includes the ability to change the document's passwords and access permissions.
• Opening the document with the correct user password (or opening a document that does not have a user password) allows additional operations to be performed according to the user access permissions specified in the document's encryption dictionary.

Access permissions are specified in the form of flags corresponding to the various operations, and the set of operations to which they correspond, depends in turn on the security handler's revision number (also stored in the encryption dictionary). If the revision number is 2 or greater, the operations to which user access can be controlled are as follows:

• Modifying the document's contents
• Copying or otherwise extracting text and graphics from the document, including extraction for accessibility purposes (that is, to make the contents of the document accessible through assistive technologies such as screen readers or Braille output devices
• Adding or modifying text annotations and interactive form fields
• Printing the document

If the security handler's revision number is 3 or greater, user access to the following operations can be controlled more selectively:

• Filling in forms (that is, filling in existing interactive form fields) and signing the document (which amounts to filling in existing signature fields, a type of interactive form field)
• Assembling the document: inserting, rotating, or deleting pages and creating navigation elements such as bookmarks or thumbnail images
• Printing to a representation from which a faithful digital copy of the PDF content could be generated. Disallowing such printing may result in degradation of output quality (a feature implemented as "Print As Image" in Acrobat)

In addition, revision 3 enables the extraction of text and graphics (in support of accessibility to disabled users or for other purposes) to be controlled separately. Beginning with revision 4, the standard security handler supports crypt filters. The support is limited to the Identity crypt filter and crypt filters named StdCF whose dictionaries contain a CFM value of V2 and an AuthEvent value of DocOpen.

Since:

1.1

Field Summary

static Name	IDENTITY_KEY
static Name	NAME_KEY

Fields inherited from class org.icepdf.core.pobjects.security.SecurityHandler

encryptionDictionary, handlerName, permissions

Constructor Summary

StandardSecurityHandler(EncryptionDictionary encryptionDictionary)

Method Summary

byte[]	decrypt(Reference objectReference, byte[] encryptionKey, byte[] data) Decrypt the PDF data bytestream or string.
void	dispose() Dispose of the security handler.
byte[]	encrypt(Reference objectReference, byte[] encryptionKey, byte[] data) Encrypt the PDF data bytestream or string.
byte[]	getDecryptionKey() Gets the encryption key used by the security handler for decryption data.
java.io.InputStream	getEncryptionInputStream(Reference objectReference, byte[] encryptionKey, java.util.HashMap decodeParams, java.io.InputStream input)
byte[]	getEncryptionKey() Gets the encryption key used by the security handler for encrypting data.
java.lang.String	getHandlerName() Gets the name of the default security handler.
Permissions	getPermissions() Gets the PDF permissions object associated with this document's security handler.
void	init() Initiate the security handler
boolean	isAuthorized(java.lang.String password) Determines whether the supplied password is authorized to view the PDF document.
boolean	isOwnerAuthorized(java.lang.String password) Determines whether the supplied owner password is authorized to view the PDF document.
boolean	isUserAuthorized(java.lang.String password) Determines whether the supplied user password is authorized to view the PDF document.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

NAME_KEY

public static final Name NAME_KEY

IDENTITY_KEY

public static final Name IDENTITY_KEY

Constructor Detail

StandardSecurityHandler

public StandardSecurityHandler(EncryptionDictionary encryptionDictionary)

Method Detail

isAuthorized

public boolean isAuthorized(java.lang.String password)

Description copied from interface: SecurityHandlerInterface

Determines whether the supplied password is authorized to view the PDF document. If a password is rejected, the user should be restricted from viewing the document.

Specified by:

isAuthorized in interface SecurityHandlerInterface

Specified by:

isAuthorized in class SecurityHandler

Parameters:

password - password to authorize

Returns:

true, if the password was authorized successfully; false, otherwise.

isOwnerAuthorized

public boolean isOwnerAuthorized(java.lang.String password)

Description copied from interface: SecurityHandlerInterface

Determines whether the supplied owner password is authorized to view the PDF document. If a password is rejected, the user should be restricted from viewing the document.

Specified by:

isOwnerAuthorized in interface SecurityHandlerInterface

Specified by:

isOwnerAuthorized in class SecurityHandler

Parameters:

password - password to authorize

Returns:

true, if the password was authorized successfully; false, otherwise.

isUserAuthorized

public boolean isUserAuthorized(java.lang.String password)

Description copied from interface: SecurityHandlerInterface

Determines whether the supplied user password is authorized to view the PDF document. If a password is rejected, the user should be restricted from viewing the document.

Specified by:

isUserAuthorized in interface SecurityHandlerInterface

Specified by:

isUserAuthorized in class SecurityHandler

Parameters:

password - password to authorize

Returns:

true, if the password was authorized successfully; false, otherwise.

encrypt

public byte[] encrypt(Reference objectReference,
                      byte[] encryptionKey,
                      byte[] data)

Description copied from interface: SecurityHandlerInterface

Encrypt the PDF data bytestream or string.

Specified by:

encrypt in interface SecurityHandlerInterface

Specified by:

encrypt in class SecurityHandler

Parameters:

objectReference - reference to PDF object being encrypted; this object contains the PDF object number and revision.

encryptionKey - encryption key used by encryption algorithm.

data - byte data to be encrypted; either represents an object stream or string value.

Returns:

the encrypted stream or string byte data

decrypt

public byte[] decrypt(Reference objectReference,
                      byte[] encryptionKey,
                      byte[] data)

Description copied from interface: SecurityHandlerInterface

Decrypt the PDF data bytestream or string.

Specified by:

decrypt in interface SecurityHandlerInterface

Specified by:

decrypt in class SecurityHandler

Parameters:

objectReference - reference to PDF object being encrypted; this object contains the PDF object number and revision.

encryptionKey - encryption key used by decryption algorithm.

data - byte data to be decrypted; either represents an object stream or string value.

Returns:

the decrypted stream or string byte data

getEncryptionInputStream

public java.io.InputStream getEncryptionInputStream(Reference objectReference,
                                                    byte[] encryptionKey,
                                                    java.util.HashMap decodeParams,
                                                    java.io.InputStream input)

Specified by:

getEncryptionInputStream in interface SecurityHandlerInterface

Specified by:

getEncryptionInputStream in class SecurityHandler

getEncryptionKey

public byte[] getEncryptionKey()

Description copied from interface: SecurityHandlerInterface

Gets the encryption key used by the security handler for encrypting data.

Specified by:

getEncryptionKey in interface SecurityHandlerInterface

Specified by:

getEncryptionKey in class SecurityHandler

Returns:

byte data representing encryption key

getDecryptionKey

public byte[] getDecryptionKey()

Description copied from interface: SecurityHandlerInterface

Gets the encryption key used by the security handler for decryption data.

Specified by:

getDecryptionKey in interface SecurityHandlerInterface

Specified by:

getDecryptionKey in class SecurityHandler

Returns:

byte data representing encryption key

getPermissions

public Permissions getPermissions()

Description copied from interface: SecurityHandlerInterface

Gets the PDF permissions object associated with this document's security handler.

Specified by:

getPermissions in interface SecurityHandlerInterface

Specified by:

getPermissions in class SecurityHandler

Returns:

security handlers permissions object

getHandlerName

public java.lang.String getHandlerName()

Description copied from interface: SecurityHandlerInterface

Gets the name of the default security handler.

Specified by:

getHandlerName in interface SecurityHandlerInterface

Specified by:

getHandlerName in class SecurityHandler

Returns:

string representing security handler name

init

public void init()

Description copied from interface: SecurityHandlerInterface

Initiate the security handler

Specified by:

init in interface SecurityHandlerInterface

Specified by:

init in class SecurityHandler

dispose

public void dispose()

Description copied from interface: SecurityHandlerInterface

Dispose of the security handler.

Specified by:

dispose in interface SecurityHandlerInterface

Specified by:

dispose in class SecurityHandler