Decrypt

Namespace: Com\Tecnick\Pdf\Encrypt

class Decrypt extends Compute

Extends: Compute

Source: src/Decrypt.php:82

Authenticates a password (or private key for public-key mode) against a PDF encryption dictionary and recovers the document file-encryption key.

Usage: $dec = new Decrypt($encrypt->getEncryptionData()); if ($dec->authenticate(‘userpass’)) { $plaintext = $dec->decryptString($ciphertext, $objnum, $gennum); }

A dictionary read out of an existing document is better passed to fromEncryptionDictionary(), which derives the mode from /V, /R and /CFM for the standard handler, and from /V and /CFM for the public-key one.

After successful authentication the derived key is stored internally and:

• decryptString() decrypts PDF string/stream objects.
• getObjectKey() returns the per-object key for RC4 and AES-128 streams.
• getDocumentKey() returns the raw 32-byte (or shorter) file key.
• getAuthenticatedRole() reports which credential authenticated.
• getRecipientPermissions() returns the permission bits of the matching recipient in public-key mode.

Limitations:

• Passwords are used as supplied. ISO 32000-2 section 7.6.4.3.3 calls for SASLprep (RFC 4013) on R5/R6 passwords and ISO 32000-1 expects PDFDocEncoding for R2 to R4, neither of which is applied here, so non-ASCII passwords may not match other implementations.

Types

TDecryptInput

TEncryptData|array{
    'V': int,
    'mode': int,
    'O': string,
    'U': string,
    'P': int,
    'fileid': string,
    'Length'?: int,
    'OE'?: string,
    'UE'?: string,
    'perms'?: string,
    'EncryptMetadata'?: bool,
    'pubkey'?: bool,
    'Recipients'?: array<array-key, string>,
}

Methods

__construct()

Initialise the decryptor from an encryption dictionary.

Accepts the array returned by Encrypt::getEncryptionData() or any array that satisfies the TDecryptInput shape. Fields not present in the input are filled with the defaults defined in Output::$encryptdata.

Every required entry is checked for presence and type before it is used.

public __construct(TDecryptInput $input)

Parameters:

• $input (TDecryptInput): Encryption dictionary fields.

Throws:

• Exception: When the dictionary is malformed.

Source: src/Decrypt.php:122

authenticate()

Authenticate using a password and/or private key.

Tries the supplied string as the owner password first, then as the user password. For public-key mode, $privkeyPath must be the path to a PEM file containing the recipient’s certificate and private key; $password is ignored in that case.

On success the derived file-encryption key is stored internally and getAuthenticatedRole() reports which password matched. For R5 and R6 the password is truncated to 127 bytes and the Perms entry is verified against the recovered key, so a document with tampered permission bits is rejected.

public authenticate(string $password, string $privkeyPath = '', string $passphrase = ''): bool

Parameters:

• $password (string): UTF-8 password to test (ignored for pubkey mode).
• $privkeyPath (string): Path to PEM file for public-key mode.
• $passphrase (string): Passphrase of the PEM private key, when it is encrypted.

Returns: bool: True when authentication succeeds.

Throws:

• Exception

Source: src/Decrypt.php:621

decryptString()

Decrypt a PDF string or stream object.

Must be called after a successful authenticate() call.

For RC4 modes (0, 1) the operation is symmetric: the same method that encrypts also decrypts. For AES modes (2, 3, 4) the first 16 bytes of $data are the random IV and the remainder is the ciphertext; the PKCS#7 padding is stripped.

public decryptString(string $data, int $objnum = 0, int $gennum = 0): string

Parameters:

• $data (string): Encrypted string/stream data.
• $objnum (int): PDF object number (used for per-object key derivation in RC4 and AES-128 modes).
• $gennum (int): PDF object generation number.

Returns: string: Decrypted data.

Throws:

• Exception: When no key has been recovered, when the AES stream is malformed, or when decryption fails.

Source: src/Decrypt.php:690

fromEncryptionDictionary()

Build a decryptor from the entries of a PDF encryption dictionary.

Derives this library’s mode index from /V, /R and the crypt filter method, and accepts /Perms under its PDF name.

The public-key handler is recognised from /Filter /Adobe.PubSec or from the presence of /Recipients, and needs no /R: that entry belongs to the standard handler.

‘fileid’ is not a dictionary entry: it is the first element of the trailer /ID array, from which revisions 2 to 4 derive the key, so the caller has to add it to $dict.

public static fromEncryptionDictionary(array<string,mixed> $dict): self

Parameters:

• $dict (array<string,mixed>): Encryption dictionary entries under their PDF names, plus ‘fileid’. /R is required for the standard handler; /CFM is required for R 4.

Returns: self

Throws:

• Exception: When the revision is not supported.

Source: src/Decrypt.php:184

getAuthenticatedRole()

Return the role granted by the last successful authenticate() call.

In public-key mode the role is ‘recipient’: the applicable permissions are the ones getRecipientPermissions() returns.

public getAuthenticatedRole(): string|null

Returns: string|null: ‘user’, ‘owner’, ‘recipient’, or null when not authenticated.

Source: src/Decrypt.php:651

getDocumentKey()

Return the recovered file-encryption key.

public getDocumentKey(): string

Returns: string: Raw binary key (empty string before authenticate() succeeds).

Source: src/Decrypt.php:711

getObjectKey()

Return the per-object key for RC4 and AES-128 streams.

Must be called after a successful authenticate() call.

public getObjectKey(int $objnum, int $gennum = 0): string

Parameters:

• $objnum (int): Object number.
• $gennum (int): Object generation number.

Returns: string

Throws:

• Exception: When no key has been recovered, or when either number is out of range.

Source: src/Decrypt.php:751

getPdfEncryptionObj()

Not available on a decryptor: writing an encryption dictionary is the task of Encrypt.

public getPdfEncryptionObj(int &$pon): string

Parameters:

• $pon (int): Current PDF object number.

Returns: string

Throws:

• Exception: Always.

Source: src/Decrypt.php:735

getRecipientPermissions()

Return the permission bits assigned to the recipient that authenticated.

Public-key documents carry no /P entry: each recipient’s permissions travel inside its own PKCS#7 envelope. Returns null outside public-key mode and before authentication.

public getRecipientPermissions(): int|null

Returns: int|null: Signed 32-bit permission value, or null when unavailable.

Source: src/Decrypt.php:665

getRevision()

Return the security handler revision the dictionary resolved to.

Taken from /R when the dictionary carried it, derived from the mode and /V otherwise.

public getRevision(): int

Returns: int

Source: src/Decrypt.php:722

Inherited members

From Compute

• encrypt(): Encrypt data using the specified encrypt type.
• getEncPermissionsString(): Convert encryption P value to a string of bytes, low-order byte first.
• getObjectKey(): Compute encryption key depending on object number where the encrypted data is stored.
• getPubKeyPermissionsString(): Convert encryption P value to the four bytes carried by a public-key recipient envelope, high-order byte first.
• getUserPermissionCode(): Return the permission code used on encryption (P value).

From Data

• DEFAULTPERMS: Permission set applied when the caller does not choose one.

From Output

• __debugInfo(): Redact the file encryption key and the passwords when the object is dumped.
• escapeString(): Escape a string: add “" before “", “(” and “)”.
• getPdfEncryptionObj(): Get the PDF encryption block