The Security Framework in PDF Java Toolkit consists of two parts, Basic Support and Internal Support.

Basic Support provides encryption technologies which the Internal Support can use. It consists of interfaces and their limited implementations. The Security Framework allows sophisticated clients to extend Security Framework implementations or create their own Security implementations based on the Security Framework.

The Internal Support is based on the Security Framework and resides in the PDF Java Toolkit COS layer. It performs the necessary setup and actual decryption and encryption of the PDF content. The Internal Support and COS layers are not available to users of PDF Java Toolkit.

Basic Support

In order to satisfy the requirement that security support can be easily removed from the PDF Java Toolkit distribution without recompiling the code, the basic support is divided between two packages, securityframework and encryption. The security- framework package contains mainly interfaces that allow the PDF Java Toolkit’s code to communicate with the other package classes and methods using reflection. The encryption package contains actual implementation of the Security Framework. Both, the Basic and Internal Support, use each of these packages.

Security Handlers perform all actions related to decrypting/encrypting the content of a PDF document. First, they authenticate the right to access the document and calculate the base encryption key. Second, they perform the actual decryption/encryption using the calculated encryption key. Crypt Filters are extensions of the Security Handlers.

In the Security Framework, securityframework.SecurityHandler class combines functionality of the PDF Security Handlers and Crypt Filters. At the same time, for implementation reasons, PDF Java Toolkit Security Framework’s Security Handlers separate the actions that PDF Security Handlers perform in two parts, SecurityHandler and EncryptionHandler. The interfaces that define these two parts are located in the security framework package.

SecurityHandler is the main class in the Security Framework. It authenticates the right to access the document and calculates the base encryption key. The SecurityHandler also instantiates the appropriate Encryption Handler. The Security Framework implementation provides separate versions of the same Security Handler for all supported Crypt Filters. The implementation of a SecurityHandler supports both, decryption and encryption of a PDF document, in the same SecurityHandler instance.

Since different security handlers may employ the same decryption/encryption algorithm, a separate securityframework.EncryptionHandler class implements the actual decryption and encryption actions. Separation of these two types of functions between Security Handler and Encryption Handler is done for pragmatic reasons so that different security handlers can reuse the same encryption algorithms implemented in Encryption Handlers.

Because different streams in the same PDF document may use different Crypt Filters, there is a need to coordinate the use of different Security Handlers that represent these Crypt Filters while processing the same PDF document. SecurityManager class registers available security handlers and delivers the requested one.

The Security Framework contains Security Manager, Security Handler and Encryption Handler interfaces and also some of their implementations.

Encryption Permissions Handling

Security Handlers are responsible for the encryption permissions handling. Security Framework defers details of the encryption permissions handling to the specific implementations of the SecurityHandlers. At the same time, Security Handler implementation is required to return PermissionProvider that defines encryption permissions for the document that this Security Handler processes.

Communication between the Internal and the Basic Support

The ISO 32000 Reference specifies that security/encryption-related parameters are located in the / Encrypt dictionary (see Section 7.6, “Encryption,” page 55). This document is found on the web store of the International Standards Organization. The division of the security/encryption-related work between the basic and internal support requires exchange of these parameters between them. In many cases the basic support does not have access to the PDF data structures internal to PDF Java Toolkit. Therefore, some transformation of this information is necessary when it is exchanged between the internal and external code.

The Java Map interface (HashMap object) is used to communicate the security and encryption-related information between the PDF Java Toolkit and external handlers. To achieve this goal, the values of the CosDictionary entries and CosArray entries are transformed according to the following table.

The Map object’s keys are Java String objects representing the corresponding names in the PDF dictionaries. The array entries go through the same transformation and their order in the CosArray and ArrayList are the same. If a value of an entry is a CosDictionary, it goes through the same transformation and the resulting HashMap is the value of the corresponding entry.