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
InvalidPasswordErrorespecificamente 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 chamadasSign()— uma assinatura de certificação estabelece as permissões DocMDP sobre as quais as assinaturas de aprovação posteriores são sobrepostas. Document.Open()devolvePermissionsrecuperados após descriptografia de chave pública, mas a biblioteca não os impõe — trate-os como informativos.VerifySignatures()éasync—awaitele (ou trate oPromiseretornado) antes de ler o array de relatório.
Problemas Comuns
| Problema | Causa | Correção |
|---|---|---|
Document.OpenFile() / Document.Open() lança InvalidPasswordError | O documento está protegido por senha e nenhuma senha, ou a senha errada, foi fornecida | Passe { password: '...' } para Document.OpenFile() / Document.Open() |
| A descriptografia de chave pública falha | A chave privada ou certificado errado foi passado, ou nenhum deles corresponde a qualquer entrada recipients usada no momento da criptografia | Confirme 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ção | Sign() foi chamado com permissões que a transformação de certificação DocMDP não permite | Defina 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 quebrada | Os bytes assinados foram modificados após a assinatura, fora de uma atualização incremental coberta pela assinatura | Assine 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étodo | Descrição |
|---|---|
Document.OpenFile() / Document.Open() | Abrir um documento, opcionalmente protegido por senha ou chave pública |
InvalidPasswordError | Lançado quando uma senha está ausente ou incorreta |
Document.Save() / Document.WriteTo() | Salvar um documento, opcionalmente com uma opção encrypt |
Permissions | Flags 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 |
SignatureReport | Resultado da verificação de uma assinatura: name, integrity, signature |