Security Framework contains a hierarchical set of interfaces. These interfaces are located in the securityframework package.

Security Manager

The task of a Security Manager is to internally register provided instances of the security handlers, mapping these instances to their names, and to serve as a switchboard that delivers requested security handler. If the requested security handler is not registered with the Security Manager, the implementation may perform any action appropriate under specific circumstances. One of such actions could be throwing an exception.

The Security Manager interface contains the methods that allow the caller to register an instance of a Security Handler and to retrieve the requested Security Handler.

Security Manager’s constructor accounts for the specifics of its implementation. Security Framework does not specify any limitations or restrictions on how a Security Manager instance gets constructed.

This interface contains constructors that accept information necessary for the authentication of the access rights (passwords, certificates, and so forth). The exact composition of these constructors depends on the nature of both the security handlers and the implementation. The implementations of this interface conform to the implementations of the security handlers that the SecurityManager implementations instantiate.

Many implementations of security handlers are document-specific. It means that an instance of a security handler can be applied only to one PDF document. This is, for instance, the case for the password-based security handlers. If a document-specific security handler instance is registered with the Security Manager instance, this makes this Security Manager instance also document-specific.

Since the same instance of a Security Handler must return Encryption Handler for both decryption and encryption, the same instance of a Security Manager can be used for both decryption and encryption.

Security Handler

The main purpose of the Security Handler is to authenticate the right to access the document for decryption or to determine necessary encryption parameters and to instantiate an instance of the associated Encryption Handler. The implementation of a Security Handler must handle both decryption and encryption in the same instance.

Additionally, the Security Handler 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 handler implementations may get/set encryption permissions as they deem appropriate. Therefore, the SecurityHandler interface contains the method that returns permissions.PermissionsProvider that handles encryption permissions.

Security Handler interface contains methods that allow the caller to authenticate the right to decrypt the document and to get the associated Encryption Handler.

Since Security Handler may alter the Encryption Parameters Map that represents the / Encrypt dictionary, the Security Handler interface contains the method that returns the current state of the Encryption Parameters Map.

The specifics of an implementation of a Security Handler are taken care of in its constructor just as they are for the Security Manager. Security Framework does not specify any limitations or restrictions on how a Security Handler instance gets constructed. For example, the constructor of a password-based security handler may take as its parameters a single password (for decryption) or two passwords, owner and user passwords (for encryption).

Implementing a new Security Handler

The interfaces described in the following sections reside in the securityframework package. Generally, a user who wishes to implement a new Security Handler performs the following steps.

• Creates an implementation of a SecurityHandler. This implementation can extend an existing implementation class (see PBSHStandardCipher).
• Creates a new implementation of the EncryptionHandler or uses an implementation of an existing EncryptionHandler. SecurityHandler implementation created in the previous step will return this EncryptionHandler implementation in its getEncryptionHandler() implementation class
• Creates a new implementation of a SecurityManager which instantiates the newly implemented SecurityHandler. This implementation of the SecurityManager may extend an existing SecurityManager implementation (see StandardCipherSecurityManager).

Depending on the implementation of the security manager the implementations of this interface may contain constructors that accept information necessary for the authentication of the access rights (passwords, certificates, and so forth). The exact composition of these constructors depends on the nature of both the security handlers and the implementation of the security manager.

Encryption Handler

As discussed in the “Security Handler” section above, Encryption Handler is just a part of the Security Handler separated from the Security Handler only to facilitate the reuse of the same encryption technology by different security handlers. The EncryptionHandler interface contains methods used to decrypt and encrypt PDF strings and streams. These methods take as a parameter addition to the base encryption key calculated in the Security Handler. This addition is based on the object number/generation number of the respective PDF objects.

The constructor of an EncryptionHandler ought to take as parameters all necessary information and the implementation of an Encryption Handler should use this information appropriately. For instance, RC4 encryption handler’s implementation takes as a parameter in its constructor the base encryption key. It is the job of the security handler implementation that uses this implementation of the encryption handler to calculate the base encryption key as appropriate for this security handler.

This interface implements method is required to perform actual encryption/decryption operations according to a specific encryption algorithm. The implementations of this interface may contain constructors that accept certain parameters.