Security

Panoramica

Questa pagina tratta password, crittografia e firme digitali. Document.OpenFile() / Document.Open() accettano una password per aprire un documento protetto, Document.Save() accetta un’opzione encrypt per proteggerne uno, e Document.Sign() / Document.Certify() / Document.VerifySignatures() aggiungono e verificano le firme digitali.


Apertura e Decrittazione di Documenti Protetti da Password

Fornisci { password: '...' } a Document.OpenFile() o Document.Open() per aprire un documento protetto da una password utente. Se la password è mancante o errata, la chiamata genera InvalidPasswordError.

import { Document, InvalidPasswordError } from '@asposefoss/pdf';

try {
  const doc = Document.OpenFile('secret.pdf', { password: 'hunter2' });
  doc.WriteTo('decrypted.pdf');    // output is plaintext
} catch (e) {
  if (e instanceof InvalidPasswordError) console.error('wrong password');
  else throw e;
}

Crittografia al Salvataggio

Document.Save() (e Document.WriteTo()) accettano un’opzione encrypt. La crittografia basata su password è il caso più comune; la libreria supporta anche la crittografia a chiave pubblica verso uno o più certificati destinatari, aperta nuovamente con la chiave privata del destinatario.

// Encrypt to one or more recipient certificates (PEM string or DER bytes):
const bytes = doc.Save({
  encrypt: {
    recipients: [{ certificate: recipientCertPem }],
    algorithm: 'aes256',                 // 'aes256' (default) | 'aes128' | 'rc4'
    permissions: { copying: false },     // shared across all recipients
  },
});

// Open with the recipient's private key + certificate, or a PKCS#12 bundle:
const opened = Document.Open(bytes, {
  recipient: { privateKey, certificate: recipientCertPem },
});
console.log(opened.Permissions);         // recovered permission flags (not enforced)

Firma e Certificazione

Document.Certify() aggiunge una firma di certificazione (autore) che trasporta una trasformazione DocMDP e dichiara quali modifiche successive sono consentite; Document.Sign() aggiunge una ulteriore firma di approvazione ordinaria che può essere aggiunta incrementalmente sopra. Entrambe accettano un firmatario { certificate, privateKey } e un oggetto di opzioni (reason, location, name, fieldName, e — per Certify() — permissions).

const certifying = Document.OpenFile('report.pdf');
await certifying.Certify(
  { certificate: author.certificate, privateKey: author.privateKey },
  { permissions: 'form-fill', reason: 'Certifying the report', fieldName: 'Certification' },
);
const certifiedBytes = certifying.Save();

const approving = Document.Open(certifiedBytes);
await approving.Sign(
  { certificate: approver.certificate, privateKey: approver.privateKey },
  { reason: 'Approved for publication', fieldName: 'Approval' },
);
approving.WriteTo('signed.pdf');

Verifica delle firme

Document.VerifySignatures() controlla ogni firma nel documento: ricalcola ogni digest /ByteRange, verifica il CMS staccato e segnala cosa è cambiato dopo ciascuna firma. Restituisce un SignatureReport[], una voce per firma.

const reports = await Document.OpenFile('signed.pdf').VerifySignatures();
for (const r of reports) {
  console.log(r.name, 'integrity:', r.integrity, 'signature:', r.signature);
}

Suggerimenti e migliori pratiche

  • Gestisci InvalidPasswordError in modo specifico prima di un catch-all più ampio quando apri input non attendibili, così potrai reagire diversamente a una password errata rispetto a un file corrotto.
  • Invoca Certify() prima di qualsiasi chiamata Sign() — una firma di certificazione stabilisce i permessi DocMDP su cui vengono sovrapposte le firme di approvazione successive.
  • Document.Open() restituisce Permissions recuperati dopo la decrittazione a chiave pubblica, ma la libreria non li applica autonomamente — considerali solo a scopo informativo.
  • VerifySignatures() è async — await (o gestisci il Promise restituito) prima di leggere l’array del report.

Problemi comuni

ProblemaCausaCorrezione
Document.OpenFile() / Document.Open() lancia InvalidPasswordErrorIl documento è protetto da password e non è stata fornita alcuna password, o è stata fornita quella sbagliataPassa { password: '...' } a Document.OpenFile() / Document.Open()
La decrittazione a chiave pubblica fallisceÈ stata passata la chiave privata o il certificato errato, o nessuno dei due corrisponde a una voce recipients usata al momento della cifraturaConferma che l’opzione recipient abbia privateKey / certificate (o bundle PKCS#12) corrisponda a uno dei destinatari originali
L’approvazione tramite firma invalida la certificazioneSign() è stato chiamato con permessi che la trasformazione di certificazione DocMDP non consenteImposta un valore permissions su Certify() (ad es. 'form-fill') sufficientemente ampio per le modifiche che i firmatari successivi apporteranno
VerifySignatures() segnala un controllo di integrità non riuscitoI byte firmati sono stati modificati dopo la firma, al di fuori di un aggiornamento incrementale coperto dalla firmaFirma nuovamente il documento dopo ulteriori modifiche

FAQ

Qual è la differenza tra Sign e Certify?

Certify() aggiunge la prima firma certificante e dichiara (tramite una trasformazione DocMDP) quali modifiche successive sono permesse. Sign() aggiunge una firma d’approvazione ordinaria, inserita in modo incrementale sopra tutto ciò che c’era prima.

Come aprire un PDF protetto da password?

Passa { password: '...' } a Document.OpenFile() o Document.Open() e intercetta InvalidPasswordError se la password potrebbe essere errata.

Questa libreria impone le flag di permesso PDF?

No. Document.Open() recupera le flag Permissions da un documento crittografato per consentirti di ispezionarle, ma non limita quello che il tuo codice può fare con il documento aperto.

Come verifico se le firme di un PDF firmato sono ancora valide?

Chiama Document.VerifySignatures() (un metodo async) e ispeziona i campi integrity e signature di ogni SignatureReport restituito.


API Reference Sommario

Classe/MetodoDescrizione
Document.OpenFile() / Document.Open()Apri un documento, opzionalmente protetto da password o chiave pubblica
InvalidPasswordErrorLanciata quando una password è mancante o errata
Document.Save() / Document.WriteTo()Salva un documento, opzionalmente con un’opzione encrypt
PermissionsFlag di autorizzazione recuperati da un documento crittografato
Document.Certify()Inserisci la firma di certificazione (autore) con una trasformazione DocMDP
Document.Sign()Aggiungi una firma di approvazione
Document.VerifySignatures()Verifica ogni firma nel documento
SignatureReportRisultato della verifica di una firma: name, integrity, signature

Vedi anche

 Italiano