Validar assinaturas - Rest PKI

Produto legado

O Rest PKI é um produto legado: continua recebendo correções de bugs e de segurança, mas novas integrações em nuvem devem usar o Rest PKI Core, que também atende à maioria das APIs do Rest PKI. Esta página é para integrações existentes com o Rest PKI. Veja a referência rápida do Rest PKI.

O seu backend envia um arquivo assinado ao Rest PKI, que o abre, lista os signatários e valida cada assinatura. Não há etapa no navegador. O Rest PKI abre assinaturas em PDF (PAdES), arquivos CMS/CAdES (.p7s) e assinaturas XML.

O código desta página é C#, do projeto de exemplos em ASP.NET MVC, que usa o Lacuna.RestPki.Client 1.24.1. Os mesmos samples existem em outras linguagens: veja a disponibilidade de exemplos por projeto.

Fluxo

1. Crie o RestPkiClient com o seu endpoint e o seu token de acesso (veja a referência rápida).
2. Crie um PadesSignatureExplorer, CadesSignatureExplorer ou XmlSignatureExplorer e defina Validate = true, a política de assinatura e o contexto de segurança.
3. Passe o arquivo assinado com SetSignatureFile().
4. Chame OpenAsync() (no CAdES, OpenAndExtractContentAsync() para obter também o conteúdo assinado).
5. Leia o certificado, a data da assinatura e o ValidationResults de cada signatário.

Explorador	Endpoint	Resposta
PadesSignatureExplorer	POST Api/PadesSignatures/Open	PadesSignatureModel
CadesSignatureExplorer	POST Api/CadesSignatures/Open	CadesSignatureModel
XmlSignatureExplorer	POST Api/XmlSignatures/Open	uma lista de XmlSignatureModel

Assinaturas em PDF (PAdES)

O sample aceita qualquer assinatura PAdES (StandardPadesSignaturePolicies.Basic) cujo certificado o contexto de segurança considere confiável:

var sigExplorer = new PadesSignatureExplorer(Util.GetRestPkiClient()) {
	Validate = true,
	DefaultSignaturePolicyId = StandardPadesSignaturePolicies.Basic,
	SecurityContextId = Util.GetSecurityContextId()
};
sigExplorer.SetSignatureFile(userfilePath);
var signature = await sigExplorer.OpenAsync();

Assinaturas CAdES

O sample de CAdES aceita as políticas CAdES da ICP-Brasil em SignaturePolicyCatalog.GetPkiBrazilCades() (AD-RB, AD-RT e AD-RC) e também obtém o conteúdo assinado quando o arquivo o traz:

var sigExplorer = new CadesSignatureExplorer(Util.GetRestPkiClient()) {
	Validate = true,
	AcceptableExplicitPolicies = SignaturePolicyCatalog.GetPkiBrazilCades(),
	SecurityContextId = Util.GetSecurityContextId(),
};
sigExplorer.SetSignatureFile(userfilePath);
var data = await sigExplorer.OpenAndExtractContentAsync();
var signature = data.Signature;
var encapsulatedContent = data.Signature.HasEncapsulatedContent ? data.EncapsulatedContent : null;

• OpenAndExtractContentAsync() define extractEncapsulatedContent na requisição. O Rest PKI guarda o conteúdo extraído por uma hora, e o cliente o devolve como um arquivo que você lê com GetContent() ou grava com WriteToFile().
• O Rest PKI não informa o tipo de arquivo do conteúdo: o sample supõe um PDF.
• Para uma assinatura destacada (detached), o cliente também tem SetDataFile(). TODO(docs): nenhum sample mostra como validar uma assinatura CAdES destacada.

Assinaturas XML

O sample de XML aceita qualquer assinatura XmlDSig (StandardXmlSignaturePolicies.XmlDSigBasic) cujo certificado o contexto de segurança considere confiável. OpenAsync() devolve uma lista, com um item por assinatura no documento:

var sigExplorer = new XmlSignatureExplorer(Util.GetRestPkiClient()) {
	Validate = true,
	DefaultSignaturePolicyId = StandardXmlSignaturePolicies.XmlDSigBasic,
	SecurityContextId = Util.GetSecurityContextId()
};
sigExplorer.SetSignatureFile(userfilePath);
var signatures = await sigExplorer.OpenAsync();

Cada assinatura XML também tem um Type (FullXml, XmlElement ou DetachedResource) e o SignedElement.

Políticas de assinatura

Cada assinatura é validada segundo uma política de assinatura:

• DefaultSignaturePolicyId valida as assinaturas que não têm política explícita e aquelas cuja política explícita não está em AcceptableExplicitPolicies. Para aceitar só uma lista de políticas explícitas, omita-o.
• AcceptableExplicitPolicies lista as políticas explícitas a aceitar, como as da ICP-Brasil.
• Uma assinatura sem política explícita, quando não há política padrão, falha na validação.

As políticas padrão ficam em StandardPadesSignaturePolicies (Basic, BasicWithoutLtv, AdobeReader), StandardCadesSignaturePolicies (CadesBes, CadesBesWithSigningTimeAndNoCrls, CmsPermissive) e StandardXmlSignaturePolicies (XadesBes, XmlDSigBasic, CodSha1, CodSha256), cada uma com as políticas da ICP-Brasil aninhadas em PkiBrazil; SignaturePolicyCatalog agrupa as da ICP-Brasil.

Contexto de segurança

O contexto de segurança decide quais certificados raiz são confiáveis. As políticas PAdES Basic, CAdES CadesBes e XML XmlDSigBasic e XadesBes exigem um, ou a chamada falha com SecurityContextRequired; as políticas da ICP-Brasil trazem o próprio contexto, que um contexto passado por você substitui.

Contexto de segurança	Confia em	Id
StandardSecurityContexts.PkiBrazil	Raízes da ICP-Brasil	201856ce-273c-4058-a872-8937bd547d36
StandardSecurityContexts.PkiItaly	Raízes da ICP italiana	c438b17e-4862-446b-86ad-6f85734f0bfe
StandardSecurityContexts.WindowsServer	Raízes confiáveis do Windows	3881384c-a54d-45c5-bbe9-976b674f5ec7
StandardSecurityContexts.LacunaTest	Raízes da ICP-Brasil, do Windows e de teste da Lacuna; só para desenvolvimento	803517ad-3bbc-4169-b085-60053a8f6dbf

Os samples usam LacunaTest nos builds de debug, para aceitar os certificados de teste, e PkiBrazil nos demais. Em uma instância on-premises, pode ser preciso criar o LacunaTest antes (veja Habilitando o contexto de segurança de testes da Lacuna).

public static Guid GetSecurityContextId() {
#if DEBUG
	return StandardSecurityContexts.LacunaTest;
#else
	return Lacuna.RestPki.Api.StandardSecurityContexts.PkiBrazil;
#endif
}

Duas outras opções relaxam a validação: IgnoreRevocationStatusUnknown ignora erros por status de revogação desconhecido (padrão false, desde o Rest PKI 1.16.0), e TrustUncertifiedSigningTime usa a data da assinatura informada pelo signatário como referência de data da validação (desde a 1.22.0). Nenhum dos samples as define.

Ler os resultados

• Uma assinatura PAdES ou CAdES tem Signers; cada signatário tem o seu Certificate, SigningTime, MessageDigest, SignaturePolicy, Timestamps e ValidationResults. Um signatário PAdES também tem IsDocumentTimestamp e SignatureFieldName. Uma assinatura XML tem os mesmos campos, sem MessageDigest.
• ValidationResults tem IsValid, Errors, Warnings, PassedChecks e Summary, e ToString() lista todas as verificações. Ele só é preenchido quando Validate é true.

A página do sample mostra, para cada signatário, o nome comum do titular, um selo "valid" ou "invalid" a partir de ValidationResults.IsValid, a data da assinatura, o resumo da mensagem (message digest), a política, os campos ICP-Brasil do certificado e o ValidationResults.ToString() completo.

Erros

• Um arquivo que não é um PDF, CAdES ou XML válido falha com InvalidPdf, InvalidCades ou InvalidXml (HTTP 422). Veja os códigos de retorno.
• Quando um limite da conta está definido e é excedido, o Rest PKI responde HTTP 429 com os headers X-RateLimit-Limit e X-RateLimit-Remaining.
• TODO(docs): como é informada uma assinatura sem política aceitável.

Veja também

• Autenticação com certificado
• Projeto de exemplos em ASP.NET MVC: abrir PAdES, abrir CAdES, abrir XML
• Referência rápida do Rest PKI

Demonstrações e exemplos

• Demonstração: Validate a signed file
• Validate a signed PDF using Rest PKI: .NET · Java · Node.js · PHP · Python · Ruby
• Validate a CMS/CAdES signature using Rest PKI: .NET · Node.js · PHP
• Validate a signed XML using Rest PKI: .NET · Java · PHP