Signature inspection - Rest PKI Core

The signature inspection API opens a signed file and returns its signers: who signed, when, with which certificate and signature policy. Optionally, it also validates each signature. One route serves the three formats that Rest PKI Core signs:

File	Signatures
PDF	PAdES
CMS (.p7s, .p7m)	CAdES, attached or detached
XML	XmlDSig and XAdES

tip

From this point on we'll describe calls to Rest PKI Core. Make sure you've read the Get Started article to be able to keep up. The application's API key needs a role that allows inspecting signatures, such as Worker (see Choosing roles).

Inspecting a file

Send the signed file in the file field, as a file reference:

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

Rest PKI Core tells the format by the file's MIME type: application/pdf, application/xml or text/xml, or a type containing pkcs7, such as application/pkcs7-signature. When the request has no mimeType, Rest PKI Core takes it from the file name's extension, or from the Content-Type of a file referenced by url. Any other type fails with UnrecognizedSignedFileMimeType, and a file whose type can't be found fails with MimeTypeRequired.

The request has these fields:

Field	Description
file	The signed file. Required
validate	Whether to validate the signatures. If false, the default, the signers are only listed
securityContextId	The security context that decides which certificates are trusted, when validating. If omitted, Rest PKI Core uses the subscription's default security context or, without one, the instance's. An ID that doesn't exist fails with SecurityContextNotFound, even without validation
ignoreRevocationStatusUnknown	When validating, accept certificates whose revocation status can't be determined. Default false
trustUncertifiedSigningTime	When validating, take the signing time declared by the signer as the reference date, even when no timestamp certifies it. Default false
dataFile, dataHashes	The signed data of a detached CMS signature: see Detached CMS signatures
extractEncapsulatedContent	Return the content encapsulated in a CMS file. Default false; ignored for PDF and XML

On Node.js, the restpki-core-client library calls this route with inspectSignature(), and on Python, restpki-ng-python-client with SignatureInspectionApi.api_signature_inspection_put(). The .NET, Java and PHP libraries have no method for it: call the route directly, as described in Calling the API directly.

Validation

With validate = true, Rest PKI Core validates each signature against the security context, with a basic policy for the format: PAdES basic for PDF, CAdES-BES for CMS and XmlDSig basic for XML. The request takes no signature policy. Validation can take a few seconds or longer.

Only the first 10 signers of a file are validated. On your own instance, the limit is the General:SignatureInspectionMaxValidations setting.

An inspection with validate = true is counted as a Signature validation transaction, and one without as a Signature inspection.

Files signed on this instance

When the file was signed on the same instance, for instance in a signature session, Rest PKI Core recognizes it and returns the signers as it stored them when the document was signed, along with the document in document. In that case it doesn't validate the signatures again, and securityContextId is not used.

Reading the response

An abridged response, for a PDF with one signer:

{
	"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
}

Field	Description
success	false only when validating a detached CMS signature without its data (see below)
signers	One entry per signature. Empty if the file is not signed
document	The document, when the file was signed on this instance; otherwise null
hasEncapsulatedContent, encapsulatedContentType, encapsulatedContent	For a CMS file, whether it encapsulates content and of which type; with extractEncapsulatedContent = true, also the content, as a file reference

Each signer has its certificate, the signature's signingTime, signaturePolicy, timestamps and archiveTimestamps, and, for PDFs, the signatureFieldName and whether the entry is a document timestamp (isDocumentTimestamp). validationResults has the checks that passed, the errors and the warnings, and is null when the signature was not validated. A signature is valid when its validationResults has no errors.

Detached CMS signatures

A detached CMS signature (.p7s) doesn't contain the file it signs. To validate it, send the signed data as well, in one of two ways:

• dataFile: the signed file, as a file reference
• dataHashes: its hashes, each with algorithm and value (in Base64) or hexValue. Send at least the SHA-256 hash. This is the better choice for large files, since the file doesn't need to be sent

If you validate without sending either, the response has success = false, failure = DataFileRequired and, in missingDataHash, the algorithm of the hash needed. This lets a page ask the user for the signed file only when it is needed. Without validation, the signers are listed without the data. dataFile and dataHashes are accepted only for CMS: with a PDF or an XML file, the call fails with DataFileNotSupported.

Moving from Rest PKI

On Rest PKI, signatures are opened with one route per format, through the explorers of the client library (PadesSignatureExplorer, CadesSignatureExplorer and XmlSignatureExplorer). Rest PKI Core still serves those routes (see Moving from Rest PKI). Signature inspection differs from them:

	Rest PKI Open routes	Signature inspection
Route	One per format: POST Api/PadesSignatures/Open, Api/CadesSignatures/Open, Api/XmlSignatures/Open	One for all formats: PUT api/signature-inspection
Signature policy	defaultSignaturePolicyId and acceptableExplicitPolicies	None: a basic policy for each format
No security context given	The signature policy decides what is trusted	The subscription's or instance's default security context
Signers validated	All on Rest PKI; the first 10 on Rest PKI Core	The first 10
Detached CMS without data	Fails with MissingDataHash	success = false, failure = DataFileRequired
Response	A model per format	signers, the same for every format, and document

To validate against a specific signature policy, keep the Open routes.

See also

• Security contexts
• Referencing files
• PDF stamps