Encryption

The encryption object adds password protection to the generated PDF and DOCX. You can set separate user and owner passwords and control what actions readers are allowed to perform.

Encrypted PDFs are not archival

PDF/A forbids encryption. An encrypted PDF is delivered without its PDF/A claim, and the render notes it. A definition that claims a PDF/A part and also sets encryption is refused: choose one. To keep a document both archival and confidential, leave the PDF unencrypted and protect it where it is stored and sent. See Conformance.

Properties

Property	Type	Default	Description
`encryptionType`	string	`"aes256"`	The cipher: `aes256`, `aes256Gcm` or `aes128` (see below)
`userPassword`	string	—	The password that opens the document. Absent, it opens without one and the permissions still hold
`ownerPassword`	string	—	The password that lifts the permissions. Absent, a random one is drawn, so nobody holds it
`permissions`	object	—	What a reader may do without the owner password (see below)
`encryptMetadata`	boolean	`true`	Whether the document's metadata is encrypted with it; `false` leaves it readable to a search tool
`encryptEmbeddedFilesOnly`	boolean	`false`	Encrypts only the attached files, leaving the document itself readable

Encryption types

Type	Notes
`aes256`	AES-256, the default and the recommended cipher
`aes256Gcm`	AES-256 in GCM mode, defined over PDF 2.0: an unpinned document becomes PDF 2.0, and under a 1.7 pin AES-256 is written instead, with a warning
`aes128`	AES-128, deprecated by PDF 2.0: a 2.0 document gets AES-256 instead, with a warning

RC4 is not offered: it is broken, and PDF 2.0 deprecates it.

Permissions

The permissions object controls what a user who opens the document with the user password is allowed to do. Absent, printing at full quality is allowed and nothing else; {} grants nothing.

Property	Type	Default	Description
`print`	boolean	`false`	Allow printing
`printHighQuality`	boolean	`true`	Allow printing at full quality; `false` allows degraded printing only, so set `print` too
`modify`	boolean	`false`	Allow modifying document content
`copy`	boolean	`false`	Allow copying text and graphics
`annotate`	boolean	`false`	Allow adding comments and filling forms
`fillForm`	boolean	`false`	Allow filling form fields
`assemble`	boolean	`false`	Allow inserting, rotating, or deleting pages

In a DOCX

A DOCX is protected from the same encryption object, as far as Word's format allows:

Key	In the DOCX
`userPassword`	The file is encrypted and opens under this password, with AES-256. Without one, the DOCX is not encrypted and opens without a password
`ownerPassword` and `permissions`	Become Word's editing restriction, locked under the owner password: read-only, comments only, or filling in forms, by the permissions granted. Allowing `modify` leaves editing unrestricted
`encryptionType`	A DOCX is always encrypted with AES-256
`permissions.print`, `copy`, `assemble`, `printHighQuality`	No equivalent in a DOCX. A denied one is reported, and not applied
`encryptMetadata`, `encryptEmbeddedFilesOnly`	No equivalent: the whole file is encrypted

note

Word's editing restriction keeps honest readers from editing, but the Office Open XML standard says it is not a security feature. Only userPassword makes the content unreadable without the password.

Examples

Basic password protection

{
  "document": {
    "encryption": {
      "encryptionType": "aes256",
      "userPassword": "viewerPass123",
      "ownerPassword": "adminPass456"
    },
    "content": [
      { "p": "This document requires a password to open." }
    ]
  }
}

Read-only with print allowed

{
  "document": {
    "encryption": {
      "encryptionType": "aes256",
      "userPassword": "readonly",
      "ownerPassword": "owner",
      "permissions": {
        "print": true,
        "copy": false,
        "modify": false,
        "annotate": false,
        "fillForm": false,
        "assemble": false
      }
    },
    "content": [
      { "p": "This document can be viewed and printed, but not edited or copied." }
    ]
  }
}

Form-fillable only

{
  "document": {
    "encryption": {
      "encryptionType": "aes128",
      "userPassword": "",
      "ownerPassword": "formsAdmin",
      "permissions": {
        "print": true,
        "fillForm": true,
        "modify": false,
        "copy": false,
        "annotate": false,
        "assemble": false
      }
    },
    "content": [
      { "p": "Fill in the fields below:" }
    ]
  }
}

An empty userPassword allows opening without a password while still enforcing permission restrictions.

Unencrypted metadata

{
  "document": {
    "metadata": {
      "title": "Confidential Report",
      "author": "Operations Team"
    },
    "encryption": {
      "encryptionType": "aes256",
      "userPassword": "secure",
      "ownerPassword": "admin",
      "encryptMetadata": false
    },
    "content": [
      { "p": "Metadata is searchable even though the document is encrypted." }
    ]
  }
}

This is useful when documents need to be indexed by a document management system without requiring the password.

Properties​

Encryption types​

Permissions​

In a DOCX​

Examples​

Basic password protection​

Read-only with print allowed​

Form-fillable only​

Unencrypted metadata​