Come proteggere e firmare documenti PDF in TypeScript

Questa guida mostra come crittografare, certificare, firmare e verificare documenti PDF con Aspose.PDF FOSS per TypeScript. Document.Save() e Document.Open() gestiscono la crittografia a chiave pubblica verso i certificati dei destinatari, mentre Document.Certify(), Document.Sign() e Document.VerifySignatures() gestiscono firme digitali in stile PAdES. Richiede Node.js 22 o versioni successive.

Guida passo-passo

Passo 1: Installa il pacchetto

git clone https://github.com/aspose-pdf-foss/Aspose.PDF-FOSS-for-TypeScript.git
cd Aspose.PDF-FOSS-for-TypeScript
npm install
npm run build

Verifica l’installazione importando la classe Document in un nuovo file TypeScript — questa riga dovrebbe risolversi senza errori una volta che il pacchetto è installato:

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

Passo 2: Importa le classi richieste

Importa Document per aprire, salvare, firmare e verificare il file; i passaggi di firma e crittografia di seguito passano oggetti opzione semplici, quindi non sono necessari ulteriori import:

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

Passo 3: Cifra un documento per i certificati del destinatario

Document.Save() accetta un’opzione encrypt contenente uno o più recipients, ognuno identificato da un certificato (stringa PEM o byte DER), un algorithm, e permissions condivisi:

const doc = Document.OpenFile('report.pdf');

const bytes = doc.Save({
  encrypt: {
    recipients: [{ certificate: recipientCertPem }],
    algorithm: 'aes256', // 'aes256' (default) | 'aes128' | 'rc4'
    permissions: { copying: false }, // shared across all recipients
  },
});

Passo 4: Apri un documento cifrato

Passa un’opzione recipient a Document.Open() con la chiave privata e il certificato corrispondenti, oppure un bundle PKCS#12:

const opened = Document.Open(bytes, {
  recipient: { privateKey, certificate: recipientCertPem },
  // or: recipient: { pkcs12: p12Bytes, passphrase: '…' },
});

console.log(opened.Permissions); // recovered permission flags (not enforced)

Passo 5: Certifica e firma un documento

Document.Certify() e Document.Sign() sono entrambi asincroni e accettano un’identità (certificate + privateKey) più opzioni che descrivono il campo della firma, l’aspetto e il motivo. La certificazione dovrebbe avvenire per prima, su tutto il file; ulteriori firme di approvazione vengono aggiunte incrementalmente in seguito:

async function certifyAndSign(sourcePath: string, signaturePageIndex: number): Promise<void> {
  const certifying = Document.OpenFile(sourcePath);
  await certifying.Certify(
    { certificate: authorCert, privateKey: authorKey },
    {
      permissions: 'form-fill',
      reason: 'Certifying the document',
      fieldName: 'Certification',
      appearance: { page: signaturePageIndex, rect: [400, 100, 550, 140] },
    },
  );
  const certifiedBytes = certifying.Save();

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

Passo 6: Verifica le firme

Document.VerifySignatures() è asincrono e restituisce un SignatureReport per campo firma, ciascuno riportando i integrity crittografici, la validità del signature, e se coversWholeFile:

async function verify(path: string): Promise<void> {
  const doc = Document.OpenFile(path);
  const reports = await doc.VerifySignatures();
  for (const r of reports) {
    console.log(`${r.name}: integrity=${r.integrity} signature=${r.signature} `
      + `coversWholeFile=${r.coversWholeFile} docMDP=${r.docMDP}`);
  }
}

Problemi comuni e soluzioni

Document.Sign() / Document.Certify() lanciare o bloccare. Entrambi sono asincroni — await la chiamata. Dimenticando await lascia la promessa restituita non risolta e la scrittura avviene prima che la firma sia completata.

Una firma di approvazione successiva invalida la certificazione. Firma incrementalmente: salva prima i byte certificati (certifying.Save()), riaprili con Document.Open(), poi chiama Sign() su quel documento riaperto — scrivere una riscrittura completa invece di un’aggiunta incrementale rompe la certificazione /ByteRange digest.

VerifySignatures() reports coversWholeFile: false per la prima firma ma true per l’ultima. Questo è previsto per una catena certify-then- sign: la certificazione è stata firmata prima che l’approvazione fosse aggiunta, quindi solo la firma più recente della /ByteRange si estende fino alla fine del file.

La decrittazione fallisce con la chiave privata corretta. Conferma il certificate passato a recipient corrisponde esattamente al certificato a cui il documento è stato crittografato in Document.Save()’s recipients elenco — un certificato riemesso con una nuova coppia di chiavi non decritterà i dati crittografati con quella vecchia.

Domande frequenti

Un documento può essere crittografato per più di un destinatario?

Sì — recipients nell’opzione encrypt di Document.Save() accetta un array; la chiave privata corrispondente di qualsiasi destinatario può aprire il file risultante.

Quale formato di firma produce `Document.Sign()`?

Passare subFilter: 'PAdES' nelle opzioni di firma produce una firma compatibile PAdES; ometterlo utilizza il subfilter di firma predefinito della libreria.

Come posso verificare se un documento è certificato o semplicemente firmato?

Ispeziona il campo docMDP sul SignatureReport restituito da Document.VerifySignatures() — una firma di certificazione segnala un verdetto di permesso DocMDP; una firma solo di approvazione non lo fa.

I `Permissions` recuperati dopo `Document.Open()` sono applicati dalla libreria?

No — opened.Permissions segnala i flag di permesso registrati nel file crittografato per l’ispezione; la loro applicazione in un’applicazione è responsabilità del chiamante.