APCrypt Users Guide

# apcrypt - [options] [-o outFilePath] inPDFFile
Usage: apcrypt [options]

-keypath <string>   : Path to key location
-rc4                : Encrypt using the RC4 encryption algorithm
-aes                : Encrypt using the AES encryption algorithm
-keylength <int>    : Key Length.  Valid options are 40, 128 & 256.  Default is 128.

-ownerpass <string> : New Owner Password (Required)
-userpass <string>  : New User Password 

-onlyattach         : Encrypt attachments only; uses AES encryption algorithm. 

-noprint            : Do Not Allow Printing
-nomodify           : Do Not Allow Modifying the Document
-nocopy             : Do Not Allow Copying text or graphics
-nonotes            : Do Not Allow Adding or changing notes or form fields
-nofill             : Do Not Allow Fill or Sign of Form Fields
-noaccess           : Do Not Allow Accessibility
-noassembly         : Do Not Allow Document Assembly
-nohighres          : Do Not Allow High Resolution Printing

-remove             : Remove all encryption from the PDF document. (requires -d OwnerPassword)

-d <string>         : Old Owner Password to Decrypt the file

-optimize           : Combine -flate, -rascii, -nolzw, -optxobj, -optcontent and -optfonts

-nocomp             : Do not compress using Object Streams; compatible with all versions of Acrobat
-comp               : Compress using Object Streams; Acrobat 6 and later
-iso32000           : Set file for ISO 32000 compliance (PDF 1.7)

-w                  : Linearize saved file
-nomod              : Retain current file modification date
-o <string>         : New output file name, for multiple inputs, a path to an output directory
-l <string>         : Write progress to the given log file name
-p                  : Log progress information
-v                  : Print version information
-r <string>         : Application serial number
-h                  : Show help
-help               : Show help

Overview

APCrypt is a command-line driven server-based application that applies standard Acrobat security features to PDF documents quickly and efficiently. It is designed to run in tandem with other processes in an unattended environment able to handle high-volume and on-demand production needs. A copy of Adobe® Acrobat® is not needed in order for security to be applied.

Encryption Features

Encryption may be applied with 40, 128 or 256-bit security. Different security features are available at the different encryption levels. If a document is already encrypted, and has an Owner password, the document can be re-encrypted with different security options, or encryption can be removed completely.

At any encryption level, a password may be assigned. There are two types of passwords:

• User password: used to open a document
• Owner password: used to change permissions and passwords

When applying any security features, you must set an Owner password so that the settings can not be changed by other users.

At the 40-bit encryption level, the following security features are available:

• Do not allow printing
• Do not allow modifying the document
• Do not allow selecting text and graphics
• Do not allow adding or changing notes and form fields

At the 128-bit or 256-bit encryption level, these are the additional security features available:

• Do not allow fill-in or signing of form fields
• Do not allow accessibility
• Do not allow document assembly
• Do not allow high-resolution printing

As a server-based command-line driven application, APCrypt can be easily integrated into your scripts to add security to already processed documents.

Introduction

APCrypt is a command-line driven server-based application that applies standard Acrobat security features to PDF documents. APCrypt is designed to run in tandem with other processes in an unattended environment and to handle high-volume and on-demand production needs.

Memory Requirements

Minimum free memory available to run the application: 512 MBytes.

Windows Installation

Windows installation is handled by the installer and does not require any special handling.

Unix Installation

Setting environmental variables (All Unix Platforms)

In version 4.0 and higher, there are two additional environmental variables that need to be set for APCrypt on all UNIX platforms. If you run APCrypt from the apcrypt script created during installation, these environmental variables will be set by the script. If you run apcryptapp directly, you will need to set these environmental variables to run APCrypt. Once APCrypt is installed, you can view the variables needed by looking at the apcrypt script created by the installer.

Setting the Appligent home directory (All Unix Platforms)

The environmental variable that stores the location of the Appligent home directory is APPLIGENT_HOME. The default location for the Appligent home directory is /usr/local/appligent. The Appligent home directory contains the library files and resources needed to run APCrypt. It also contains license information for APCrypt.

Example:

export APPLIGENT_HOME=/usr/local/appligent

Setting the APDFL library path (All Unix except AIX)

The APDFL library path must be added to the LD_LIBRARY_PATH variable. The APDFL library path is located in a subdirectory of the APPLIGENT_HOME directory.

The path should be set to ${APPLIGENT_HOME}/APDFLX.X.X/Libs

Example:

export LD_LIBRARY_PATH=${LD_LIBRARY_PATH}:${APPLIGENT_HOME}/APDFLX.X.X/Libs

Setting the APDFL library path (AIX Only)

The APDFL library path for AIX must be added to the LIBPATH variable. The APDFL library path is located in a subdirectory of the APPLIGENT_HOME directory.

The path should be set to ${APPLIGENT_HOME}/APDFLX.X.X/Libs.

Example:

export LIBPATH=${LIBPATH}:${APPLIGENT_HOME}/APDFLX.X.X/Libs

Registration numbers for APCrypt 5.0

In previous versions of APCrypt, the APCrypt registration number was required as a command line option with the -r flag each time apcryptapp was run. An apcrypt script was provided that automatically added -r and the registration number to the apcryptapp command line when the script was run.

In the current release, in addition to getting the registration number from the command line, APCrypt can get the registration number from a license file in the appligent home directory. On unix systems, license files are created by the installation script and stored in the ${APPLIGENT_HOME}/license directory. For windows, the license file is created by the installer and stored in the All Users/Application Data/Appligent/License directory. With a valid license file, the -r is no longer required on the command line. The -r option can still be used as in previous versions, and will override the value in the license file.

To upgrade a Demo Version of APCrypt 5.0

As mentioned in the previous paragraph, registration numbers are now stored in the license directory. The license file for ApCrypt 5.0 is called APCT_50.arn. To upgrade a demo version of ApCrypt, change the demo number stored in the license file to your new registration number. If you call the apcryptapp executable with the -r option directly from a script or program that you wrote, update the number in that file.

Type apcrypt -v on the command line and press Enter. The new registration number, and a message that it is valid, should be displayed.

Supported Platforms

Windows: NT, 2000, XP, Vista & above
Linux:  64 bit
Solaris: 10 and above on SPARC

Introduction

The following general options deal with reporting, logging, and file maintenance.

Sample command

The following command displays usage information for APCrypt:

$apcrypt -h

Summary

The following table provides a summary of the general command-line options.

Detailed Options

The following sections provide details on using the general command-line options.

-r <RegNum> — Pass registration number to APCrypt

This option can be used to supply your registration number to APCrypt from a script or another application:

$apcryptapp -r XXXX-XXXX-XXXX-XXXX-XXXX-XXXX [other options]

This option is typically not necessary and is available for use in cases where the Appligent License File can not be located by the application because of runtime environment restrictions.

-l <logfile> — Log to a log file

Write to a text file any errors and/or progress messages. This option is helpful for debugging. The -l <logfile> option must be followed by a file name.

-p — Show progress

Write progress messages to the screen (STDOUT — the standard output of your system). This option is helpful for debugging and for understanding how the utility works.

A note on using -p and -l <logfile> together

As outlined in the above sections, the -p option gives you progress messages on your screen and the -l <logfile> option writes error messages to a file if errors occur. The following table provides more detail on using these options alone or together.

-l	-p	Errors	Results
			Nothing will be written to the screen or to the log file you specify.
			Progress messages will be written to the screen and apcrypt.log.
			Progress messages will be written to the screen and to the log file you specify.
			The utility will create an apcrypt.log file with the errors in your working directory.
			Errors will be written to the log file you specify.
			The utility will create an apcrypt.log file and write the errors  and progress messages to the file and your screen.
			Both progress and error messages will be written to the screen and to the log file you specify.

Therefore, -l <logfile> used on its own will only go into action if there are errors. With -p and -l <logfile> combined you will get a text file with full details on the utility operation whether there are errors or not.

-v — Print version information

Display the version of the utility you are running. This is important when corresponding with Appligent support; in order to best understand your problem, we must know what version of the software you have. APCrypt will not do anything else if you use this option.

-h or -help — Show usage

Display all available options for the utility. APCrypt will not do anything else if you use either of these options.

-o <outFile.pdf> — Save to a new file or directory

Save the modified file as a new file. We recommend using this option so you do not overwrite your existing files. If you are processing more than one input file at a time, specify a directory to save the resulting files.

-w — Linearize the file upon save

Save the output file as a linearized document. Linearization reorganizes the file to make it more efficient for web delivery. Individual pages can be rendered before the entire document has downloaded, so the user can start reading the document sooner.

There are four options available in APCrypt 4.x and later.

-optimize — Optimize the file (optional)

This flag will do the following: 1) encode any non-encoded streams using Flate compression, 2) remove ASCII85 filters from all streams, 3) replace LZW encoded streams with Flate encoding, 4) merge identical XObjects and images, 5) optimize common sequences in page content, and 6) merge identical font descriptors and encodings. This option will usually result in a smaller file size.

-nocomp — Do not compress using Object Streams (optional)

This flag will not compress Object Streams, resulting in a document that is compatible with all versions of Acrobat.

-comp — Compress using Object Streams (optional)

This flag will compress Object Streams, resulting in a document that is compatible with Acrobat 6.0 and later.

-iso32000 — Set file for ISO 32000-1 compliance (optional)

This flag sets the file for compliance with ISO 32000-1:2008 (PDF 1.7).

Using Command-Line Options

Command syntax

$apcrypt [options] input1.pdf [input2.pdf...]

Refer to General Command-Line Options for details on the general options.
Refer to Applying Standard Security for more information about the encryption options.

Running APCrypt

Applying encryption to a document

The following examples use the sample files securitysample1.pdf and securitysample2.pdf in the Samples subdirectory. The examples assume you are in the directory where you installed APCrypt. On Windows, the default location is C:\Appligent\APCrypt.  On Unix, it is wherever you installed APCrypt.

Applying 256-bit encryption to an unencrypted document

Use the -p flag to show progress, and the -o flag to specify an output file so the input PDF file will not be overwritten.

$apcrypt -p -o ./Samples/out_securitysample1.pdf -aes -keylength 256
-ownerpass Pa55w0rd -userpass paSsWoRd -noprint
./Samples/securitysample1.pdf

The out_securitysample1.pdf will be a new PDF document, encrypted with 256-bit encryption, with owner and user passwords. It will not allow you to print the document.

Applying 128-bit encryption to an unencrypted document

Use the -p flag to show progress, and the -o flag to specify an output file so the input PDF file will not be overwritten.

$apcrypt -p -o ./Samples/out_securitysample2.pdf -aes -keylength 128
-ownerpass Pa55w0rd -userpass paSsWoRd -nomodify -nohighres -nocopy
./Samples/securitysample2.pdf

The out_securitysample1.pdf will be a new PDF document, encrypted with 128-bit encryption, with owner and user passwords. It will not allow changes, high resolution printing, or copying the document.

Applying 40-bit encryption to a previously encrypted document

Use the -p flag to show progress, and the -o flag to specify an output file so the input PDF file will not be overwritten.

$apcrypt -p -o out_reencrypted.pdf -keylength 40 -d oldPassword
-ownerpass PaSsWoRd -noprint -nomodify -nocopy
./Samples/out_securitysample1.pdf

The out_reencrypted.pdf will be a new PDF document secured with 40-bit encryption and an owner password against printing, modifying and copying the document.

Removing encryption from a document

Use the -remove option to remove encryption from a document. Use the -p flag to show progress, and the -o flag to specify an output file so the input PDF file will not be overwritten.

$./apcrypt -p -remove -o ./Samples/Testfiles/out_securityremoved.pdf
-d oldpassword ./Samples/out_securitysample1.pdf

Introduction

This section describes the apcrypt command syntax and summarizes the options you can use with the apcrypt command.  Command-line syntax in the tables below refer to a path to any input or output file.  In the Windows environment, directory paths use a back slash “\” character. In the UNIX/Mac OS X environment, directory paths use a forward slash “/” character. Examples in the tables below show a Windows type path.

The following is an example of paths to the default installation directory for APCrypt:

Windows

> C:\Appligent\APCrypt\

UNIX

$ /Appligent/APCrypt/

Command Syntax

$apcrypt [options] path\inFilename.pdf [inFilename.pdf...]

Product Information Options

The following table describes options you can use to obtain information about APCrypt.  For more information about these options, see Introduction to APCrypt.

Input and Output Options

The following table describes the options for managing file input and output. For more information about these options, see General Options – APCrypt.

Reporting Options

The following table describes the options for reporting progress and error messages. These options are helpful for debugging and understanding how APCrypt works. For more information about these options, see General Options – APCrypt.

Registration Number

The following table describes how to pass the registration number to APCrypt. For more information about this option flag, see General Options – APCrypt.

Encryption Options

The following table describes how to use the encryption options available with APCrypt. For more information about these options, see Applying Standard Security – APCrypt.

40-bit permissions

The following table describes the security provided by 40-bit encryption options.  For more information about these options, see Applying Standard Security – APCrypt.

128-bit and 256-bit permissions

The following table describes the additional security options provided by 128-bit encryption options.  For more information about these options, see Applying Standard Security – APCrypt.

APCrypt within a Document Processing and Delivery Solution

Adding security to a document should generally be the last step of processing. Appligent has available several products for processing PDF documents. Any of these, or a combination, could be used before applying security features with APCrypt. The products available are as follows:

• AppendPDF Pro — Append several PDF documents or pages of documents together to produce one complete document. Add a cover page and a table of contents, as well as text and/or image stamps to any of the pages.
• FDFMerge — Merge PDF forms together with FDF or XFDF data files to create a completed form. With FDFMerge’s form-flattening feature, form fields are removed making the output document more portable and less easily modified.
• StampPDF Batch — Add text to PDF documents as headers or footers, watermarks, etc., which can include page numbers, date/time, file names, and more. Stamps can be in any RGB color, Adobe PostScript Type 1 font, point size, and position. They can be overlaid or underlaid text, outline text, invisible text and/or multi-line.

The following is a graphical example of using APCrypt as part of a document processing solution that uses AppendPDF and StampPDF Batch before using APCrypt to add security features. (The work done by AppendPDF and StampPDF Batch could also be done by using the single product AppendPDF Pro.) Once the document is secured, it is ready for delivery.

Using APCrypt after document processing and before delivery

Using APCrypt in a Perl Script

Using APCrypt within a Perl script requires a simple system call. Below we show first a call to StampPDF Batch where a document, file1.pdf, is applied with stamps as specified in stampfile.txt. Following that is a call made to APCrypt where standard security features are applied to the file file1.pdf (do not allow printing, allow only form fill-in or signing). Owner and user passwords are set to owner and user, respectively.

system "stamppdf stampfile.txt file1.pdf"; system "apcrypt -ownerpass owner
-userpass user -o outfile.pdf -keylength 40 -noprint -nomodify -nocopy
-nonotes file1.pdf";

If you use Perl to write a script that uses APCrypt, make a call to the application in the format shown above.

Example scripts may be found on the Appligent web site.

Introduction

APCrypt is a command-line application. If you are used to the Microsoft Windows or Apple Mac OS X operating system, you may not be familiar with running command-line tools. This section shows you all you need to get started.

• Windows tells you how to use APCrypt on Windows.
  
  

Windows

To run APCrypt in Windows, you need to open a Command Prompt window.

In Windows:

• Click Start > Programs > Accessories > Command Prompt

The Command Prompt window opens.

Some basic commands

At the command prompt, you type each command, and press the Enter key to execute it. You can use the mouse to select text to copy or cut to the clipboard, but you cannot position the cursor with it. The command line is completely keyboard driven. Navigation keys are shown below:

In addition to running programs, you have many commands to navigate and maintain the system. Two important ones are cd and dir.

Changing directories

Use the cd command to change directories. For example, to change to the directory that APCrypt is located in, type:

C:\>cd \appligent\apcrypt\

The command prompt changes to:

C:\Appligent\apcrypt>

to show you where you are.

To move back one level, use the shortcut of two periods (..)

C:\Appligent\apcrypt>cd..

Don’t forget to press the Enter key after every command. You will now be in this directory:

C:\Appligent>

Move back to apcrypt:

C:\Appligent>cd apcrypt

Listing the contents of a directory

Use the dir command to list the contents of a directory:

C:\Appligent\apcrypt>dir

The computer responds with a listing of all the contents of the apcrypt directory.

If the directory contents fly by too fast to read, do this:

C:\Appligent\apcrypt>dir /p

The /p switch tells DOS to display one page at a time. Press the Enter key to see the next page.

To see the contents of all the subdirectories at the same time, type:

C:\Appligent\apcrypt>dir /s

This displays the contents of apcrypt and all the subdirectories under it.

Running APCrypt

To run APCrypt, type the commands on the command line as shown in other sections of this manual and press Enter. In the next example, we’ve truncated the command prompt path for clarity. A simple command would be:

C:\path\>apcrypt.bat  -o Samples\output.pdf Samples\input.pdf

This processes the sample file and creates a new file named “output.pdf”.  Note we provide the relative path to the input and output files so that APCrypt knows where to find them. The safest way to specify files is to use the full path:

C:\path\>apcrypt.bat  "c:\appligent\apcrypt\Samples\input.pdf"

If you do not specify the correct path, you will get a “file not found” error.

Now, refer to the rest of this User Guide for details about using APCrypt.

E-mail

You can contact support directly by sending an e-mail to support@appligent.com. Support e-mails are answered within one business day during the normal business hours listed below.  

Telephone & Fax

• Telephone: +1 610 284 4006
• Fax: +1 610 284 4233

To better serve you, please call us during our normal business hours, Monday - Friday, 8:00 am - 5:00 pm U.S. EST/EDT.

A member of our friendly, knowledgeable support staff will reply as soon as possible, generally within one business day.

International Support

Customers from locations outside the United States, including Germany, United Kingdom, Canada and Australia can contact us directly or connect with one of our many resellers.

When contacting support please provide the following information:

• Name of the Product
• Product Version Number
• Operating System
• Your Name
• Company Name
• Your Email Address
• Your Phone Number
• Product Registration Number
• Any files to help us reproduce your problem (if needed)

Known Issues

If an input file has a user password set, the user password is copied over into the new output file even if -userpass <Password> is not supplied on the command line.

-d option must have Owner password
All encrypted documents that you decrypt with -d ownerpass must have an Owner password. You cannot use the -d option without an Owner password. If you have a legacy PDF document that was encrypted without an Owner password, you must create an Owner password for the document before using the -d option to decrypt it.

Form Fields
APCrypt cannot decrypt files with form fields. If you need to apply encryption to a document with form fields, delete them, remove encryption manually beforehand, or flatten them with FDFMerge.

Linearization
Linearization (-w) should not be used with files that contain articles.

To Get Help

Contact technical support by:

emailing support@appligent.com, or calling 610-284-4006

Please provide the following:

Product name and version number
Operating system
Your name, company name, email address, and phone number
Description of your question or problem

Responses are typically emailed within one business day.