com.adobe.internal.pdftoolkit.core.securityframework

Interface SecurityHandler

public interface SecurityHandler

SecurityHandler performs the main actions required to decrypt or encrypt a PDF document. In the case of decryption, the SecurityHandler authenticates the right to decrypt the document. For example, password-based SecurityHandler validitates the password in the process of authentication.

SecurityHandler also delivers (on decryption) or determines (on encryption) encryption permissions. For the password-based security handlers, this is the content of the /P entry in the Encrypt dictionary; the public-key-based security handlers get the encryption permissions from the proper PKCS#7 object in the Recipients array in the Encrypt dictionary. Other security handlers implementations may get/set encryption permissions as they deem appropriate. Therefore the SecurityHandler interface contains the method that returns PermissionsProvider that handles encryption permissions.

SecurityHandler declares the interfaces for a specific security handler in a PDFDocument.

The security handler provides the following functionality:

• Authenticates the access rights to an encrypted PDF document.
• Computes the base encryption key.
• Computes the object-specific encryption key for each PDF object (String or Stream).
• Uses the object-specific encryption key to encrypt or decrypt (String or Stream) content.
• All Security Handler implementations must support Crypt filters listed in the Encrypt dictionary. Specifically, they must support Identity Crypt filter.

The PDF Java ToolKit provides the following password-based security handler.

• Standard This security handler provides support for RC4 and AES encryption technologies.

The names for other security handlers can be registered by using the procedure described in the PDF Reference, Appendix E.

Method Summary

Modifier and Type	Method and Description
boolean	authenticate(Map params, byte[] docID) Authenticates the right to decrypt and access the document.
boolean	authenticate(Map params, byte[] docID, DecryptedState decryptedState) Authenticates the right to decrypt and access the document by plugging in the decrypted state of the document.
DecryptedState	getDecryptedState() Returns decrypted state of the document.
EncryptionHandler	getEncryptionHandler(String cryptName, Map encryptParams, byte[] docId) Instantiates an encryption handler that performs the actual encryption/decryption operations with the base encryption key calculated by this security handler.
Map	getEncryptParameters() Get the encryption parameters specified by this Security Handler This can be either the original Encryption Parameters Map that were passed in the getEncryptionHandler(String, Map, byte[]) call with some entries possibly changed.
PermissionProvider	getPermissionProvider() Fetch the permission provider that specifies encryption permissions associated with this security handler.

Method Detail

getEncryptionHandler

EncryptionHandler getEncryptionHandler(String cryptName,
                                       Map encryptParams,
                                       byte[] docId)
                                throws PDFSecurityAuthorizationException,
                                       PDFSecurityConfigurationException

Instantiates an encryption handler that performs the actual encryption/decryption operations with the base encryption key calculated by this security handler. To implement this, Security Handler should authenticate the access rights to the encrypted document before it instantiates the encryption handler.

Parameters:

cryptName - the name of the Crypt Filter

encryptParams - the Encryption Parameters Map containing encryption parameters for encryption. Depending on the implementation it may or may not be the same Encryption Parameters Map used in decryption. SecurityHandler may cache or discard it.

docId - the first Document ID string in the PDF document’s trailer.

Returns:

EncryptionHandler encryption handler that performs encryption/decryption for this security handler. This handler may be cached by the Security Handler for reuse as required.

Throws:

PDFSecurityAuthorizationException

PDFSecurityConfigurationException

See Also:

authenticate(Map, byte[])

getEncryptParameters

Map getEncryptParameters()

Get the encryption parameters specified by this Security Handler This can be either the original Encryption Parameters Map that were passed in the getEncryptionHandler(String, Map, byte[]) call with some entries possibly changed. It could also be a completely new Map created in the SecurityHandler and used to encrypt content.

Security Handler should not change Encryption Parameters Map used to decrypt the content

In instances of the Security Handler for decryption this method may return null because no encryption parameters were saved.

Returns:

Map that contains encryption parameters.

authenticate

boolean authenticate(Map params,
                     byte[] docID)
              throws PDFSecurityAuthorizationException,
                     PDFSecurityConfigurationException

Authenticates the right to decrypt and access the document.

This method is usually called for the default Security Handler by the Security Support implementation to ensure the ability to process PDF document. Because particular streams may use different Security Handlers for encryption (or decryption), the authentication of these Security Handlers may happen, depending on the implementation, in the getEncryptionHandler(String, Map, byte[]) call.

Parameters:

params - the Encryption Parameters Map containing encryption parameters for encryption. Depending on the implementation it may or may not be the same Encryption Parameters Map used in decryption.

SecurityHandler may cache or discard the parameters map.

docID - the first Document ID string in the PDF document’s trailer.

Throws:

PDFSecurityAuthorizationException

PDFSecurityConfigurationException

getPermissionProvider

PermissionProvider getPermissionProvider()

Fetch the permission provider that specifies encryption permissions associated with this security handler.

authenticate

boolean authenticate(Map params,
                     byte[] docID,
                     DecryptedState decryptedState)
              throws PDFSecurityConfigurationException,
                     PDFSecurityAuthorizationException

Authenticates the right to decrypt and access the document by plugging in the decrypted state of the document.

Parameters:

params - the Encryption Parameters Map containing encryption parameters for encryption. Depending on the implementation it may or may not be the same Encryption Parameters Map used in decryption.

SecurityHandler may cache or discard the parameters map.

docID - the first Document ID string in the PDF document’s trailer.

decryptedState - Decrypted state of the document

Throws:

PDFSecurityAuthorizationException

PDFSecurityConfigurationException

getDecryptedState

DecryptedState getDecryptedState()

Returns decrypted state of the document. If authenticate method has not been called, then this method returns null.

Returns:

DecryptedState