Working with Document Security¶
About document security¶
Encryption is controlled by an encryption dictionary in the PDF file. The Acrobat core API uses RC4 (a proprietary algorithm provided by RSA Data Security, Inc.) to encrypt document data, and a standard (proprietary) method to encrypt, decrypt, and verify user passwords to determine whether or not a user is authorized to open a document.
Each stream or string object in a PDF file is individually encrypted. This level of encryption improves performance because objects can be individually decrypted as needed rather than decrypting an entire file. All objects, except for the encryption dictionary (which contains the security handler’s private data), are encrypted using the RC4 algorithm Adobe licenses from RSA Data Security, Inc. A plugin may not substitute another encryption scheme for RC4.
A plugin that implements a security handler is responsible for encrypting the values it places into the encryption dictionary, and it may use any encryption scheme. If the security handler does not encrypt the values it places into the encryption dictionary, the values are in plain text.
The core API provides two Cos layer methods to encrypt and decrypt data using the RC4 algorithm. These methods are
CosDecryptData. (See the Acrobat and PDF Library API Reference.)
Security handlers may use these methods to encrypt data they want to put into the PDF file’s encryption dictionary and decrypt data when it is read from the dictionary. Security handlers may instead choose to ignore these methods and use their own encryption algorithms.
About security handlers¶
Application logic that performs user authorization and sets permissions is known as a security handler. Acrobat has these built-in security handlers: password, Adobe and public key security handler. (See the Acrobat and PDF Library API Reference.)
A security handler supports two passwords:
A user password that enables a user to open and read a protected document with whatever permissions the owner chose
An owner password that allows a document’s owner to also change the permissions granted to users
You can use the Acrobat core API’s built-in security handler or write your own security handlers to perform user authorization (for example, by the presence of a specific hardware key or file, or by reading a magnetic card reader).
Security handlers are responsible for performing the following tasks:
Setting permissions on a file
Authorizing access to a file
Setting up a file’s encryption and decryption keys
Maintaining the encryption dictionary of the PDF file containing the document
Security handlers are used in the following situations:
A document is opened. The security handler determines whether a user is authorized to open the file and sets up the decryption key that is used to decrypt the PDF file.
A document is saved. The security handler sets up the encryption key and writes extra security-related information into the PDF file’s encryption dictionary.
A user attempts to change a document’s security settings. The security handler determines whether the user is permitted to perform this task.
A document may have zero, one, or two security handlers associated with it. A document has zero security handlers if no security is used on the file. When security is applied to a file, or the user selects a different security handler for a secured file, the newly-chosen security handler is not put in place immediately. Instead this new security handler is simply associated with the document; it is a pending security handler until the document is saved.
The new security handler is not put in place immediately because it is responsible for decrypting the contents of the document’s encryption dictionary, and that dictionary is re-encrypted in the correct format for the new security handler only when the document is saved. As a result, a document may have both a current and a new security handler associated with it.
A security handler has two names: one that is placed in each PDF file that is saved by the handler (for example, ADBE_Crypt), and another name that Acrobat can use in any user interface items in which the security handler appears (for example, Acrobat Developer Technologies default encryption). This is similar to the two-name scheme used for menu items: a language-independent name that the application logic can refer to regardless of the user interface language, and another name that appears in the user interface. (See Adding menu commands to menus.)
Adding a security handler¶
You can add a security handler by performing the following tasks:
Writing a set of callback routines to perform security-related functions.
Specifying the callbacks in a
Registering the handler by passing the structure to
Security handlers data¶
The following list describes three types of data used by security handlers:
Authorization data is the data the security handler needs to determine the user’s authorization level for a particular file (for example, not authorized to open the file, authorized to access the file with user permissions, authorized to access the file with owner permissions). Passwords are a common type of authorization data.
Security data is whatever internal data the security handler uses. It includes security information, internal flag values, seed values, and so on.
Security information is a subset of the security data. Specifically, it is a collection of flags that contains the information that Acrobat uses to display the current permissions to the user. This information includes permissions and the user’s authorization level (user or owner).
Security handler callbacks¶
A security handler must provide callbacks that performs the following tasks:
Determines whether a user is authorized to open a particular file and what permissions the user has once the file is open (
Creates and fills an authorization data structure, using whatever user interface is needed to obtain the data. For example, displaying a dialog box into which the user can type a password (
Creates, fills, and verifies a security data structure (
Extracts security information from the security data structure (
Allows the user to request different security settings, usually by displaying a dialog box. (
Sets up the encryption key used to encrypt the file (
Fills or reads the PDF filefs encryption dictionary (
Displays the current document’s permissions (required with
With Acrobat 5.0 and later, a finer granularity of permissions has been predefined for objects supported by a PDF document. Plugins can invoke the
PDDocPermRequest method to request whether a particular operation is authorized to be performed on a specified object in a document.
To support the
PDDocPermRequest method, there are two new callback methods:
PDCryptGetAuthDataExProc. Acrobat 5.0 and later also includes optional security handling for batch operations (actions on one or more files). There are a number of callbacks (indicated by PDCryptBatch… ) that a security handler must provide to support batch processing. These callbacks are part of a
PDCryptBatchHandler structure. The
PDCryptHandlerRec structure contains a new member
CryptBatchHandler, which points to this structure.
To support batch processing, a security handler should provide a non-NULL value for
CryptBatchHandler and implement the batch callbacks. Prior to Acrobat 5.0, the maximum length of the encryption key that Acrobat accepted was 40 bits. Acrobat version 5.0 or later accommodates an encryption key length of 128 bits. These length limitations are imposed to comply with export restrictions.
Opening a secured file¶
The Acrobat core API has several methods for opening files. The
PDDocOpenEx ) method is used to open PDF files, even when a plugin calls AV layer methods such as
AVDocOpenFromASFileWithParams. As a result, the sequence of operations is largely the same regardless of whether the document is being opened from the PD layer or from the AV layer. The difference is that if you call
PDDocOpen directly, you must pass your own authorization procedure (
PDAuthProc ), while AV layer methods always use Acrobat’s built-in authorization procedure.
The authorization procedure must implement the authorization strategy, such as giving the user three chances to enter a password. The
PDAuthProc is not part of a security handler, but it must call the security handler’s methods to authorize the user (for example, to get the password from the user and to check whether or not the password is valid).
Acrobat performs the following steps to open a secured PDF file:
Searches for an Encrypt key in the PDF document’s trailer, to determine whether or not the document is encrypted. If there is no Encrypt key, Acrobat opens the document immediately.
If there is an Encrypt key, its value is an encryption dictionary. Acrobat gets the value of the Filter key in the dictionary to determine which security handler was used when the file was saved. It looks in the list of registered security handlers (which contains Acrobat’s built-in handler and any handlers that plugins or applications have registered) for one whose name matches the name found in the PDF file. For information about a dictionary, see Working with Cos dictionaries.
If Acrobat finds no match, indicating that the necessary handler could not be found, it does not open the document. If it finds a matching security handler, it invokes that handler’s P
DCryptNewSecurityDataProccallback to extract and decrypt information from the PDF file’s encryption dictionary.
Acrobat invokes the security handler’s authorize callback (
PDCryptAuthorizeExProc) with NULL authorization data, and with the requested permissions set to
pdPermOpen(requesting that the user be allowed to open the file). This allows support for authorization schemes that do not need authorization data.
If authorization succeeds, the handler’s authorization callback must return the
PDPermReqStatus(when the callback is
pdPermOpen(when the callback is
PDCryptAuthorizeProc) indicating that the user is permitted to open the file.
If authorization fails, the authorization procedure passed in the call to open the
If authorization still fails, the file is not opened.
If authorization succeeds, Acrobat calls the security handler’s
PDCryptNewCryptDataProccallback to create the decryption key that is used to decrypt the file. The
PDCryptNewCryptDataProccallback can construct the decryption key in any way it chooses, but generally performs some calculation based on the contents of the security data structure filled previously by the handler’s
Saving a secured file¶
When saving a file, it is important to remember the following information:
When a user selects document encryption for the first time or has selected a different security handler for an already encrypted file, the newly-selected handler does not take effect until the document is saved.
To be allowed to save a file, the user must have
In Acrobat 5.0, a save operation forces a complete encrypted copy of the file to be written.
The following information is applicable to when a secured file is saved:
If the file is being saved in an encrypted form for the first time or if a different security handler is selected, Acrobat calls the new security handler’s
PDCryptNewSecurityDataProccallback. This action creates a new copy of the new security handler’s security data structure.
If the file is saved in an encrypted form for the first time or if a different security handler is selected, Acrobat calls the new security handlerfs
PDCryptUpdateSecurityDataProccallback. This presents whatever user interface the security handler has for enabling the user to set permissions.
Acrobat invokes the new security handler’s
PDCryptFillEncryptDictProccallback to encrypt and write into the PDF file’s encryption dictionary whatever data the security handler wants to save in the PDF file.
Acrobat writes out the encrypted file.
Acrobat sets the new security handler as the document’s current security handler.
Setting security for a document¶
Acrobat calls the new security handler’s
PDCryptUpdateSecurityDataProc callback to present whatever user interface the security handler has for allowing the user to set security, passwords, and so forth.
When security is set, the security handler obtains the permissions and authorization data (such as passwords) to be used for the file. The settings do not take effect until the file is saved, as described in the previous section.
Saving a file with an encryption dictionary¶
To save a file with a new encryption dictionary, use the following callbacks in the
PDCryptNewSecurityDataProccreates and initializes a security data structure. It is called with
encryptDict(a Cos object) set either to NULL or to a valid encryption dictionary, in which case the fields of the encryption dictionary are read and placed into the security data structure. For information about a Cos object, see Working with Cos Objects.
PDCryptUpdateSecurityDataProcgets the current security data structure by invoking the
PDDocGetNewSecurityDatamethod. It then makes a copy of the structure with which to work. This new copy is freed if an error or cancel condition is encountered. The user is requested to log in to their PKI infrastructure to access the user’s keys and certificates.
If the security data structure was seeded with information from
encryptDict, an internal authorize procedure is called. This procedure decrypts and examines the data fields in the security data structure copy that are set to indicate the user’s permissions and, possibly, information relating to the document symmetric key.
A user interface is provided to enable your plugin to specify a list of recipients for the document. If all goes well, the
secDataP argument to
PDCryptUpdateSecurityDataProc is sent to the copy of the security data structure, and Acrobat frees the original security data structure.
PDCryptFillEncryptDictProcwrites data from the security data structure into the encryption dictionary. When Acrobat is done with the security data structure, it invokes the
Opening an encrypted file¶
The following callbacks are used when opening an encrypted file:
PDCryptNewSecurityDataProc is invoked as described in the previous section.
PDCryptAuthorizeExProcis invoked and returns NULL since the authorization permissions have not been determined. This callback should not present a user interface.
The plugin does not use the authorization data structure, but instead only the security data structure. It calls an internal authorization procedure that determines the authorization level of the logged-in user. This authorization procedure is the same procedure as is called by
PDCryptUpdateSecurityDataProcin the previous section.
PDCryptAuthorize. The authorization permissions have now been established (by the call to get the authorization data) and are returned. Acrobat opens the file.