TypeScript'te PDF Belgelerini Güvence Altına Almak ve İmzalamak Nasıl Yapılır

Bu kılavuz, TypeScript için Aspose.PDF FOSS ile PDF belgelerini nasıl şifreleyeceğinizi, sertifikalandıracağınızı, imzalayacağınızı ve doğrulayacağınızı gösterir. Document.Save() ve Document.Open(), alıcı sertifikalarına yönelik açık anahtar şifrelemesini yönetirken, Document.Certify(), Document.Sign() ve Document.VerifySignatures() PAdES tarzı dijital imzaları yönetir. Node.js 22 veya daha yeni bir sürüm gerektirir.

Adım Adım Kılavuz

Adım 1: Paketi Yükleyin

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

Kurulumu, yeni bir TypeScript dosyasında Document sınıfını içe aktararak doğrulayın — paket yüklendikten sonra bu satır hatasız şekilde çözülmelidir:

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

Adım 2: Gerekli Sınıfları İçe Aktarın

Dosyayı açmak, kaydetmek, imzalamak ve doğrulamak için Document içe aktarın; aşağıdaki imzalama ve şifreleme adımları düz seçenek nesneleri geçirir, bu nedenle başka bir içe aktarmaya gerek yok:

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

Adım 3: Belgeyi Alıcı Sertifikalarına Şifrele

Document.Save(), bir encrypt seçeneği kabul eder ve bu seçenek bir veya daha fazla recipients içerir; her biri bir sertifika (PEM dizesi veya DER baytları), bir algorithm ve ortak permissions ile tanımlanır:

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
  },
});

Adım 4: Şifreli Bir Belgeyi Aç

Eşleşen özel anahtar ve sertifika ya da bir PKCS#12 paketi ile Document.Open()‘e bir recipient seçeneği geçirin:

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

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

Adım 5: Bir Belgeyi Onayla ve İmzala

Document.Certify() ve Document.Sign() her ikisi de eşzamansızdır ve bir kimlik (certificate + privateKey) ile birlikte imza alanını, görünümünü ve nedenini tanımlayan seçenekleri alır. Onaylama önce, tüm dosya üzerinde gerçekleşmelidir; ardından ek onay imzaları artarak eklenir:

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');
}

Adım 6: İmzaları Doğrula

Document.VerifySignatures() eşzamansızdır ve imza alanı başına bir SignatureReport döndürür, her biri kriptografik integrity, signature geçerliliğini ve coversWholeFile olup olmadığını rapor eder:

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}`);
  }
}

Yaygın Sorunlar ve Çözümler

Document.Sign() / Document.Certify() throw ya da takıl. İkisi de eşzamansızdır — await call. Unutma await döndürülen promise’ı çözümlenmemiş bırakır ve write, signing tamamlanmadan önce gerçekleşir.

Daha sonraki approval signature sertifikayı geçersiz kılar. Artımlı olarak imzala: sertifikalı baytları önce kaydet (certifying.Save()), yeniden aç onları ile Document.Open(), then call Sign() yeniden açılan belgede — artımlı ekleme yerine tam bir yeniden yazma yapmak sertifikanın /ByteRange özetini.

VerifySignatures() reports coversWholeFile: false ilk imza için ancak true sonuncu için. Bu, önce sertifikalandırıp sonra imzalama zinciri için beklenen bir durumdur: sertifika, onayın eklenmesinden önce imzalanmıştı, bu yüzden yalnızca en son imzanın /ByteRange dosyanın sonuna kadar uzanır.

Doğru özel anahtar ile şifre çözme başarısız olur. Onaylayın certificate geçirildi recipient belgenin şifrelendiği kesin sertifikayla eşleşir Document.Save()’s recipients liste — yeni bir anahtar çiftiyle yeniden verilen bir sertifika, eski anahtar altında şifrelenmiş verileri çözemeyecektir.

Sıkça Sorulan Sorular

Bir belge birden fazla alıcıya şifrelenebilir mi?

Evet — recipients, Document.Save()‘in encrypt seçeneğinde bir dizi kabul eder; herhangi bir alıcının eşleşen özel anahtarı oluşan dosyayı açabilir.

`Document.Sign()` hangi imza formatını üretir?

İmza seçeneklerinde subFilter: 'PAdES' geçirildiğinde PAdES uyumlu bir imza oluşturulur; bırakılması durumunda kütüphanenin varsayılan imza alt süzgeci kullanılır.

Bir belgenin sertifikalı mı yoksa sadece imzalı mı olduğunu nasıl kontrol ederim?

Document.VerifySignatures() tarafından döndürülen SignatureReport‘deki docMDP alanını inceleyin — bir sertifikasyon imzası DocMDP izin kararı rapor eder; sadece onay imzası bunu raporlamaz.

`Document.Open()` sonrasında kurtarılan `Permissions` kütüphane tarafından uygulanıyor mu?

Hayır — opened.Permissions, denetleme için şifreli dosyada kaydedilen izin bayraklarını rapor eder; bunların bir uygulamada uygulanması çağıranın sorumluluğundadır.