PDF Encryption and Permissions: Pdf.Protection

How it works: loaded and pending security

Set OwnerPassword and/or UserPassword (or call SetDecryptCert) before LoadFile; Chilkat tries the owner password first, then the user password, then the empty password, and records which one opened the file. Every Protection operation except getInfo then changes the pending security — the settings the PDF will be saved with. Nothing is encrypted or decrypted until WriteFile or WriteBd is called; if no operation changed anything, the PDF is saved with exactly the security it was loaded with.

The operations

Quick start: protect a PDF

An open password, no copying, low-quality printing — AES-256 (revision 6) by default.

Chilkat.Pdf pdf = new Chilkat.Pdf();
pdf.LoadFile("report.pdf");

pdf.UserPassword = "open-me";          // needed to open the PDF
pdf.OwnerPassword = "admin-secret";    // needed to change its security

Chilkat.JsonObject jsonIn = new Chilkat.JsonObject();
Chilkat.JsonObject jsonOut = new Chilkat.JsonObject();
jsonIn.UpdateString("permissions.print", "lowQuality");
jsonIn.UpdateBool("permissions.copy", false);

if (pdf.Protection("encrypt", jsonIn, jsonOut)) {
    pdf.WriteFile("protected.pdf");    // saved as PDF 1.7, Adobe extension level 8
}

{
  "permissions": { "print": "lowQuality", "copy": false }
}

{
  "changed": true,
  "pending": {
    "encrypted": true,
    "method": "password",
    "algorithm": "aes-256",
    "pdfVersion": "1.7",
    "adobeExtensionLevel": 8,
    "scope": "all",
    "userPasswordRequired": true,
    "ownerPasswordSet": true,
    "permissions": {
      "print": "lowQuality", "modify": true, "copy": false,
      "accessibility": true, "annotate": true, "fillForms": true, "assemble": true
    }
  }
}

Open a protected PDF and remove its encryption

pdf.OwnerPassword = "admin-secret";    // set before loading, to get owner rights
pdf.LoadFile("protected.pdf");
if (pdf.Protection("removeEncryption", jsonIn, jsonOut)) {
    pdf.WriteFile("plain.pdf");
}

op = encrypt

An empty jsonIn encrypts everything with AES-256 revision 6, using the two password properties and granting every permission.

algorithmChoice

The version in the file header is raised to the one shown when the PDF is saved, never lowered.

{ "algorithmChoice": "aes-128" }

{
  "changed": true,
  "pending": {
    "encrypted": true, "method": "password", "algorithm": "aes-128",
    "pdfVersion": "1.6", "scope": "all",
    "userPasswordRequired": true, "ownerPasswordSet": true,
    "permissions": { "print": "full", "modify": true, "copy": true, "accessibility": true,
                     "annotate": true, "fillForms": true, "assemble": true }
  }
}

{ "algorithmChoice": "aes-256-gcm" }

{
  "changed": true,
  "pending": {
    "encrypted": true, "method": "password", "algorithm": "aes-256-gcm",
    "pdfVersion": "2.0", "isoExtensionLevel": 32003, "scope": "all",
    "userPasswordRequired": true, "ownerPasswordSet": true,
    "permissions": { "print": "full", "modify": true, "copy": true, "accessibility": true,
                     "annotate": true, "fillForms": true, "assemble": true }
  }
}

scope

{ "scope": "allExceptMetadata", "permissions": { "copy": false } }

{
  "changed": true,
  "pending": {
    "encrypted": true, "method": "password", "algorithm": "aes-256",
    "pdfVersion": "1.7", "adobeExtensionLevel": 8, "scope": "allExceptMetadata",
    "userPasswordRequired": true, "ownerPasswordSet": true,
    "permissions": { "print": "full", "modify": true, "copy": false, "accessibility": true,
                     "annotate": true, "fillForms": true, "assemble": true }
  }
}

{ "scope": "attachmentsOnly" }

{
  "changed": true,
  "pending": {
    "encrypted": true, "method": "password", "algorithm": "aes-256",
    "pdfVersion": "1.7", "adobeExtensionLevel": 8, "scope": "attachmentsOnly",
    "userPasswordRequired": true, "ownerPasswordSet": true,
    "permissions": { "print": "full", "modify": true, "copy": true, "accessibility": true,
                     "annotate": true, "fillForms": true, "assemble": true }
  }
}

permissions

Every permission is granted by default; name the ones to restrict.

With rc4-40 only print (as none or full), modify, copy and annotate exist; the rest are ignored.

{
  "permissions": {
    "print": "full",
    "modify": false,
    "copy": false,
    "annotate": false,
    "fillForms": false,
    "assemble": false
  }
}

{
  "changed": true,
  "pending": {
    "encrypted": true, "method": "password", "algorithm": "aes-256",
    "pdfVersion": "1.7", "adobeExtensionLevel": 8, "scope": "all",
    "userPasswordRequired": true, "ownerPasswordSet": true,
    "permissions": { "print": "full", "modify": false, "copy": false, "accessibility": true,
                     "annotate": false, "fillForms": false, "assemble": false }
  }
}

{
  "permissions": {
    "modify": false,
    "annotate": false,
    "fillForms": true,
    "assemble": false
  }
}

{
  "changed": true,
  "pending": {
    "encrypted": true, "method": "password", "algorithm": "aes-256",
    "pdfVersion": "1.7", "adobeExtensionLevel": 8, "scope": "all",
    "userPasswordRequired": true, "ownerPasswordSet": true,
    "permissions": { "print": "full", "modify": false, "copy": true, "accessibility": true,
                     "annotate": false, "fillForms": true, "assemble": false }
  }
}

Passwords

• encrypt and changePasswords read the UserPassword and OwnerPassword properties at the time of the call.
• An empty UserPassword gives a PDF that opens without a prompt but keeps its restrictions.
• encrypt refuses an empty OwnerPassword whenever any permission is restricted, since anyone would then have owner rights and the restrictions would mean nothing. An empty owner password is allowed when every permission is granted (a plain open-password file).
• aes-256 and aes-256-gcm: any Unicode text, up to 127 bytes as UTF-8. All older algorithms: up to 32 Latin-1 characters; encrypt fails if a password cannot be represented.
• AES-256 PDFs opened with the owner password alone: the user password cannot be recovered from the file, so changePermissions and removeRestrictions are refused unless UserPassword was also set when the PDF was loaded. changePasswords and encrypt work, since they set both passwords afresh.

// An open password only: anyone who can open it has every permission.
pdf.UserPassword = "open-me";
pdf.OwnerPassword = "";
pdf.Protection("encrypt", jsonIn, jsonOut);      // empty jsonIn: all permissions granted

Certificate encryption

With "method": "certificate", the PDF is encrypted for one or more recipients, each identified by a certificate. Only the public certificate is needed to encrypt; a recipient opens the PDF with the matching certificate and private key.

Example: encrypt for two recipients, then open as one of them

Chilkat.Cert alice = new Chilkat.Cert();
alice.LoadFromFile("alice.cer");          // the public certificate is enough to encrypt
Chilkat.Cert bob = new Chilkat.Cert();
bob.LoadFromFile("bob.cer");
pdf.AddEncryptCert(alice);
pdf.AddEncryptCert(bob);

jsonIn.UpdateString("method", "certificate");
jsonIn.UpdateBool("recipientPermissions[0].changeSecurity", true);   // Alice manages security
jsonIn.UpdateBool("recipientPermissions[1].modify", false);          // Bob cannot modify
pdf.Protection("encrypt", jsonIn, jsonOut);
pdf.WriteFile("for-alice-and-bob.pdf");

// Later, Alice opens it with her certificate and private key:
Chilkat.Cert aliceKey = new Chilkat.Cert();
aliceKey.LoadPfxFile("alice.pfx", "pfx-password");
Chilkat.Pdf pdf2 = new Chilkat.Pdf();
pdf2.SetDecryptCert(aliceKey);
pdf2.LoadFile("for-alice-and-bob.pdf");

{
  "method": "certificate",
  "permissions": { "copy": false },
  "recipientPermissions": [
    { "changeSecurity": true },
    { "modify": false }
  ]
}

{
  "changed": true,
  "pending": {
    "encrypted": true,
    "method": "certificate",
    "algorithm": "aes-256",
    "pdfVersion": "1.7",
    "adobeExtensionLevel": 8,
    "scope": "all",
    "recipients": [
      { "issuer": "CN=Example CA,O=Example", "serialNumber": "1A2B3C",
        "permissions": { "print": "full", "modify": true, "copy": true, "accessibility": true,
                         "annotate": true, "fillForms": true, "assemble": true, "changeSecurity": true } },
      { "issuer": "CN=Example CA,O=Example", "serialNumber": "4D5E6F",
        "permissions": { "print": "full", "modify": false, "copy": true, "accessibility": true,
                         "annotate": true, "fillForms": true, "assemble": true, "changeSecurity": false } }
    ]
  }
}

A recipientPermissions entry starts from everything allowed and applies only the members it names; it replaces permissions for that recipient rather than adding to it.

removeEncryption, removeRestrictions, changePasswords, changePermissions

These operations take no options except changePermissions, which takes the permissions object. Each returns changed and the pending security.

Example: lift the restrictions, keep the open password

pdf.UserPassword = "open-me";
pdf.OwnerPassword = "admin-secret";
pdf.LoadFile("protected.pdf");
pdf.Protection("removeRestrictions", jsonIn, jsonOut);
pdf.WriteFile("unrestricted.pdf");

{ }

{
  "changed": true,
  "pending": {
    "encrypted": true, "method": "password", "algorithm": "aes-256",
    "pdfVersion": "1.7", "adobeExtensionLevel": 8, "scope": "all",
    "userPasswordRequired": true, "ownerPasswordSet": true,
    "permissions": { "print": "full", "modify": true, "copy": true, "accessibility": true,
                     "annotate": true, "fillForms": true, "assemble": true }
  }
}

Example: new passwords

pdf.OwnerPassword = "old-admin-secret";
pdf.LoadFile("protected.pdf");
pdf.UserPassword = "new-open-me";          // the new passwords are read at the time of the call
pdf.OwnerPassword = "new-admin-secret";
pdf.Protection("changePasswords", jsonIn, jsonOut);
pdf.WriteFile("rekeyed.pdf");

Example: new permissions only

{ "permissions": { "print": "none", "copy": false } }

{
  "changed": true,
  "pending": {
    "encrypted": true, "method": "password", "algorithm": "aes-256",
    "pdfVersion": "1.7", "adobeExtensionLevel": 8, "scope": "all",
    "userPasswordRequired": true, "ownerPasswordSet": true,
    "permissions": { "print": "none", "modify": true, "copy": false, "accessibility": true,
                     "annotate": true, "fillForms": true, "assemble": true }
  }
}

pdf.Protection("changePermissions", jsonIn, jsonOut);
pdf.WriteFile("no-print.pdf");

op = getInfo

Reports two states of the loaded PDF: loaded (the security it was loaded with) and pending (the security it will be saved with), and changed, whether they differ. Passwords are never returned.

{
  "changed": true,
  "loaded": {
    "encrypted": true,
    "method": "password",
    "algorithm": "aes-128",
    "pdfVersion": "1.6",
    "scope": "all",
    "userPasswordRequired": true,
    "ownerPasswordSet": true,
    "openedWith": "owner",
    "permissions": { "print": "lowQuality", "modify": false, "copy": false,
                     "accessibility": true, "annotate": false, "fillForms": true, "assemble": false }
  },
  "pending": {
    "encrypted": true,
    "method": "password",
    "algorithm": "aes-256",
    "pdfVersion": "1.7",
    "adobeExtensionLevel": 8,
    "scope": "all",
    "userPasswordRequired": true,
    "ownerPasswordSet": true,
    "permissions": { "print": "full", "modify": false, "copy": false,
                     "accessibility": true, "annotate": false, "fillForms": true, "assemble": false }
  }
}

PreLoadCheck: before loading

PreLoadCheck(path, jsonOut) and PreLoadCheckBd(bd, jsonOut) report what can be known about a file's encryption before it is loaded, so that an application can decide which password or certificate it needs. Nothing is loaded into the object and no password is needed. They return false only when the file cannot be read or is not a PDF; an unencrypted PDF returns true with encrypted false.

Chilkat.JsonObject info = new Chilkat.JsonObject();
pdf.PreLoadCheck("incoming.pdf", info);
if (info.BoolOf("encrypted") && info.StringOf("method") == "certificate") {
    pdf.SetDecryptCert(myCertWithPrivateKey);      // one of info.recipients[]
} else if (info.BoolOf("openPasswordRequired")) {
    pdf.UserPassword = AskUserForPassword();
}
pdf.LoadFile("incoming.pdf");

pdf.PreLoadCheck("protected.pdf", jsonOut);

{
  "encrypted": true,
  "method": "password",
  "algorithm": "aes-256",
  "pdfVersion": "1.7",
  "adobeExtensionLevel": 8,
  "scope": "all",
  "openPasswordRequired": false,
  "permissions": { "print": "full", "modify": false, "copy": true,
                   "accessibility": true, "annotate": false,
                   "fillForms": true, "assemble": false }
}

pdf.PreLoadCheck("for-alice-and-bob.pdf", jsonOut);

{
  "encrypted": true,
  "method": "certificate",
  "algorithm": "aes-256",
  "pdfVersion": "1.7",
  "adobeExtensionLevel": 8,
  "scope": "all",
  "recipients": [
    { "issuer": "CN=Example CA,O=Example", "serialNumber": "1A2B3C" },
    { "issuer": "CN=Example CA,O=Example", "serialNumber": "4D5E6F" }
  ]
}

Saving and signed PDFs

• Saving (WriteFile / WriteBd) applies the pending security. Unchanged security keeps the original algorithm, passwords, permissions, scope and recipients — even when the PDF was opened with only the user password, because either password yields the file's encryption key. Changed security re-encrypts the whole file.
• The PDF version is raised to what the pending algorithm requires and never lowered.
• Signed PDFs. An appended update must keep the original encryption, so any security change means rewriting the whole file, which invalidates every signature. With the PreserveSignatures property true (the default), every operation except getInfo fails on a signed PDF; with it false, the change is allowed and the signatures are invalidated.
• Other features respect the permissions: ExtractText needs the copy permission (or owner rights), and TextReplace, Watermark and Optimize need modify.

Option reference (op = encrypt)

{
  "method": "password",             // password | certificate
  "algorithmChoice": "aes-256",     // rc4-40 | rc4-128 | aes-128 | aes-256-r5 | aes-256 | aes-256-gcm
  "scope": "all",                   // all | allExceptMetadata | attachmentsOnly
  "permissions": {
    "print": "full",                // none | lowQuality | full
    "modify": true,
    "copy": true,
    "accessibility": true,
    "annotate": true,
    "fillForms": true,
    "assemble": true,
    "changeSecurity": false         // certificate method only
  },
  "recipientPermissions": [ { ...same members... }, ... ]   // certificate method only
}

Reference documentation: Pdf.Protection, PreLoadCheck, AddEncryptCert, SetDecryptCert, OwnerPassword, UserPassword. Related: Pdf class overview.