Writing a Password exit

To encrypt PDF documents with passwords, you must write a Password exit. The Password exit provides passwords to the AFP to PDF transform.

The types of PDF passwords are:

User password

Lets someone open an encrypted PDF document. A user password is optional. If a user password is not specified, anyone can open the encrypted PDF document.

Owner password

Lets you restrict actions in an encrypted PDF document. The owner password also lets someone open an encrypted PDF document and bypass restrictions. An owner password is optional. However, it is required to restrict actions.

The Password exit can do these functions:

• Provide user and owner passwords:

  The AFP to PDF transform passes one or two identifiers to the Password exit as input -- a user identifier and an owner identifier. (The Password exit is called only when at least one identifier is specified.) Typically, job submitters specify these identifiers in job attributes. However, the administrator can also specify identifiers in printer definitions.

  Your installation can decide what identifiers to use. For example, identifiers can be z/OS® user IDs, email addresses, or a combination of different types of identifiers. See Input to the Password exit for rules pertaining to identifiers.

  The Password exit must return a password for each identifier that is passed as input to the exit. See Output from the Password exit for rules pertaining to passwords.

  To map identifiers to passwords, your Password exit can use a password database in any format. For example, your Password exit can use a password database that already exists for other purposes. Or, you could create a password database that only your Password exit uses.

  Tip:

  Your Password exit can return a password even when an identifier is not specified as input. For example, your Password exit could provide a default owner password when no owner identifier is specified.
• (Optional) Specify restricted actions:

  The AFP to PDF transform passes a list of restricted actions to the Password exit as input. The job submitter specifies the restricted actions in a job attribute, or the administrator can specify them in the printer definition. If no restricted actions have been specified for a job, the default is not to restrict actions. This default is passed to the exit.

  Your Password exit can change the restricted actions. However, if your Password exit restricts actions, it must also return an owner password.

Input to the Password exit

• Arguments (optional): You can define arguments in the AOP_PASSWORD_EXIT environment variable in the transform configuration file. For example, you might want to pass the name of the password database as an argument to your Password exit.
• User identifier (optional): The user identifier. This identifier can be specified either in the pdf-user-identifier job attribute or in the User identifier field in the printer definition. Although the user identifier is optional, the transform calls the Password exit only if a user identifier or owner identifier is specified.
• Owner identifier (optional): The owner identifier. This identifier can be specified either in the pdf-owner-identifier job attribute or in the Owner identifier field in the printer definition. Although the owner identifier is optional, the transform calls the Password exit only if a user identifier or owner identifier is specified.
• Protected actions (optional): A list of actions that are to be restricted in the PDF document. These restricted actions can be specified either in the pdf-protect job attribute or in the Protected actions field in the printer definition. For information about the values in this list, see the description of the pdf-protect job attribute in Job attributes for encrypting PDF documents.

Output from the Password exit

• User password (optional): The password for the user identifier.
• Owner password (optional): The password for the owner identifier.
• Protected actions: A list of actions that are to be restricted in the PDF document. For information about the actions that can be protected, see the description of the pdf-protect job attribute in Job attributes for encrypting PDF documents.

Sample Password exit

IBM® provides a sample Password exit and sample password database:

/usr/lpp/Printsrv/lib/aokpdfexit.dll

This sample Password exit looks up passwords in the sample password database and returns a password for each identifier that is passed to it as input. It does not change the restricted actions.

The sample Password exit accepts the name of the password database as an argument. If no argument is specified for the sample exit in the AOP_PASSWORD_EXIT environment variable, the exit looks for the database in /etc/Printsrv/aokpdfexit.db.

/usr/lpp/Printsrv/samples/aokpdfexit.db

A sample password database that maps identifiers to passwords. To use the sample database with the sample exit, copy it to /etc/Printsrv/aokpdfexit.db because the sample exit looks for the password database in that location.

IBM provides the source code for the sample Password exit (aokpdfexit.dll) in these files:

/usr/lpp/Printsrv/samples/aokpdfexit.h:

A header file that contains declarations and interface descriptions.

Rule:

Do not change the contents of this file.

/usr/lpp/Printsrv/samples/aokpdfexit.c

The source code for the sample Password exit.

Steps for writing and installing a Password exit

1. Modify file /usr/lpp/Printsrv/samples/aokpdfexit.c, which contains the source code for the sample Password exit.

   File /usr/lpp/Printsrv/samples/aokpdfexit.h contains declarations and interface descriptions.

   _______________________________________________________

2. Link your Password exit as a dynamic link library (DLL). Follow instructions in /usr/lpp/Printsrv/samples/aokpdfexit.h.

   _______________________________________________________

3. Mark the UNIX file or MVS™ data set that contains your Password exit program-controlled. If the Password exit is in a UNIX file, use the z/OS UNIX extattr command to do this.
   Example:

   exattr +p /etc/Printsrv/mypdfexit.dll
   Tip:

   To use the +p option of the extattr command, you must have at least READ access to the BPX.FILEATTR.PROGCTL FACILITY class profile.

   _______________________________________________________

4. Set the permissions so that the file is owned and executable by UID 0 and with no group or other permissions.
   Example:

   su
   chown 0 /etc/Printsrv/mypdfexit.dll
   chmod 700 /etc/Printsrv/mypdfexit.dll 

   Tip:

   To use the chown command, you must have an effective UID of 0. You can use the su command to switch to an effective UID of 0 if you are permitted to the BPX.SUPERUSER profile in the FACILITY class in RACF®.

   _______________________________________________________

5. Specify the name of the Password exit and optional arguments in the AOP_PASSWORD_EXIT environment variable in the transform configuration file, aopxfd.conf. For information, see Environment variables for the AFP to PDF transform.
   Example:

   environment={AOP_PASSWORD_EXIT –> "/etc/Printsrv/mypdfexit.dll"}

   Tip:

   To edit the transform configuration file, you must have an effective UID of 0.

   _______________________________________________________

6. If you switched to an effective UID of 0 in step 4, switch back to your own user ID.
   Example:

   exit

   _______________________________________________________

7. Restart the Transform Manager to pick up the changes to the transform configuration file and to load your Password exit. For example, use the AOPSTOP and AOPSTART JCL procedures to stop and restart the Transform Manager:

   START AOPSTOP,OPTIONS='-d xfd'
   START AOPSTART

   _______________________________________________________

Steps for writing a Password database

1. Create the password database. If you want to use the sample password database, copy it from /usr/lpp/Printsrv/samples/aokpdfexit.db to another directory and follow instructions in the sample database to add the user identifiers, owner identifiers, and passwords for your installation.
   Example:

   su
   cp /usr/lpp/Printsrv/samples/aokpdfexit.db /etc/Printsrv/aokpdfexit.db

   Tip:

   To copy the sample password database, you must have an effective UID of 0. You can use the su command to switch to an effective UID of 0 if you are permitted to the BPX.SUPERUSER profile in the FACILITY class in RACF.

   _______________________________________________________

2. Set the z/OS UNIX permissions of the database so that it is owned by UID 0 and with no group or other permissions.
   Example:

   su
   chown 0 /etc/Printsrv/mypdfexit.db
   chmod 700 /etc/Printsrv/mypdfexit.db

   Tip:

   To use the chown command, you must have an effective UID of 0. You can use the su command to switch to an effective UID of 0 if you are permitted to the BPX.SUPERUSER profile in the FACILITY class in RACF.

   _______________________________________________________

3. (Optional) If your password exit accepts the name of the password database as an argument, specify the argument in the AOP_PASSWORD_EXIT environment variable in the transform configuration file, aopxfd.conf.
   Example:

   The backslash in this example indicates that the text within the quotation marks continues on the next line:

   environment={AOP_PASSWORD_EXIT –> "/etc/Printsrv/mypdfexit.dll \
   /etc/Printsrv/mypdfexit.db"}

   Tip:

   To edit the transform configuration file, you must have an effective UID of 0.

   _______________________________________________________

4. If you switched to an effective UID of 0 in step 1 or step 2, switch back to your own user ID.
   Example:

   exit

   _______________________________________________________

5. If you modified the transform configuration file, restart the Transform Manager to pick up the changes. For example, use the AOPSTOP and AOPSTART JCL procedures to stop and restart the Transform Manager:

   START AOPSTOP,OPTIONS='-d xfd'
   START AOPSTART

   _______________________________________________________