Inspeção de assinaturas - Rest PKI Core

A API de inspeção de assinaturas abre um arquivo assinado e retorna os signatários: quem assinou, quando, com qual certificado e com qual política de assinatura. Opcionalmente, ela também valida cada assinatura. Uma única rota atende os três formatos que o Rest PKI Core assina:

Arquivo	Assinaturas
PDF	PAdES
CMS (.p7s, .p7m)	CAdES, anexadas ou destacadas
XML	XmlDSig e XAdES

dica

A partir daqui, descrevemos chamadas ao Rest PKI Core. Leia antes o artigo Primeiros passos. A chave de API da aplicação precisa de um papel que permita inspecionar assinaturas, como Operador (veja Escolhendo os papéis).

Inspecionando um arquivo

Envie o arquivo assinado no campo file, como uma referência de arquivo:

PUT {endpoint}/api/signature-inspection
{
	"file": {
		"content": "JVBERi0xLjcK...",
		"name": "contrato.pdf",
		"mimeType": "application/pdf"
	},
	"validate": true,
	"securityContextId": "201856ce-273c-4058-a872-8937bd547d36"
}

O Rest PKI Core identifica o formato pelo tipo MIME do arquivo: application/pdf, application/xml ou text/xml, ou um tipo que contenha pkcs7, como application/pkcs7-signature. Quando a requisição não tem mimeType, o Rest PKI Core o deduz da extensão do nome do arquivo, ou do Content-Type de um arquivo referenciado por url. Qualquer outro tipo falha com UnrecognizedSignedFileMimeType, e um arquivo cujo tipo não pode ser determinado falha com MimeTypeRequired.

A requisição tem estes campos:

Campo	Descrição
file	O arquivo assinado. Obrigatório
validate	Se as assinaturas devem ser validadas. Com false, o padrão, os signatários são apenas listados
securityContextId	O contexto de segurança que decide em quais certificados confiar, ao validar. Se omitido, o Rest PKI Core usa o contexto de segurança padrão da organização ou, sem ele, o da instância. Um ID que não existe falha com SecurityContextNotFound, mesmo sem validação
ignoreRevocationStatusUnknown	Ao validar, aceitar certificados cujo estado de revogação não pode ser determinado. Padrão false
trustUncertifiedSigningTime	Ao validar, tomar a data de assinatura declarada pelo signatário como data de referência, mesmo quando nenhum carimbo de tempo a certifica. Padrão false
dataFile, dataHashes	Os dados assinados de uma assinatura CMS destacada: veja Assinaturas CMS destacadas
extractEncapsulatedContent	Retornar o conteúdo encapsulado num arquivo CMS. Padrão false; ignorado para PDF e XML

Em Node.js, a biblioteca restpki-core-client chama esta rota com inspectSignature() e, em Python, a restpki-ng-python-client com SignatureInspectionApi.api_signature_inspection_put(). As bibliotecas de .NET, Java e PHP não têm método para ela: chame a rota diretamente, como descrito em Chamando a API diretamente.

Validação

Com validate = true, o Rest PKI Core valida cada assinatura com o contexto de segurança, usando uma política básica para o formato: PAdES básica para PDF, CAdES-BES para CMS e XmlDSig básica para XML. A requisição não recebe política de assinatura. A validação pode levar alguns segundos ou mais.

Apenas os 10 primeiros signatários de um arquivo são validados. Na sua própria instância, o limite é a configuração General:SignatureInspectionMaxValidations.

Uma inspeção com validate = true é contada como uma transação de Validação de assinatura, e uma sem validação como Inspeção de assinatura.

Arquivos assinados nesta instância

Quando o arquivo foi assinado na mesma instância, por exemplo numa sessão de assinatura, o Rest PKI Core o reconhece e retorna os signatários como os guardou quando o documento foi assinado, junto com o documento em document. Nesse caso, ele não valida as assinaturas de novo, e o securityContextId não é usado.

Lendo a resposta

Uma resposta resumida, para um PDF com um signatário:

{
	"success": true,
	"signers": [
		{
			"certificate": {
				"subjectName": { "commonName": "JOHN DOE:12345678901" },
				"issuerDisplayName": "AC EXAMPLE"
			},
			"signingTime": "2026-10-12T14:30:00-03:00",
			"signatureFieldName": "Signature1",
			"isDocumentTimestamp": false,
			"validationResults": {
				"passedChecks": [],
				"errors": [],
				"warnings": []
			}
		}
	],
	"document": null
}

Campo	Descrição
success	false apenas ao validar uma assinatura CMS destacada sem os dados dela (veja abaixo)
signers	Uma entrada por assinatura. Vazio se o arquivo não estiver assinado
document	O documento, quando o arquivo foi assinado nesta instância; senão, null
hasEncapsulatedContent, encapsulatedContentType, encapsulatedContent	Para um arquivo CMS, se ele encapsula conteúdo e de que tipo; com extractEncapsulatedContent = true, também o conteúdo, como referência de arquivo

Cada signatário traz o certificate, a signingTime da assinatura, signaturePolicy, timestamps e archiveTimestamps e, em PDFs, o signatureFieldName e se a entrada é um carimbo de tempo de documento (isDocumentTimestamp). O validationResults traz as verificações que passaram, os erros e os avisos, e é null quando a assinatura não foi validada. Uma assinatura é válida quando o validationResults dela não tem errors.

Assinaturas CMS destacadas

Uma assinatura CMS destacada (.p7s) não contém o arquivo que assina. Para validá-la, envie também os dados assinados, de uma de duas formas:

• dataFile: o arquivo assinado, como referência de arquivo
• dataHashes: os hashes dele, cada um com algorithm e value (em Base64) ou hexValue. Envie pelo menos o hash SHA-256. É a melhor escolha para arquivos grandes, já que o arquivo não precisa ser enviado

Se você validar sem enviar nenhum dos dois, a resposta traz success = false, failure = DataFileRequired e, em missingDataHash, o algoritmo do hash necessário. Isso permite que uma página peça o arquivo assinado ao usuário apenas quando necessário. Sem validação, os signatários são listados sem os dados. dataFile e dataHashes só são aceitos para CMS: com um PDF ou um XML, a chamada falha com DataFileNotSupported.

Migrando do Rest PKI

No Rest PKI, as assinaturas são abertas com uma rota por formato, por meio dos explorers da biblioteca cliente (PadesSignatureExplorer, CadesSignatureExplorer e XmlSignatureExplorer). O Rest PKI Core continua atendendo essas rotas (veja Migração do Rest PKI). A inspeção de assinaturas é diferente delas:

	Rotas Open do Rest PKI	Inspeção de assinaturas
Rota	Uma por formato: POST Api/PadesSignatures/Open, Api/CadesSignatures/Open, Api/XmlSignatures/Open	Uma para todos os formatos: PUT api/signature-inspection
Política de assinatura	defaultSignaturePolicyId e acceptableExplicitPolicies	Nenhuma: uma política básica para cada formato
Sem contexto de segurança	A política de assinatura decide em quem confiar	O contexto de segurança padrão da organização ou da instância
Signatários validados	Todos no Rest PKI; os 10 primeiros no Rest PKI Core	Os 10 primeiros
CMS destacada sem os dados	Falha com MissingDataHash	success = false, failure = DataFileRequired
Resposta	Um modelo por formato	signers, igual para todos os formatos, e document

Para validar com uma política de assinatura específica, continue usando as rotas Open.

Veja também

• Contextos de segurança
• Referenciando arquivos
• Carimbos em PDF