Replaces PDCryptAuthorizeProc. PDPerms are obsolete, but Acrobat still supports old security handlers.

It is called whenever Acrobat needs to get authorization data and/or check permissions for operations.

A callback for PDCryptHandler. It is called by PDDocAuthorize() when a user tries to set security for an encrypted document and by a PDAuthProc() when a user tries to open a file.

It must decide, based on the contents of the authorization data structure, whether the user is permitted to open the file, and what permissions the user has for this file. The authorization data structure is available for making this decision. Alternate implementations may not require authorization data and may, for example, make authorization decisions based on data contained in the security data structure (use PDCryptNewSecurityDataProc()).

This callback must not obtain the authorization data (for example, by displaying a user interface into which a user can type a password). Obtaining authorization data is handled by the security handler's PDCryptGetAuthDataProc(), which must be called before this callback. Instead, PDCryptAuthorizeProc() must work with whatever authorization data is passed to it.

It is legitimate for this callback to be called with NULL authorization data; the Acrobat viewer's built-in authProc does this in order to support authorization methods that do not require authorization data.

When this callback is invoked to determine whether a user is permitted to open a file, permWanted is set to pdPermOpen. In this case, the file's contents are not yet decrypted (since this callback is being asked to permit decryption), and some calls must be avoided. For example, a call that causes a page to be parsed results in an error, since the encrypted contents are parsed. In general, it is safe to obtain information about the presence or absence of things, or the number of things, and to examine any part of a document at the Cos level.

A callback for PDCryptHandler. It is called when an encrypted document is saved. It fills the document's Encryption dictionary with whatever information the security handler wants to store in the document.

Normally this callback is called after PDCryptUpdateSecurityDataProc(). The security data structure can be obtained with a call to PDDocGetNewSecurityData(), and encryptDict is filled based on this data.

The sequencing of events that the viewer performs during creation of the encryptDict is as follows:

• The viewer creates the encryptDict.
  
• The viewer adds the Filter attribute to the dictionary.
  
• The viewer calls this PDCryptFillEncryptDictProc() to allow the security handler to add its own attributes to the dictionary.
  
• The viewer calls the PDCryptNewCryptDataExProc() (the PDCryptNewCryptDataProc() if unsuccessful) to get the algorithm version, key, and key length.
  
• The viewer checks if the V attribute has been added to the dictionary and, if not, it sets V to the algorithm version.
  
• The viewer sets the Length attribute if V is 2 or greater.
  
• The viewer adds the encryptDict to the document.
  

(Optional) A callback for PDCryptFilterHandler. Callbacks that conform to this prototype are called to encrypt or decrypt streams from a document.

The first call to a procedure of this type must fill out an ASCryptStmRec structure with pointers to callback routines for various types of stream access; see ASCryptStmProcs().

Replaces PDCryptGetAuthDataProc(). It is called whenever Acrobat needs to get authorization data and/or check permissions for operations.

PDPerms are obsolete. Acrobat provides permission controls, but Acrobat still supports old security handlers.

A callback for PDCryptHandler. This callback is called from a PDAuthProc when a file is opened after PDCryptNewSecurityDataProc() is called.

The callback must determine the user's authorization properties for the document by obtaining authorization data, such as a user interface log in or password entry. It populates an authorization data structure with this data.

This callback may call the security handler's PDCryptNewAuthDataProc() to allocate the authorization data structure. The use of an authorization data structure is optional (an implementation may wish to contain authorization data within the security data structure). The authorization data structure is subsequently used by the security handler's PDCryptAuthorizeProc() to determine whether the user is authorized to open the file.

A security handler can specify the standard password dialog box by using AVCryptGetPassword(). In this case, authData is a char *.

A callback for PDCryptHandler. This function should extract and return information about the document permissions to display for the user: whether the user can print, edit, copy text and graphics, edit notes and do form fill in and signing.

The permissions returned are logically AND-ed with the document permissions returned by any other permissions handlers, and displayed to the user. All crypt handlers should implement this call so that consolidated permissions can be displayed. To display your own crypt handler's permissions, implement PDCryptDisplaySecurityDataProc().

If this callback is absent, Acrobat assumes that all the operations on the document are allowed.

(Optional) A callback for PDCryptHandler. It is called by PDDocGetNewSecurityInfo(). It extracts the security information from the security data structure, and returns the security information.

This function is also used after a Save As... to reset the permissions according to the current document.

A default set of permissions is used if this callback is absent:

pdInfoCanPrint|pdInfoCanEdit|pdInfoCanCopy|pdInfoCanEditNotes

See PDPerms.

(Optional) A callback for PDCryptHandler. It creates a new empty authorization data structure. This structure is subsequently filled by PDCryptGetAuthDataProc(), then passed to PDCryptAuthorizeProc() and eventually to ASfree().

This callback is not called by the Acrobat viewer, but a security handler may use it if it wishes. The Acrobat viewer's standard security handler does not use this method.

A callback for PDCryptHandler. It sets up the key to be passed to initialize the RC4 cipher for encryption and decryption of a PDF file. It is called when an encrypted document is opened or saved.

The key is truncated when the length is greater than the viewer currently supports. Data is freed by PDCryptFreeCryptDataProc() if provided. Otherwise, ASfree() is used.

(Optional) A callback for PDCryptHandler. It creates and populates a new structure that contains whatever security-related information the security handler requires (for example, permissions, whether the file has owner and/or user passwords, owner and/or user passwords, or other data used internally by the security handler). If encryptDict is not NULL, the structure should be populated based on the encryptDict parameter's contents. This method is intended only to initialize the security data structure.

This callback is called under two circumstances:

• When a document is opened, it is called with encryptDict set to the document's Encryption dictionary. The handler should then populate the new security data structure with data that is obtained from the Encryption dictionary.
  
• When the user chooses a new encryption method, it is called without an encryptDict. The handler should return a security data structure with default values.
  

If a security handler does not have this callback, the document's newSecurityData field is set to NULL.

If a file is to be saved, then PDCryptUpdateSecurityDataProc() is subsequently called to allow user interface modification of the contents.

Security data is freed using PDCryptFreeSecurityDataProc(). If PDCryptFreeSecurityDataProc() is not defined, ASfree() is used.

A callback for PDCryptHandler. It updates the security data structure that was created by PDCryptNewSecurityDataProc(). This structure can be obtained by calling PDDocGetNewSecurityData(). The security data structure of the previously saved file can be obtained with a call to PDDocGetSecurityData().

The security data structure should be updated to reflect the encryption parameters that will be used when saving the file (this information is usually obtained via dialogs). The encryption parameters are transferred to the Encrypt dictionary by a subsequent callback to PDCryptFillEncryptDictProc().

The security data should be allocated by ASmalloc() or a related function. Security data is freed using PDCryptFreeSecurityDataProc(). If PDCryptFreeSecurityDataProc() is not defined, ASfree() is used.

The callback can also update the security handler itself. For example, the standard encryption handler switches to no encryption if no passwords or permissions are set in the security dialog box. Return ASAtomNull in cryptHandler if no encryption is used in the saved file.

(Optional) A callback for PDCryptHandler. It validates the security data structure, which specifies the user's permissions. This callback may modify the security data structure (for example, because the user is not authorized to change the security as they requested). A client may have called PDDocNewSecurityData() to obtain a new security data structure, then modified it, and then called PDDocSetNewSecurityData() to change the document security. This callback should be called before actually setting the document's security data.

This callback is not called automatically by the Acrobat viewer. It must be called, if desired, by the security handler's PDCryptUpdateSecurityDataProc().