Come aggiungere firme di sicurezza PDF in Python

Aspose.PDF FOSS per Python include un rilevatore di compromissione della firma che esamina un PDF già firmato alla ricerca di un modello di manomissione specifico: byte significativi aggiunti dopo l’intervallo di byte firmato della firma, un rischio unico ai file PDF aggiornati in modo incrementale. Questa guida aggiunge tale controllo a un flusso di lavoro Python utilizzando le classi SignaturesCompromiseDetector e CompromiseCheckResult. Creare o applicare nuove firme digitali è una parte separata della libreria e non è trattata qui. La libreria si installa con il comando riportato di seguito.

Guida passo-passo

Passo 1: Installa il pacchetto

Installa il pacchetto FOSS Aspose.PDF:

git clone https://github.com/aspose-pdf-foss/Aspose-PDF-FOSS-for-Python.git
cd Aspose-PDF-FOSS-for-Python
pip install -e .

Verifica l’installazione importando SignaturesCompromiseDetector e stampando un messaggio di conferma:

from aspose_pdf import SignaturesCompromiseDetector
print("aspose-pdf-foss-for-python is ready.")

Passo 2: Importa le classi necessarie

from aspose_pdf import CompromiseCheckResult, SignaturesCompromiseDetector

Passo 3: Prepara un oggetto che espone un elenco di firme

SignaturesCompromiseDetector non analizza direttamente un PDF — il suo costruttore accetta qualsiasi oggetto che espone un attributo signatures: un elenco di voci di firma, ciascuna contenente valid, byte_range e reference_data. PdfSignature — una classe semplice, direttamente costruibile — corrisponde a quella forma, quindi è utile per vedere come si comporta il controllo prima di collegarlo al tuo oggetto documento:

from types import SimpleNamespace
from aspose_pdf import PdfSignature

with open("signed.pdf", "rb") as handle:
    pdf_bytes = handle.read()

signature = PdfSignature(
    name="Signature1",
    contents=b"...",  # PKCS#7 signed-data blob from the signature dictionary
    byte_range=[0, 1024, 1040, len(pdf_bytes) - 1040],
    reference_data=pdf_bytes,
)

signed_document = SimpleNamespace(signatures=[signature])

Sostituisci signed_document con il tuo oggetto documento personale una volta che espone un elenco signatures con la stessa struttura — qualsiasi oggetto con quell’attributo funziona.

Passo 4: Esegui il controllo di compromissione

from aspose_pdf import SignaturesCompromiseDetector

detector = SignaturesCompromiseDetector(signed_document)
result = detector.check()

print(result.compromised)                # bool
print(result.has_compromised_signatures)  # bool -- same value as compromised
print(result.signatures_coverage)         # int -- number of signatures inspected
print(result.reasons)                     # list[str] -- human-readable findings

check() percorre ogni firma in signed_document.signatures, cercando contenuti non firmati aggiunti dopo l’intervallo di byte firmato di ciascuna firma. Un CompromiseCheckResult riassume il risultato: compromised e has_compromised_signatures riportano lo stesso valore booleano con due nomi, signatures_coverage indica quante firme sono state esaminate, e reasons elenca una spiegazione leggibile dall’uomo per ogni problema riscontrato.

Passo 5: Gestisci un documento senza firme

Un elenco signatures vuoto o mancante non è una condizione di errore — viene segnalato allo stesso modo di un documento senza nulla da controllare:

from types import SimpleNamespace
from aspose_pdf import SignaturesCompromiseDetector

unsigned_document = SimpleNamespace(signatures=[])
detector = SignaturesCompromiseDetector(unsigned_document)
result = detector.check()

print(result.compromised)  # False
print(result.reasons)      # ["unsigned document"]

Passare SignaturesCompromiseDetector(None) — il valore predefinito del costruttore — si comporta allo stesso modo.

Problemi comuni e soluzioni

compromised is False per un PDF che sai è stato modificato dopo la firma

SignaturesCompromiseDetector cerca specificamente byte non firmati aggiunti dopo l’intervallo di byte firmati di una firma — un modello tipico di manomissione ingenua tramite aggiornamento incrementale. Non esegue una verifica completa della firma crittografica. Per questo, chiama validate() sull’oggetto PdfSignature individuale.

compromised and has_compromised_signatures sembra ridondante

Sono lo stesso valore: compromised è una proprietà calcolata che restituisce has_compromised_signatures. Usa il nome che risulta più leggibile nel tuo codice.

Nessuna eccezione viene sollevata quando il documento non ha signatures alcun attributo

SignaturesCompromiseDetector tratta un documento senza l’attributo signatures, o document=None, allo stesso modo di un documento non firmato — check() restituisce un risultato con has_compromised_signatures=False e reasons=["unsigned document"] invece di sollevare.

Un malformato PdfSignature non viene segnalato

check() ignora qualsiasi firma il cui byte_range non è una lista a 4 elementi, o il cui reference_data non è bytes/bytearray, invece di sollevare un’eccezione o segnalare che è compromessa. Una firma costruita con la forma errata viene silenziosamente esclusa dal controllo, non segnalata.

Confondere questo rilevatore con la creazione di firme

SignaturesCompromiseDetector e CompromiseCheckResult ispezionano solo le firme già presenti su un documento — non hanno alcun metodo per creare, applicare o incorporare una nuova firma.

Domande Frequenti

Cosa conta esattamente come “compromessa” qui?

Byte significativi, non spazi bianchi, aggiunti al PDF dopo l’intervallo di byte firmato di una firma — con due eccezioni già gestite dal rilevatore: una firma o timestamp successivo che copre quegli stessi byte, e un aggiornamento incrementale che aggiunge solo materiale di convalida (come un /DSS) senza sovrapporre nuovo contenuto come annotazioni.

Questo verifica la validità crittografica della firma stessa?

No. SignaturesCompromiseDetector controlla i pattern di manomissione intorno all’intervallo di byte firmato. La validità crittografica è un controllo separato, disponibile tramite PdfSignature.validate().

Cosa mi dice `signatures_coverage`?

Il numero di firme che il controllo ha effettivamente esaminato sul documento fornito — utile per confermare che il rilevatore abbia visto le firme che ti aspettavi prima di fidarti di un risultato pulito.

Posso controllare un documento con più firme contemporaneamente?

Sì. check() itera ogni voce in signed_document.signatures e restituisce un CompromiseCheckResult aggregato che copre tutte.

Devo creare io gli oggetti `PdfSignature` in un utilizzo normale?

No — la costruzione di PdfSignature al passo 3 serve per esplorare direttamente il comportamento del rilevatore. In un flusso di lavoro reale, passa qualsiasi oggetto che il tuo codice di caricamento del documento produce già, purché esponga una lista signatures di voci con forma PdfSignature.