Jak pracovat s PDF Encryption Engine v Python

Aspose.PDF FOSS pro Python (import aspose_pdf) implementuje ochranu PDF heslem na úrovni bajtů pomocí malé interní třídy enginu, EncryptionUtils, v aspose_pdf.engine.encryption. Zde se nachází šifra AES-CBC a algoritmy pro odvození klíčů PDF Standard Security Handleru (ISO 32000 revize 2 až 6), nezávisle na vyšší úrovni Document API. Tento průvodce nainstaluje balíček a provede vás třemi úkoly enginu: šifrování a dešifrování surových bajtů pomocí AES-CBC, odvození klíčů Standard Security Handleru pro heslo (revize 2-4) a odvození AES-256 klíčů pro dokumenty revize 5/6.

Průvodce krok za krokem

Krok 2: Importovat požadované třídy

EncryptionUtils není znovu exportováno z hlavního balíčku aspose_pdf — importujte jej přímo z podmodulu engine.encryption:

import os
from aspose_pdf.engine.encryption import EncryptionUtils

Krok 3: Šifrovat a dešifrovat data pomocí AES-CBC

encrypt_aes_cbc a decrypt_aes_cbc pracují přímo s libovolným 16-, 24- nebo 32-bajtovým klíčem (AES-128, AES-192 nebo AES-256) bez použití odvození klíče založeného na hesle. encrypt_aes_cbc interně aplikuje padding PKCS7 a decrypt_aes_cbc jej odstraňuje.

key = os.urandom(32)  # AES-256; 16- and 24-byte keys are also accepted
plaintext = b"Confidential PDF content"

ciphertext = EncryptionUtils.encrypt_aes_cbc(key, plaintext)
decrypted = EncryptionUtils.decrypt_aes_cbc(key, ciphertext)

assert decrypted == plaintext
print("Roundtrip OK, ciphertext length:", len(ciphertext))

Krok 4: Odvození standardních klíčů bezpečnostního obslužného programu pro heslo (revize 2-4)

compute_owner_key_v4 vypočítá hodnotu hesla vlastníka (O) podle Algoritmu 3.3 a compute_user_key_v4 vypočítá hodnotu hesla uživatele (U) a šifrovací klíč souboru podle Algoritmu 3.4/3.5. verify_password_v4 znovu odvodí klíč z kandidátního hesla, abyste mohli potvrdit, že otevře dokument, než mu budete důvěřovat.

owner_password = "owner-secret"
user_password = "user-secret"
key_length = 16   # 128-bit (AES/RC4); Revision 2 uses 5 (40-bit)
revision = 4
file_id = os.urandom(16)
permissions = -4  # standard PDF permissions value

o_value = EncryptionUtils.compute_owner_key_v4(
    owner_password, user_password, key_length, revision
)

u_value, encryption_key = EncryptionUtils.compute_user_key_v4(
    user_password, o_value, permissions, file_id, key_length, revision
)

verified_key = EncryptionUtils.verify_password_v4(
    user_password, u_value, o_value, permissions, file_id, key_length, revision
)
assert verified_key == encryption_key

ciphertext = EncryptionUtils.encrypt_aes_cbc(verified_key, b"Confidential PDF content")
decrypted = EncryptionUtils.decrypt_aes_cbc(verified_key, ciphertext)
assert decrypted == b"Confidential PDF content"

o_value a u_value jsou vždy 32 bajtů bez ohledu na key_length. verify_password_v4 vrací None — ne výjimku — když heslo neodpovídá.

Krok 5: Odvození klíčů AES-256 pro dokumenty revize 5/6

Bezpečnostní obslužné programy revizí 5 a 6 (AES-256) nepoužívají compute_owner_key_v4/compute_user_key_v4 — hashují heslo pomocí compute_hash_v5, které implementuje „Algoritmus 2.B“ normy ISO 32000-2. Použijte generate_file_id pro nový identifikátor souboru a derive_object_key k převodu šifrovacího klíče souboru na klíč pro konkrétní nepřímý objekt.

password = b"SecurePassword123"
salt = os.urandom(8)

password_hash = EncryptionUtils.compute_hash_v5(password, salt)
assert len(password_hash) == 32

file_id = EncryptionUtils.generate_file_id()
assert len(file_id) == 16

file_key = os.urandom(32)
object_key = EncryptionUtils.derive_object_key(file_key, 12, 0, use_aes=True)
assert len(object_key) == 16

derive_object_key míchá číslo objektu a číslo generace do klíče souboru, takže každý nepřímý objekt získá svůj vlastní klíč, i když je klíč souboru sdílený.

Časté problémy a opravy

encrypt_aes_cbc/decrypt_aes_cbc vyvolá “AES key must be 16, 24, or 32 bytes”. Argument klíče musí být skutečný AES klíč, ne surový řetězec hesla. Vygenerujte jej pomocí os.urandom(16 | 24 | 32), nebo jej nejprve odvoďte pomocí compute_user_key_v4 (Revisions 2-4) nebo compute_hash_v5 (Revize 5/6).

verify_password_v4 returns None místo vyvolání. To znamená, že heslo neodpovídá — nejde o podmínku chyby, kterou byste měli zachytit, jen o výsledek, který je potřeba zkontrolovat. Také ověřte, že permissions, file_id, key_length, a revision jsou přesně stejné hodnoty použité při výpočtu dokumentu o_value and u_value byly původně vypočítány; nesoulad v kterémkoli z nich tiše vytvoří nesprávný klíč místo toho, aby selhal nahlas.

compute_owner_key_v4 s prázdným heslem vlastníka. Passing "" for owner_password je chování definované spec, nikoli chyba — algoritmus se vrátí k použití uživatelského hesla, takže hesla vlastníka a uživatele se stanou ekvivalentními.

Klíče odvozené pro nesprávnou revizi nebo délku klíče. Revize 2 používá 40-bitové (5-bytové) RC4 klíče, revize 3/4 používají 128-bitové (16-bytové) RC4/AES klíče a revize 5/6 používají compute_hash_v5 namísto compute_owner_key_v4/compute_user_key_v4 zcela. Míchání těchto hodnot nevyvolá výjimku — jen vytvoří klíč, který dokument neotevře.

compute_hash_v5 výstup se neočekávaně mění. Třetí argument (user_key) je smíchán do hashe. Předávejte b"" explicitně, když chcete prostý hash pro ověření hesla, protože jeho vynechání není totéž jako předání prázdné hodnoty v každém místě volání.

Často kladené otázky

Proč není `EncryptionUtils` importovatelný přímo z `aspose_pdf`?

Nachází se v podbalíčku engine, protože jde o interní implementační detail ochrany heslem na úrovni dokumentu, nikoli o součást veřejného rozhraní API na vyšší úrovni. Importujte jej explicitně z aspose_pdf.engine.encryption.

Je `compute_hash_v5` stejné jako jediné volání SHA-256?

Ne. Implementuje algoritmus 2.B normy ISO 32000-2, který provádí více kol pomocí různých hashovacích algoritmů vybíraných podle mezivýsledků – záměrně dražší než jediné volání hash.

Vrací `generate_file_id()` pokaždé stejné bajty?

Ne — vrací čerstvou, náhodnou 16-bajtovou hodnotu při každém volání. Různé identifikátory souboru mění každý klíč odvozený z nich, i když je heslo stejné.

Sdílí všechny nepřímé objekty v šifrovaném PDF jeden klíč?

Ne. derive_object_key kombinuje číslo objektu a číslo generace s klíčem šifrování souboru, takže každý nepřímý objekt získá odlišný klíč specifický pro objekt.

Měl by aplikační kód volat `EncryptionUtils` přímo pro ochranu PDF heslem?

Obvykle ne. EncryptionUtils je nízkoúrovňový motor, na kterém jsou postaveny API pro hesla na úrovni dokumentu. Většina aplikací by měla chránit PDF prostřednictvím API na úrovni dokumentu a sáhnout po EncryptionUtils jen pro vlastní nástroje nebo forenzní kontrolu šifrovaných souborů.