Encryption

Version 6.1.0

In this article

This article describes how to use PDFsharp to read and write encrypted PDF files.

What is encryption?

Encryption protects a PDF document from unauthorized access to its content. The protection is based on a password used for encryption at the creation process of the document. PDFsharp provides several encryption methods.

User and owner password

PDF files can be encrypted using a user password, an owner password, or both of them. In general, one of these passwords has to be provided to open and decrypt a secured PDF file. For a PDF file secured with an owner password, the owner password is required to gain full access to the file, including the ability to change the file.

Loading an encrypted file only requires one password to be provided. If this password matches the owner password of the file, the file is opened with owner rights. If the password instead matches the user password of the file, the file is opened with user rights.

If a user password, but no owner password is provided to secure a file, PDFsharp actually uses the given password as both, user and owner password. Otherwise, applications could grant owner access, when providing an empty password.

Read encrypted PDF files

For reading a password secured file with PDFsharp, the user or owner password has to be passed this way:

var pdfDoc = PdfReader.Open(filename, userOrOwnerPassword);

PDFsharp’s purpose is creating and modifying PDF files. The code line above hence uses PdfDocumentOpenMode.Modify to load the file. If the file is protected with an owner password, it must not be modified without it. Therefore, this file cannot be opened with a potential user password using this code line.

To get around this issue, you can provide the owner password or pass a less extensive PdfDocumentOpenMode. Maybe importing pages into a new document instead of modifying the original document could solve the problem:

var pdfDocImport = PdfReader.Open(filename, userPassword, PdfDocumentOpenMode.Import);
var pdfDoc = new PdfDocument();

foreach (var page in pdfDocImport.Pages)
    pdfDoc.AddPage(page);

When reading a file, all the encryption methods introduced below are supported. Starting with version 6.2.0, PDFsharp will also support reading PDF files, that were secured with the proprietary encryption of revision 5.

Write encrypted PDF files

For writing a secured PDF file, you have to set the user and/or owner password before saving the file:

// Use this line to set a user password.
pdfDocument.SecuritySettings.UserPassword = userPassword;

// Use this line to set an owner password.
pdfDocument.SecuritySettings.OwnerPassword = ownerPassword;

// Set encryption, if wanted.
// See "Setting the encryption method".

// Save the file.
pdfDocument.Save(filename);

Setting the encryption method

PDFsharp comes with an implementation of the standard security handler defined by the PDF reference to support various encryption methods. By default, encryption version 4 using AES with 128 bit key length is used. This is the most recent encryption method introduced with PDF 1.x.

You can set the desired encryption method by inserting one of the following code lines before saving the file. You can use one of the encryption-specific methods like SetEncryptionToV1 to use all supported encryption options. Alternatively, you can use the general SetEncryption function and pass one of the PdfDefaultEncryption enum values to set the most typical encryption methods using one parameter.

Contemporary encryption methods

Encryption version 4

Encryption version 4 using AES with 128 bit key length is used in PDFsharp by default, as it is a strong encryption supported by PDF 1.5.

You can set this encryption like this:

pdfDocument.SecurityHandler.SetEncryptionToV4UsingAES();
// or
pdfDocument.SecurityHandler.SetEncryption(PdfDefaultEncryption.V4UsingAES);

To exclude the metadata stream from encryption, use:

pdfDocument.SecurityHandler.SetEncryptionToV4UsingAES(false);

To use the RC4 algorithm instead of AES, use:

pdfDocument.SecurityHandler.SetEncryptionToV4UsingRC4();
// or
pdfDocument.SecurityHandler.SetEncryption(PdfDefaultEncryption.V4UsingRC4);

To use the RC4 algorithm instead of AES and exclude the metadata stream from encryption, use:

pdfDocument.SecurityHandler.SetEncryptionToV4UsingRC4(false);

Encryption version 5

Encryption version 5 is the most recent encryption method. It uses AES with a 256 bit key length and is only supported in PDF 2.0.

You can set this encryption like this:

pdfDocument.SecurityHandler.SetEncryptionToV5();
// or
pdfDocument.SecurityHandler.SetEncryption(PdfDefaultEncryption.V5);

To exclude the metadata stream from encryption, use:

pdfDocument.SecurityHandler.SetEncryptionToV5(false);

Use default encryption

To set the default encryption (version 4 using AES with 128 bit key length), use:

pdfDocument.SecurityHandler.SetPdfDefaultEncryption();
// or
pdfDocument.SecurityHandler.SetEncryption(PdfDefaultEncryption.Default);

Reset encryption

To remove the encryption settings and the passwords, use:

pdfDocument.SecurityHandler.SetEncryptionToNoneAndResetPasswords();
// or
pdfDocument.SecurityHandler.SetEncryption(PdfDefaultEncryption.None);

Older encryption methods

PDFsharp supports older encryption methods to open PDF documents protected with these older methods. We discourage you from using these encryption methods for protecting new documents, as they may not be secure anymore.

Encryption version 1

To set encryption version 1 using RC4 with 40 bit key length, use:

pdfDocument.SecurityHandler.SetEncryptionToV1();
// or
pdfDocument.SecurityHandler.SetEncryption(PdfDefaultEncryption.V1);

Encryption version 2

To set encryption version 2 using RC4 with 40 bit key length, use:

pdfDocument.SecurityHandler.SetEncryptionToV2();
// or
pdfDocument.SecurityHandler.SetEncryption(PdfDefaultEncryption.V2With40Bits);

To set encryption version 2 using RC4 with 128 bit key length, use one of the following lines. This encryption was the default encryption in PDFsharp 1.5.

pdfDocument.SecurityHandler.SetEncryptionToV2With128Bits();
// or
pdfDocument.SecurityHandler.SetEncryption(PdfDefaultEncryption.V2With128Bits);

To set encryption version 2 using RC4 with a variable key length, use the following line. keyLength must be a multiple of 8 from 40 to 128 bit.

pdfDocument.SecurityHandler.SetEncryptionToV2(keyLength);

Setting permissions

The PDF reference introduces user access permission flags, allowing to set specific permissions that shall be granted when the PDF file is opened with the user password. pdfDocument.SecuritySettings provides a set of boolean properties to set those permissions.

Property Explanation Required encryption version
PermitPrint Permits printing of the document (possibly not at the highest quality level, depending on whether PermitFullQualityPrint is also set to true). Any
PermitModifyDocument Permits modifying the contents of the document by operations other than those controlled by PermitAnnotations, PermitFormsFill, and PermitAssembleDocument. Any
PermitExtractContent Permits copying or extracting text and graphics from the document. Any
PermitAnnotations Permits adding or modifying text annotations, filling in interactive form fields, and, if PermitModifyDocument is also set to true, creating or modifying interactive form fields (including signature fields). Any
PermitFormsFill Permits filling in existing interactive form fields (including signature fields), even if PermitAnnotations is false. Version 2 or higher
PermitAssembleDocument Permits assembling the document (inserting, rotating, or deleting pages and creating document outline items or thumbnail images), even if PermitModifyDocument is false. Version 2 or higher
PermitFullQualityPrint Permits printing the document to a representation from which a faithful digital copy of the PDF content could be generated, based on an implementation-dependent algorithm. When this is false (and PermitPrint is set), printing shall be limited to a low-level representation of the appearance, possibly of degraded quality. Version 2 or higher