pdf-lite 1.0.0

package/packages/pdf-lite/src/security/handlers/v4.ts

@@ -0,0 +1,379 @@
+import { PdfDictionary } from '../../core/objects/pdf-dictionary'
+import { PdfName } from '../../core/objects/pdf-name'
+import { PdfNumber } from '../../core/objects/pdf-number'
+import { aes128 } from '../../crypto/ciphers/aes128'
+import { deriveObjectKey } from '../../crypto/key-derivation/key-derivation'
+import { Cipher } from '../../crypto/types'
+import { ByteArray } from '../../types'
+import { assert, assertIfDefined } from '../../utils/assert'
+import { AesV2CryptFilter } from '../crypt-filters/aesv2'
+import { AesV3CryptFilter } from '../crypt-filters/aesv3'
+import { PdfCryptFilter } from '../crypt-filters/base'
+import { IdentityCryptFilter } from '../crypt-filters/identity'
+import { V2CryptFilter } from '../crypt-filters/v2'
+import {
+    CryptFilterType,
+    PdfCryptFilterDictionary,
+    PdfEncryptionAlgorithmType,
+    PdfEncryptionDictionary,
+} from '../types'
+import { PdfStandardSecurityHandlerOptions } from './base'
+import { PdfV2SecurityHandler } from './v2'
+
+const IDENTITY_CRYPT_FILTER = new IdentityCryptFilter({ authEvent: 'DocOpen' })
+
+/**
+ * V4 security handler implementing AES-128-CBC encryption with crypt filters.
+ * Supports different encryption methods for strings, streams, and embedded files (PDF 1.5).
+ *
+ * @example
+ * ```typescript
+ * const handler = new PdfV4SecurityHandler({
+ *     password: 'user123',
+ *     ownerPassword: 'admin456'
+ * })
+ * handler.setCryptFilter('StmFilter', new AesV2CryptFilter({ authEvent: 'DocOpen' }))
+ * ```
+ */
+export class PdfV4SecurityHandler extends PdfV2SecurityHandler {
+    /** Map of named crypt filters. */
+    protected cryptFilters: Map<string, PdfCryptFilter> = new Map([
+        ['Identity', IDENTITY_CRYPT_FILTER],
+    ])
+
+    /** Mapping of content types to crypt filter names. */
+    protected cryptFiltersByType: {
+        [key in CryptFilterType]?: string
+    } = {}
+
+    /**
+     * Creates a new V4 security handler with AES-128 encryption.
+     *
+     * @param options - Configuration options for the handler.
+     */
+    constructor(options: PdfStandardSecurityHandlerOptions) {
+        super(options)
+
+        this.setCryptFilter(
+            'StdCF',
+            new AesV2CryptFilter({
+                authEvent: 'DocOpen',
+            }),
+        )
+
+        this.setCryptFilterForType('stream', 'StdCF')
+        this.setCryptFilterForType('string', 'StdCF')
+    }
+
+    /**
+     * Gets a crypt filter by name.
+     *
+     * @param name - The crypt filter name.
+     * @returns The crypt filter, or undefined if not found.
+     */
+    getCryptFilter(name: string): PdfCryptFilter | undefined {
+        return this.cryptFilters.get(name)
+    }
+
+    /**
+     * Gets the crypt filter assigned to a content type.
+     *
+     * @param type - The content type ('string', 'stream', or 'file').
+     * @returns The assigned crypt filter, or null if none.
+     */
+    getCryptFilterByType(type: CryptFilterType): PdfCryptFilter | null {
+        const name = this.cryptFiltersByType[type]
+        if (name) {
+            return this.cryptFilters.get(name) || null
+        }
+        return null
+    }
+
+    /**
+     * Assigns a crypt filter to a content type.
+     *
+     * @param type - The content type.
+     * @param name - The crypt filter name.
+     */
+    setCryptFilterForType(type: CryptFilterType, name: string): void {
+        this.cryptFiltersByType[type] = name
+    }
+
+    /**
+     * Registers a named crypt filter.
+     *
+     * @param name - The filter name.
+     * @param filter - The crypt filter instance.
+     */
+    setCryptFilter(name: string, filter: PdfCryptFilter): void {
+        filter.setSecurityHandler(this)
+        this.cryptFilters.set(name, filter)
+    }
+
+    /**
+     * Gets the encryption revision number.
+     *
+     * @returns 4 for V4 encryption.
+     */
+    getRevision(): number {
+        return 4
+    }
+
+    /**
+     * Gets the encryption version number.
+     *
+     * @returns 4 for crypt filter-based encryption.
+     */
+    getVersion(): number {
+        return 4
+    }
+
+    /**
+     * Computes the object-specific encryption key.
+     *
+     * @param objectNumber - The PDF object number.
+     * @param generationNumber - The PDF generation number.
+     * @param algorithm - Optional algorithm type for key derivation.
+     * @returns The computed object key.
+     * @throws Error if object or generation number is invalid.
+     */
+    async computeObjectKey(
+        objectNumber?: number,
+        generationNumber?: number,
+        algorithm?: PdfEncryptionAlgorithmType,
+    ): Promise<ByteArray> {
+        assert(
+            objectNumber !== undefined,
+            'Object number is required to derive the key',
+        )
+        assert(
+            generationNumber !== undefined,
+            'Generation number is required to derive the key',
+        )
+
+        assert(objectNumber > 0, 'Object number cannot be zero or negative')
+        assert(generationNumber >= 0, 'Generation number cannot be negative')
+
+        this.masterKey ||= await this.computeMasterKey()
+
+        const key = await deriveObjectKey(
+            this.masterKey,
+            objectNumber,
+            generationNumber,
+            algorithm === 'AES-128-CBC',
+        )
+
+        return key
+    }
+
+    /**
+     * Gets an AES-128 cipher for the specified object.
+     *
+     * @param objectNumber - The PDF object number.
+     * @param generationNumber - The PDF generation number.
+     * @returns An AES-128 cipher instance.
+     */
+    protected async getCipher(
+        objectNumber?: number,
+        generationNumber?: number,
+    ): Promise<Cipher> {
+        const key = await this.computeObjectKey(objectNumber, generationNumber)
+
+        return aes128(key)
+    }
+
+    /**
+     * Reads encryption parameters and crypt filter definitions from the dictionary.
+     *
+     * @param encryptionDictionary - The encryption dictionary from the PDF.
+     */
+    readEncryptionDictionary(
+        encryptionDictionary: PdfEncryptionDictionary,
+    ): void {
+        super.readEncryptionDictionary(encryptionDictionary)
+
+        if (encryptionDictionary.get('CF')) {
+            const cfDict = encryptionDictionary.get('CF')
+            assert(cfDict instanceof PdfDictionary, 'CF must be a dictionary')
+
+            const cfEntries = cfDict.values
+
+            for (const [key, cf] of Object.entries(cfEntries)) {
+                assert(
+                    cf instanceof PdfDictionary,
+                    'Crypt filter must be a dictionary',
+                )
+
+                const cfm = cf.get('CFM')
+                const authEvent = cf.get('AuthEvent')
+                const length = cf.get('Length')
+
+                assertIfDefined(
+                    cfm,
+                    cfm instanceof PdfName,
+                    'CFM must be a name',
+                )
+                assertIfDefined(
+                    authEvent,
+                    authEvent instanceof PdfName,
+                    'AuthEvent must be a name',
+                )
+                assertIfDefined(
+                    length,
+                    length instanceof PdfNumber,
+                    'Length must be a number',
+                )
+
+                assert(cfm, 'CFM is required in crypt filter dictionary')
+                assert(
+                    authEvent,
+                    'AuthEvent is required in crypt filter dictionary',
+                )
+
+                if (cfm.value === 'None') {
+                    this.setCryptFilter(
+                        key,
+                        new IdentityCryptFilter({
+                            authEvent: authEvent.value,
+                        }),
+                    )
+                } else if (cfm.value === 'V2') {
+                    this.setCryptFilter(
+                        key,
+                        new V2CryptFilter({
+                            authEvent: authEvent.value,
+                            length: length.value,
+                        }),
+                    )
+                } else if (cfm.value === 'AESV2') {
+                    this.setCryptFilter(
+                        key,
+                        new AesV2CryptFilter({
+                            authEvent: authEvent.value,
+                        }),
+                    )
+                } else if (cfm.value === 'AESV3') {
+                    this.setCryptFilter(
+                        key,
+                        new AesV3CryptFilter({
+                            authEvent: authEvent.value,
+                        }),
+                    )
+                } else {
+                    throw new Error(`Unsupported CFM value: ${cfm.value}`)
+                }
+            }
+        }
+
+        if (encryptionDictionary.values['StmF']) {
+            const stmF = encryptionDictionary.values['StmF']
+            assert(stmF instanceof PdfName, 'StmF must be a name')
+            assert(
+                this.cryptFilters.has(stmF.value),
+                `StmF references unknown crypt filter: ${stmF.value}`,
+            )
+            this.setCryptFilterForType('stream', stmF.value)
+        }
+
+        if (encryptionDictionary.values['StrF']) {
+            const strF = encryptionDictionary.values['StrF']
+            assert(strF instanceof PdfName, 'StrF must be a name')
+            assert(
+                this.cryptFilters.has(strF.value),
+                `StrF references unknown crypt filter: ${strF.value}`,
+            )
+            this.setCryptFilterForType('string', strF.value)
+        }
+
+        if (encryptionDictionary.values['EFF']) {
+            const eff = encryptionDictionary.values['EFF']
+            assert(eff instanceof PdfName, 'EFF must be a name')
+            assert(
+                this.cryptFilters.has(eff.value),
+                `EFF references unknown crypt filter: ${eff.value}`,
+            )
+            this.setCryptFilterForType('file', eff.value)
+        }
+    }
+
+    /**
+     * Writes the encryption dictionary including crypt filter definitions.
+     */
+    async write(): Promise<void> {
+        await super.write()
+
+        const dict = this.dict
+
+        const cfs: Record<string, PdfCryptFilterDictionary> = {}
+        this.cryptFilters.forEach((cf, name) => {
+            if (cf instanceof IdentityCryptFilter) {
+                // The Identity crypt filter is implicit and should not be included
+                return
+            }
+
+            cfs[name] = cf.toDictionary()
+        })
+
+        if (Object.keys(cfs).length > 0) {
+            dict.set('CF', new PdfDictionary(cfs))
+        }
+
+        if (this.cryptFiltersByType.stream) {
+            dict.set('StmF', new PdfName(this.cryptFiltersByType.stream))
+        }
+
+        if (this.cryptFiltersByType.string) {
+            dict.set('StrF', new PdfName(this.cryptFiltersByType.string))
+        }
+
+        if (this.cryptFiltersByType.file) {
+            dict.set('EFF', new PdfName(this.cryptFiltersByType.file))
+        }
+    }
+
+    /**
+     * Encrypts data using the appropriate crypt filter for the content type.
+     *
+     * @param type - The type of content being encrypted.
+     * @param data - The data to encrypt.
+     * @param objectNumber - The PDF object number.
+     * @param generationNumber - The PDF generation number.
+     * @returns The encrypted data.
+     */
+    encrypt(
+        type: 'string' | 'stream' | 'file',
+        data: ByteArray,
+        objectNumber?: number,
+        generationNumber?: number,
+    ): Promise<ByteArray> {
+        const cryptFilter = this.getCryptFilterByType(type)
+        if (cryptFilter) {
+            return cryptFilter.encrypt(data, objectNumber, generationNumber)
+        }
+
+        return super.encrypt(type, data, objectNumber, generationNumber)
+    }
+
+    /**
+     * Decrypts data using the appropriate crypt filter for the content type.
+     *
+     * @param type - The type of content being decrypted.
+     * @param data - The encrypted data.
+     * @param objectNumber - The PDF object number.
+     * @param generationNumber - The PDF generation number.
+     * @returns The decrypted data.
+     */
+    decrypt(
+        type: 'string' | 'stream' | 'file',
+        data: ByteArray,
+        objectNumber?: number,
+        generationNumber?: number,
+    ): Promise<ByteArray> {
+        const cryptFilter = this.getCryptFilterByType(type)
+        if (cryptFilter) {
+            return cryptFilter.decrypt(data, objectNumber, generationNumber)
+        }
+
+        return super.decrypt(type, data, objectNumber, generationNumber)
+    }
+}

package/packages/pdf-lite/src/security/handlers/v5.ts

@@ -0,0 +1,298 @@
+import { aes256 } from '../../crypto/ciphers/aes256'
+import { getFileKey } from '../../crypto/key-derivation/key-derivation-aes256'
+import {
+    generateOandOe,
+    generateUandUe,
+} from '../../crypto/key-gen/key-gen-aes256'
+import { ByteArray } from '../../types'
+import { aes256ecbEncrypt, getRandomBytes } from '../../utils/algos'
+import { assert } from '../../utils/assert'
+import { PdfEncryptionDictionary } from '../types'
+import { PdfV4SecurityHandler } from './v4'
+import { PdfStandardSecurityHandlerOptions } from './base'
+import { AesV3CryptFilter } from '../crypt-filters/aesv3'
+import { PdfHexadecimal } from '../../core/objects/pdf-hexadecimal'
+import { PdfString } from '../../core/objects/pdf-string'
+import { Cipher } from '../../crypto/types'
+
+/**
+ * V5 security handler implementing AES-256-CBC encryption.
+ * This is the most secure encryption method (PDF 2.0).
+ *
+ * @example
+ * ```typescript
+ * const handler = new PdfV5SecurityHandler({
+ *     password: 'strongPassword123',
+ *     ownerPassword: 'adminPassword456'
+ * })
+ * ```
+ */
+export class PdfV5SecurityHandler extends PdfV4SecurityHandler {
+    /** User encrypted file key (UE value). */
+    protected userEncryptedFileKey?: ByteArray
+    /** Owner encrypted file key (OE value). */
+    protected ownerEncryptedFileKey?: ByteArray
+    /** Permissions entry (Perms value). */
+    protected perms?: ByteArray
+    /** Promise resolving to the file encryption key. */
+    protected fileKey?: Promise<ByteArray>
+
+    /**
+     * Creates a new V5 security handler with AES-256 encryption.
+     *
+     * @param options - Configuration options including optional pre-computed keys.
+     */
+    constructor(
+        options: PdfStandardSecurityHandlerOptions & {
+            userEncryptedFileKey?: ByteArray
+            ownerEncryptedFileKey?: ByteArray
+        },
+    ) {
+        super(options)
+        this.userEncryptedFileKey = options.userEncryptedFileKey
+        this.ownerEncryptedFileKey = options.ownerEncryptedFileKey
+
+        this.setCryptFilter(
+            'StdCF',
+            new AesV3CryptFilter({
+                authEvent: 'DocOpen',
+            }),
+        )
+
+        this.setCryptFilterForType('stream', 'StdCF')
+        this.setCryptFilterForType('string', 'StdCF')
+    }
+
+    /**
+     * Checks if the handler is ready (has user encrypted file key).
+     *
+     * @returns True if the handler has the required keys.
+     */
+    isReady(): boolean {
+        return !!this.userEncryptedFileKey
+    }
+
+    /**
+     * Initializes encryption keys, either deriving from existing values or generating new ones.
+     */
+    protected async initKeys(): Promise<void> {
+        this.fileKey ||= (async () => {
+            if (
+                this.userEncryptedFileKey &&
+                this.ownerEncryptedFileKey &&
+                this.userKey &&
+                this.ownerKey &&
+                this.perms
+            ) {
+                const derivedFileKey = await getFileKey(
+                    this.password,
+                    this.ownerPassword ?? this.password,
+                    this.userKey,
+                    this.userEncryptedFileKey,
+                    this.ownerKey,
+                    this.ownerEncryptedFileKey,
+                )
+
+                return derivedFileKey
+            }
+            const fileKey = getRandomBytes(32)
+
+            const { U, UE } = await generateUandUe(this.password, fileKey)
+
+            this.userKey = U
+            this.userEncryptedFileKey = UE
+
+            const { O, OE } = await generateOandOe(
+                this.ownerPassword ?? this.password,
+                U,
+                fileKey,
+            )
+
+            this.ownerKey = O
+            this.ownerEncryptedFileKey = OE
+
+            this.perms = await this.buildPermsEntry(
+                this.permissions ?? 0,
+                this.encryptMetadata,
+                fileKey,
+            )
+
+            return fileKey
+        })()
+
+        await this.fileKey
+    }
+
+    /**
+     * Computes the master encryption key.
+     *
+     * @returns The file encryption key.
+     * @throws Error if file key is not initialized.
+     */
+    protected async computeMasterKey(): Promise<ByteArray> {
+        await this.initKeys()
+
+        if (!this.fileKey) {
+            throw new Error('File key not initialized')
+        }
+
+        return this.fileKey
+    }
+
+    /**
+     * Builds the Perms entry for the encryption dictionary.
+     *
+     * @param flags - The permission flags.
+     * @param encryptMetadata - Whether metadata is encrypted.
+     * @param fileKey - The file encryption key.
+     * @returns The encrypted permissions entry.
+     */
+    private async buildPermsEntry(
+        flags: number,
+        encryptMetadata: boolean,
+        fileKey: ByteArray,
+    ): Promise<ByteArray> {
+        const block = new Uint8Array(16)
+
+        // a + b) permissions + 0xFFFFFFFF (little-endian)
+        const view = new DataView(block.buffer)
+        view.setUint32(0, flags, true) // little-endian
+        view.setUint32(4, 0xffffffff, true) // upper 32 bits
+
+        // c) "T" or "F"
+        block[8] = encryptMetadata ? 'T'.charCodeAt(0) : 'F'.charCodeAt(0)
+
+        // d) "adb"
+        block[9] = 'a'.charCodeAt(0)
+        block[10] = 'd'.charCodeAt(0)
+        block[11] = 'b'.charCodeAt(0)
+
+        // e) random 4 bytes
+        const randomBytes = getRandomBytes(4)
+        block.set(randomBytes, 12)
+
+        return await aes256ecbEncrypt(fileKey, block)
+    }
+
+    /**
+     * Gets the encryption key length in bits.
+     *
+     * @returns 256 for V5 encryption.
+     */
+    getKeyBits(): number {
+        return 256
+    }
+
+    /**
+     * Gets an AES-256 cipher.
+     *
+     * @returns An AES-256 cipher instance.
+     */
+    protected async getCipher(): Promise<Cipher> {
+        this.masterKey ||= await this.computeMasterKey()
+
+        return aes256(this.masterKey)
+    }
+
+    /**
+     * Gets the encryption version number.
+     *
+     * @returns 5 for AES-256 encryption.
+     */
+    getVersion(): number {
+        return 5
+    }
+
+    /**
+     * Gets the encryption revision number.
+     *
+     * @returns 6 for V5 encryption.
+     */
+    getRevision(): number {
+        return 6
+    }
+
+    /**
+     * Writes the encryption dictionary including V5-specific entries.
+     *
+     * @throws Error if required keys are not computed.
+     */
+    async write(): Promise<void> {
+        await super.write()
+        const dict = this.dict
+
+        assert(this.userEncryptedFileKey, 'User Encrypted File Key not set')
+        assert(this.ownerEncryptedFileKey, 'Owner Encrypted File Key not set')
+        assert(this.perms, 'Permissions entry not set')
+
+        dict.set('UE', new PdfString(this.userEncryptedFileKey))
+        dict.set('OE', new PdfString(this.ownerEncryptedFileKey))
+        dict.set('Perms', new PdfString(this.perms))
+    }
+
+    /**
+     * Reads V5-specific encryption parameters from the dictionary.
+     *
+     * @param encryptionDictionary - The encryption dictionary from the PDF.
+     * @throws Error if required entries are missing or invalid.
+     */
+    readEncryptionDictionary(
+        encryptionDictionary: PdfEncryptionDictionary,
+    ): void {
+        super.readEncryptionDictionary(encryptionDictionary)
+
+        const { values } = encryptionDictionary
+
+        assert(
+            values['UE'] instanceof PdfHexadecimal ||
+                values['UE'] instanceof PdfString,
+            'Invalid or missing /UE entry',
+        )
+        assert(
+            values['OE'] instanceof PdfHexadecimal ||
+                values['OE'] instanceof PdfString,
+            'Invalid or missing /OE entry',
+        )
+        assert(
+            values['Perms'] instanceof PdfString ||
+                values['Perms'] instanceof PdfHexadecimal,
+            'Invalid or missing /Perms entry',
+        )
+
+        this.userEncryptedFileKey =
+            values['UE'] instanceof PdfHexadecimal
+                ? values['UE'].bytes
+                : values['UE'].raw
+        this.ownerEncryptedFileKey =
+            values['OE'] instanceof PdfHexadecimal
+                ? values['OE'].bytes
+                : values['OE'].raw
+        this.perms =
+            values['Perms'] instanceof PdfHexadecimal
+                ? values['Perms'].bytes
+                : values['Perms'].raw
+    }
+
+    /**
+     * Computes the object encryption key (same as master key for V5).
+     *
+     * @returns The master encryption key.
+     */
+    async computeObjectKey(): Promise<ByteArray> {
+        return await this.computeMasterKey()
+    }
+
+    /**
+     * Recovers the user password from the owner password.
+     * Not supported for AES-256 encryption.
+     *
+     * @throws Error always, as this operation is not supported for V5.
+     */
+    async recoverUserPassword(
+        ownerPassword?: ByteArray | string,
+    ): Promise<string> {
+        throw new Error(
+            'Recovering user password from owner password is not supported for AES-256',
+        )
+    }
+}