Validating a Digital Signature Using JavaScript
The following guide outlines how to validate digital signatures when deploying PSPDFKit for Web as a standalone client-side JavaScript library. To validate digital signatures in a server-backed deployment, see our guide for validating digital signatures using PSPDFKit Server.
The digital signature validation process consists of two steps.
In the first step, we check if the signature certificate embedded during signing can be trusted. To do this, we need to obtain the trusted certificate chain up to the root authority that issued it. Both the Server and Standalone setups of PSPDFKit for Web allow you to specify the certificates to use for validation.
In the second step, we verify the signature. This process essentially decrypts the signature with a public key from the certificate embedded in the PDF file on signing and compares it with the message digest built from the PDF file, excluding the signature itself.
Provide Trusted Root Certificates
PSPDFKit will need access to the trusted root certificates that will be used for digital signature validation.
Provided you have the feature enabled in your license, you only need to supply the root certificates that PSPDFKit for Web should use for validation and call the corresponding API method to obtain the validation status of digital signatures embedded in a document.
For this purpose, you can set
PSPDFKit.Configuration#trustedCAsCallback when loading. This callback should return a Promise object that resolves to the Array of certificates to be used for validation. If the certificate is DER encoded, you need to return it as an ArrayBuffer. If it’s PEM encoded, you need to return it as a string.
In order to retrieve the certificate list, PSPDFKit for Web calls the function assigned to PSPDFKit.Configuration#trustedCAsCallback when an
instance is loaded.
Example Using a Dynamic List of Certificates:
PSPDFKit.load[{
...configuration,
trustedCAsCallback: async [] => {
let res;
let arrayBuffer;
try {
res = await fetch[myCertificateStore];
// Use `res.text[]` instead for a PEM-encoded certificate.
arrayBuffer = await res.arrayBuffer[];
} catch [e] {
throw `Error ${e}`;
}
if [!res.ok] {
throw `HTTP Error ${res.statusCode}`;
}
return [arrayBuffer];
}];Obtain Validation Status
You can obtain the overall validation status of the current document and information about each one of the digital signatures found on it with the
PSPDFKit.Instance#getSignaturesInfo method. It returns a Promise that resolves with a PSPDFKit.SignaturesInfo object.
The status field returns a value indicating the result of the signatures’ validation of the document. Additionally, the documentModifiedSinceSignature property can be queried to determine if the document was
altered in any way after all signatures were applied. If true, it means there is a signature that doesn’t cover the entire document. See the API documentation for more information.
If you need granular information about each one of the digital signatures found on the document, the signatures property of PSPDFKit.SignaturesInfo returns an Array with
PSPDFKit.SignatureInfo objects. The array is sorted from least recent to most recent signature. The general status of each signature is present on the signatureValidationStatus field, wherein the field is PSPDFKit.SignatureValidationStatus.valid if no issues have been found on the signature, PSPDFKit.SignatureValidationStatus.warning if there are certain concerns with it, and PSPDFKit.SignatureValidationStatus.error if the signature is invalid.
For more details about the status of the certificate chain or the integrity of the
document, you can check out the certificateChainValidationStatus and documentIntegrityStatus fields. Additionally, there are flags that indicate whether the signing certificate is trusted, self-signed, or expired.
Validation UI
With the Digital Signatures license component, the validation status UI is available, but it’s not enabled by default. You can easily turn it on by specifying the desired option on the
PSPDFKit.ViewState.showSignatureValidationStatus property. The available options are:
PSPDFKit.ShowSignatureValidationStatusMode.NEVER[default] — Don’t show the digital signature validation UI at any time, even if there are digital signatures on the document.PSPDFKit.ShowSignatureValidationStatusMode.IF_SIGNED— Show the digital signature validation UI whenever the document is digitally signed.PSPDFKit.ShowSignatureValidationStatusMode.HAS_WARNINGS— Only show the digital signature validation UI if there are warnings for the document’s digital signatures.PSPDFKit.ShowSignatureValidationStatusMode.HAS_ERRORS— Only show the digital signature validation UI if there are invalid signatures in the document.
The signature validation UI consists of a colored bar shown under the main toolbar and, if they exist, under the annotation toolbars. The bar will have the background color corresponding to the current document’s validation status: red for “error,” yellow for “warning,” and green for “OK.” These colors are adapted for the default supported themes, light and dark. The status bar will show an informative text about the validation status of the document.
The diagram below shows the decision tree that leads to each possible validation status text and color. The bar will be shown or
hidden in each case depending upon the value of PSPDFKit.ViewState.showSignatureValidationStatus.
The validation status bar will pop up either when the document is loaded [or reloaded], or when PSPDFKit.ViewState.showSignatureValidationStatus is updated, depending on its value. The bar can be closed at any time by pressing the Close button
at the end of the bar. The validation status displayed is automatically updated whenever the document changes, e.g. if an annotation is added, the bar will reflect that modifications were made to the document since it was signed.