Security

Visão geral

Esta página cobre senhas, criptografia e assinaturas digitais. Document.OpenFile() / Document.Open() aceitam uma senha para abrir um documento protegido, Document.Save() aceita uma opção encrypt para proteger um, e Document.Sign() / Document.Certify() / Document.VerifySignatures() adicionam e verificam assinaturas digitais.


Abrindo e Descriptografando Documentos Protegidos por Senha

Passe { password: '...' } para Document.OpenFile() ou Document.Open() para abrir um documento protegido com uma senha de usuário. Se a senha estiver ausente ou incorreta, a chamada lança 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;
}

Criptografando ao Salvar

Document.Save() (e Document.WriteTo()) aceitam uma opção encrypt. A criptografia baseada em senha é o caso mais comum; a biblioteca também oferece suporte à criptografia de chave pública para um ou mais certificados de destinatário, que são abertos novamente com a chave privada do destinatário.

// 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)

Assinando e Certificando

Document.Certify() adiciona uma assinatura de certificação (autor) que carrega uma transformação DocMDP que declara quais alterações posteriores são permitidas; Document.Sign() adiciona uma assinatura de aprovação ordinária adicional que pode ser anexada incrementalmente por cima. Ambas recebem um assinante { certificate, privateKey } e um objeto de opções (reason, location, name, fieldName, e — para 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');

Verificando assinaturas

Document.VerifySignatures() verifica cada assinatura no documento: ele recalcula cada digest /ByteRange, verifica o CMS destacado e relata o que mudou após cada assinatura. Ele devolve um SignatureReport[], uma entrada por assinatura.

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

Dicas e boas práticas

  • Capture InvalidPasswordError especificamente antes de um tratamento genérico ao abrir entrada não confiável, para que você possa reagir de forma diferente a uma senha incorreta do que a um arquivo corrompido.
  • Chame Certify() antes de quaisquer chamadas Sign() — uma assinatura de certificação estabelece as permissões DocMDP sobre as quais as assinaturas de aprovação posteriores são sobrepostas.
  • Document.Open() devolve Permissions recuperados após descriptografia de chave pública, mas a biblioteca não os impõe — trate-os como informativos.
  • VerifySignatures() é async — await ele (ou trate o Promise retornado) antes de ler o array de relatório.

Problemas Comuns

ProblemaCausaCorreção
Document.OpenFile() / Document.Open() lança InvalidPasswordErrorO documento está protegido por senha e nenhuma senha, ou a senha errada, foi fornecidaPasse { password: '...' } para Document.OpenFile() / Document.Open()
A descriptografia de chave pública falhaA chave privada ou certificado errado foi passado, ou nenhum deles corresponde a qualquer entrada recipients usada no momento da criptografiaConfirme se o privateKey / certificate da opção recipient (ou pacote PKCS#12) corresponde a um dos destinatários originais
Uma assinatura de aprovação invalida a certificaçãoSign() foi chamado com permissões que a transformação de certificação DocMDP não permiteDefina um valor permissions em Certify() (por exemplo, 'form-fill') amplo o suficiente para as alterações que os assinantes posteriores farão
VerifySignatures() relata uma verificação de integridade quebradaOs bytes assinados foram modificados após a assinatura, fora de uma atualização incremental coberta pela assinaturaAssine novamente o documento após quaisquer edições adicionais

FAQ

Qual é a diferença entre Sign e Certify?

Certify() adiciona a primeira assinatura de certificação e declara (via uma transformação DocMDP) quais alterações posteriores são permitidas. Sign() adiciona uma assinatura de aprovação comum, anexada incrementalmente sobre tudo o que veio antes.

Como abrir um PDF protegido por senha?

Passe { password: '...' } para Document.OpenFile() ou Document.Open(), e capture InvalidPasswordError se a senha puder estar errada.

Esta biblioteca impõe as flags de permissão de PDF?

Não. Document.Open() recupera as flags Permissions de um documento criptografado para que você as inspecione, mas não restringe o que seu código pode fazer com o documento aberto.

Como verifico se as assinaturas de um PDF assinado ainda são válidas?

Chame Document.VerifySignatures() (um método async) e inspecione os campos integrity e signature de cada SignatureReport retornado.


API Reference Resumo

Classe/MétodoDescrição
Document.OpenFile() / Document.Open()Abrir um documento, opcionalmente protegido por senha ou chave pública
InvalidPasswordErrorLançado quando uma senha está ausente ou incorreta
Document.Save() / Document.WriteTo()Salvar um documento, opcionalmente com uma opção encrypt
PermissionsFlags de permissão recuperadas de um documento criptografado
Document.Certify()Adicionar uma assinatura de certificação (autor) com uma transformação DocMDP
Document.Sign()Adicionar uma assinatura de aprovação
Document.VerifySignatures()Verificar todas as assinaturas no documento
SignatureReportResultado da verificação de uma assinatura: name, integrity, signature

Ver também

 Português