Table of Contents
A PDF file can be encrypted to prevent access of unauthorized users. When a PDF file is encrypted, all string and stream objects are encrypted using a symmetric-key algorithm, either RC4 or AES. PDF starts with RC4 40 bit at version 1.2, and at version 1.6, it supports 40-bit RC4, 128-bit RC4 and 128-bit AES. The encryption method and key length combined is referred as Encryption Level. Symmetric-key encryption uses the same key to encode and decode data, often called File Key or Master Key.
The access method to the file key is available in a number of ways, called Security Handler. Two security handlers are defined in the PDF standard: password security and public key security (also called certificate security). There are other proprietary security handlers available, such as Adobe Policy Server security, which requires a live proprietary server at presence. Due to obvious reasons, PDFLeo does not support those proprietary handlers.
PDF standard also defines access permission which a document author can specify the desired access of users with certain credentials when encryption is applied. Unfortunately, access permission is not enforced at cryptographic level. Once a PDF is decrypted, the program has access to all the document objects. It is up to the client program to honor the permission.
The permission settings varies by PDF version. The complete list can be found at Section 3.3.2, “Permissions”.
The metadata stream in the document can be optionally marked as clear text, in order for other software (such as a search engine) to retrieve the data without requiring credentials. Clear text metadata support is available at PDF version 1.5, and requires 128-bit encryption level (RC4-128 or AES).
Encryption setting selection may affect the PDF version. As indicated previously, pdfleo automatically increases PDF version of the output file if a feature selected requires so.
Occasionally user may want to limit the PDF version, in order to ensure that results are compatible with existing software. In order to do so user needs to know which encryption settings are supported at that PDF version. This manual groups encryption settings into Compatibility Level.
A higher PDF version can utilize lower compatibility level. For example a PDF file marked version 1.6 can be encrypted with 40-bit RC4 (requiring 1.2). However under this settings metadata stream can't be marked as clear text. In order for the metadata to be marked as clear text, 128-bit RC4 or AES must be used.
To select encryption options based on specified PDF version, first determine the highest compatibility level. For example, suppose that the resulted PDF should have a version no higher than 1.5 (Acrobat 6.0). From the list below, 128-bit AES can't be selected, but 40-bit RC4 (with metadata always encrypted) is a candidate.
Acrobat 3.0 (PDF version 1.2). Encryption level is 40-bit RC4. Metadata is always encrypted.
Acrobat 5.0 (PDF version 1.4). 128bit-RC4. Metadata is always encrypted.
Acrobat 6.0 (PDF version 1.5). 128bit-RC4. Metadata can be marked as clear text.
Acrobat 7.0 (PDF version 1.6). 128bit-AES Metadata can be marked as clear text.
Warning
PDFLeo does not currently support AES-256 encryption settings per PDF 1.7 Adobe Extension Level 3/ Acrobat 9.
Password security features two passwords: user password, which is given to the viewer of the document, and owner password, which is reserved by the author. In theory, without owner password, the user can only perform operations allowed by the author, such as printing, extracting pages and so on. The author, while retaining the owner passwords, has the full access to the document. However, as pointed out previously, the permission is only enforced by the application, not by cryptographic technology. Anyone with user password can convert the document to unencrypted mode. Some authors choose to set user password to blank and distribute the documents with expectation that anybody can view the document, but can't modify it. This expectation is not correct.
Although password security protects the encryption key to authorized users, the passwords must be known to authorized users prior to viewing the document. In many times it is difficult to pass the password in a secured manner. public key security solves the problem in a nice way - the authorized users give their certificates to the author, and encryption key is encrypted with the certificate. The certificate can be passed over unsecured media because the decryption requires the private key, which is not transferred.
The two security handlers are mutually exclusive. If public key security is chosen, the document can't be encrypted with a password, and vice versa.
Similar to the password security, the author can set permission for each user, referred as recipient. Multiple recipients can share the same permission, called recipient set. A PDF document can have multiple permission set. Like passwords security, the permission is only enforced by the application.
PDFLeo supports two types of security handlers - password security
and public key security. Both share common encryption settings - such
as encryption level, key length and if metadata is encrypted. The common
settings are specified through --encrypt switch. After this is specified,
you use --password-security to specify parameters for password security,
or --recipient to specify parameters for public key security.
Common settings are specified through --encrypt switch.
The value of this option has four fields, divided by semicolon:
The first field is one of the three choices indicating how the current encryption setting is based: preserve, copy, and discard.
- preserve
This is the default option when no
--encryptis present. The output PDF preserves all encryption settings, including passwords, permission and recipient sets. If the original PDF file is not encrypted, the output will not be encrypted either. Under this mode, no--password-securityor--pubkey-recipientis allowed. The switch works as long as you have the credentials to open the input file.- discard
The output PDF will use encryption settings specified at the command line, without any inheritance from source file. Normally it is followed by encryption level, key length and metadata encryption flag. However, if none of them is present, the resulted PDF will have no encryption at all.
- copy
The encryption setting is copied from source document, and subsequently modified by options specified at command line. The attributes copied include encryption level, key length, and permissions. Note that this option is used to establish the base line for encryption settings. They should not be used when the whole encryption attributes are preserved in the target document.
Encryption Level: can be RC4, RC4-128, and AES-128. Encryption level affects the following key length parameter as some of them have fixed key length.
Key Length. For RC4-128 encryption level, key length between 40 and 128 can be specified here. Note that the key length must be integral times of 8. For other encryption levels, this field is ignored. For RC4 cipher the key length is fixed at 40 bits. For AES-128, the key length is 128 bits.
A word
yesornoto indicate if meta data stream should be kept clear text. This setting is available when encryption level is RC4-128 or AES-128. The default value isyes.
Note
The difference between copy and discard is the encryption setting baseline. If copy is specified,
the following settings are copied from the source PDF: encryption leve,
key length, clear text metadata and permissions. If discard is specified, the default base line is in use:
AES-128, clear text
metadata, and full access permission. Subsequent parameters will
modify those settings. If the source is not encrypted, the two modes
produce the same result.
Permission is specified inside --password-security or --pubkey-security. For public key encrypted PDFs,
recipients are grouped into recipient set, with each set sharing the
same permission.
Note that permission settings are based on encryption level.
If RC4 (40-bit) is specified, the following permissions are available.
- print=[yes|no]
Determines whether or not to allow printing.
- modify=[yes|no]
Determines whether or not to allow document modification.
- extract=[yes|no]
Determines whether or not to allow text/image extraction.
- annotate=[yes|no]
Determines whether or not to allow comments and form fill-in and signing.
If RC4-128 or AES-128 is specified as encryption level, the following permissions are applicable:
- accessibility=[yes|no]
If yes, text access for screen reader devices for the visually impaired is allowed.
- extract=[yes|no]
If yes, text and graphic extraction, such as copying of text, images and other content, is allowed.
- print=[high|low|none]
This option specifies the print access, which can be one of the following:
high: allow high resolution printing.low: allow degraded printing.none: no printing is allowed.
- modify=[all|annotate|form|assembly|none]
This option specifies the modify access, which can be one of the following, each of which implies all the options that follow it:
all: allow full document modificationannotate: allow comment authoring and form operationsform: allow form field fill-in and signing existing signature fields.assembly: allow document assembly only (inserting, deleting and rotating pages).none: allow no modifications.
Permissions are separated with semicolon. For example, the following code specifies permission that allow high resolution printing and no modification:
C:\>pdfleo --encrypt=copy; --password-security=pdf123;;print=high;modify=none
Use --password-security switch to specify owner
password, user password and
permission. This switch can't be used with --encrypt=preserve.
The value of switch requires at least two fields - the first field containing the value of owner password, followed by user password. Permissions are optional, and start from the third field if they are present. Fields are separated by semicolon.
--password-security=<ownerpass>;<userpass>;<perm1>;<perm2>...
Empty passwords are allowed by leaving the field blank. You can also copy the password from the source file using asterisk (*). If source document is not encrypted, empty password is used for the output. For example,
C:\>pdfleo --encrypt=copy --password-security=pdf123;*;print=high;modify=none
The command above sets owner password to pdf123,
and the user password to the one in the source document.
Note
Passwords are not always retrievable. If you opened
the document using the owner password, pdfleo is able to derive
the user password. However, the opposite is not true. If the document
is opened by user password, pdfleo can't derive the owner password.
If you specify to copy the owner password, pdfleo will print
a warning and replace it with the default owner password, pdfleo.
Copy Encryption Settings and Set Passwords and Permission
the following example sets owner password to pdf123, user password
set to empty. Print permission to high resolution and modify option
to none. both permissions require encryption to set to RC4-128 or AES-128.
C:\>pdfleo --encrypt=copy; --password-security=pdf123;;print=high;modify=none
Note that permission is based on the one in the source document
if --encrypt=copy is specified. Otherwise it starts
with full access.
This --pubkey-recipient switch specifies
public key security options. Multiple switches
can exist at the command line, with each specifying a recipient set. A
recipient set comprises multiple recipients shared by the same permission flag.
A recipient is identified by its X509 public key file.
C:\>pdfleo --encrypt=discard;AES-128 \
--pubkey-recipient=thomas_tang.cer;joe_smith.cer;modify=none;print=low;extract=yesThe first part lists all certificate files, separated by semicolon.
the second part specifies permission flags. The permission flag is based
on source document if copy is specified at --encrypt switch, otherwise it starts with full access.
Hint: you can dump the list of recipients using --info switch after creating the document.
For maximum compatibility across applications, it is recommended to restrict password text to printable ASCII characters only. However if your existing PDF is encrypted with extended characters, or you plan to use extended characters in password, read this section. Extended characters are those not in the ASCII range (0x20~0x7e).
In PDF specification, password is interpreted as byte sequence. However, users often treat passwords text. Value of characters are subject to the interpretation of the code page. For example, Latin character Ä has value 0x80 under Mac Roman encoding, while on windows code page 1252 it is 0xC4. In order to uses to open encrypted files with the same password phrase across Windows and Mac, Acrobat converts the supplied password text into a special encoding native to PDF, called PdfDocEncoding. This encoding contains most characters in code page 1252 and MacRoman. Characters not in the encoding set are converted to spaces.
In order for users to have the same UI experience with Acrobat, pdfleo takes the same approach. Therefore you can encrypt PDFs with passwords containing Latin characters, and use the same password text in Adobe Reader. Note that other applications may take different approaches. Such applications may not be able to read PDFs encrypted in this manner.
The command below encrypts source PDF with owner password 123456,
and user password DésoléÄe.
C:\>pdfleo --encrypt=discard;AES-128;;no \
--password-security=123456;DésoléÄe;print=none test3.pdf test8.pdfThe following section demonstrates how you can use pdfleo to encrypt or decrypt PDF documents. Remember that encryption can be used in conjunction with other transforms, such as linearization and compression.
Preserving Encryption
Under preserve mode, the encryption settings are preserved in the target PDF. If the source PDF is not encrypted, the output is not encrypted either. If the source is encrypted, the output PDF preserves all encryption settings, such as encryption level, permission, passwords and recipient sets.
C:\>pdfleo --encrypt=preserve source.pdf target.pdf
Preserveis the default encryption mode
and it can be omitted.
The command line below has the same effect:
C:\>pdfleo source.pdf target.pdf
Stripping Encryption (Decryption)
By specifying discard without additional parameters, the encryption is removed from the PDF.
C:\>pdfleo --encrypt=discard source.pdf target.pdf
Encrypt with New Encryption Settings
If discard is followed by other parameters,
the output PDF will be encrypted. When this is the case,
security handler through --password-security or --pubkey-security is required. The discard mode sets encryption baseline to AES-128, 128 bits, clear text metadata
and all access (permission). They can be modified by other command
line parameters. The following statement
encrypt the PDF with RC4-128, 80 bits, and metadata is encrypted.
The following --password-security switch specifies the owner
password as pdf128, user password empty; modify permission is set
to none.
C:\>pdfleo --encrypt=discard;RC4-128;80;no \ --password-security=pdf123;;modify=none \ source.pdf target.pdf
You do not need to set all parameters explicitly. For example, the following command will encrypt document using the default encryption level - AES-128, clear text metadata.
C:\>pdfleo --encrypt=discard; \ --password-security=pdf123;;modify=none \ source.pdf target.pdf
The semicolon after discard can't be skipped. It indicates
that the encryption parameters followed use the default value.
Encrypting with Settings Based on Source PDF
The copy mode uses encryption settings from the source PDF as the base line.
C:\>pdfleo --password=pdf123 --encrypt=copy --password-security=*;*;print=full
It is possible to change security setting under copy mode:
C:\>pdfleo --password=pdf123 --encrypt=copy;AES-128 \ --password-security=*;*;print=full \ source.pdf target.pdf
The command above changes encryption level to AES-128.
Encrypting with Public Key Security
By using --pubkey-security option, the output
PDF can be encrypted with public key security.
C:\>pdfleo --encrypt=discard;AES-128 \ --pubkey-security=john.smith.cer;jennifer.lopez.cer;modify=none;print=low \ source.pdf target.pdf
The resulted document can only be opened by the persons who
posses private keys of corresponding certificates: john.smith.cer and jennifer.lopez.cer. The permission is
set to “no modification and low resolution printing”.