
Adobe Acrobat SDK
Working with Document Security
Developing Plug-ins and Applications
Setting security for a document 159
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
PDCryptHandlerRec
:
1.
PDCryptNewSecurityDataProc
creates 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” on page 178
.
2.
PDCryptUpdateSecurityDataProc
gets the current security data structure by invoking the
PDDocGetNewSecurityData
method. 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 plug-in 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.
3.
PDCryptFillEncryptDictProc
writes data from the security data structure into the encryption
dictionary. When Acrobat is done with the security data structure, it invokes the
PDCryptFreeSecurityDataPro
c method.
Opening an encrypted file
The following callbacks are used when opening an encrypted file:
1.
PDCryptNewSecurityDataPr
oc is invoked as described in the previous section.
2.
PDCryptAuthorizeExProc
is invoked and returns NULL since the authorization permissions have
not been determined. This callback should not present a user interface.
3. The plug-in 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
PDCryptUpdateSecurityDataProc
in the previous section.
4.
PDCryptAuthorizeEx
or
PDCryptAuthorize
. The authorization permissions have now been
established (by the call to get the authorization data) and are returned. Acrobat opens the file.