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 Server-Backed mode, see our guide for validating digital signatures using Document Engine.

The digital signature validation process consists of two steps.

• In the first step, it checks if the signature certificate embedded during signing can be trusted. To do this, the trusted certificate chain up to the root authority that issued it is necessary. Both PSPDFKit for Web Served-Backed and Standalone allow you to specify the certificates to use for validation.

• In the second step, it verifies the signature. This process essentially applies the public key (from the certificate embedded in the PDF file) to the digital signature and compares the result with the message digest built from the PDF file, excluding the signature itself. If the result is the same, the signature is valid.

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 component 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.

Every digital signature also contains information about PAdES signature levels, which can be found on the PAdESSignatureLevel field. The possible values are PSPDFKit.PAdESLevel.b_b, PSPDFKit.PAdESLevel.b_t, and PSPDFKit.PAdESLevel.b_lt. The fields validFrom and validUntil indicate the validity period of the signature, while timestampInfo field contains information about the timestamp token issuer.

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.