Digital Signature

webPDF provides the Signature web service for the digital signing of PDF documents.

HTTP REST-API	OpenAPI
POST /signature/{documentId}	🔗

A digital signature is used to define the current status of a document. This marks the authenticity of a document and any further changes to the document can be recognised. It is also possible to insert several signatures into the document or to certify a document conclusively. After that, no further changes can be made to the document.

Digital signatures (also known as electronic signatures) use a key pair consisting of a private (secret) signature key and a public key (verification key). The terms usually used here are ‘private key’ and ‘public key’.

webPDF requires an X.509 certificate with private keys to create an electronic signature. The certificate and the private key must be provided to webPDF via a configured keystore file or directly via the parameters of the /signature web service call.

The certificate and the private key must be passed to webPDF either
a) via the global keystore file or
b) directly as PEM data during the web service call

webPDF creates signatures for PDF documents based on an asymmetric encryption scheme also known as "public key cryptography."

caution

As of this writing, webPDF can generate qualified electronic signatures only if the required certificates can be provided on the server on an appropriate medium (e.g., file) and it is possible to configure access to them on the server.

Use of the global keystore

webPDF uses a global keystore on the server to provide certificates (“public key” and “private” key) for the web service calls.

API {REST}: /signature

can be used to use this global keystore.

info

The global certificate store applies to all web service calls to the server.

In the parameters of the web service call, the corresponding certificate is then selected from the global keystore using the add operation with the keyName and keyPassword parameters.

{
  "signature": {
    "add": {
      "appendSignature": false,
      "certificationLevel": "none",
      "contact": "",
      "fieldName": "Signature1",
      "keyName": "name",
      "keyPassword": "password",
      "location": "",
      "reason": ""
    }
  }
}

The (alias) name of the certificate under which it is stored in the global keystore is specified by keyName. If the private key for the certificate is protected in the global keystore, a password can (optionally) be specified with keyPassword.

tip

If you want to use a different certificate for each web service call, you can use the PEM format and the keyPair parameter.

Use of individual certificates

webPDF uses a global keystore to provide certificates for all web service calls. However, if an individual certificate is to be used for a single web service call with

API {REST}: /signature

this is possible via the parameters of the web service call as a PEM format. In this case, the certificate, consisting of a public key and a private key, is transferred directly to the parameter under signer.

{
  "signature": {
    "add": {
      "appendSignature": true,
      "certificationLevel": "none",
      "contact": "",
      "fieldName": "Signature1",
      "location": "",
      "reason": "",
      "signer": {
        "keyPair": {
          "certificate": {
            "source": "value",
            "uri": "",
            "value": "-----BEGIN CERTIFICATE-----\r\nMIIF+TCCBOGgAwIBA ... idstK36dRILKz7OA54=\r\n-----END CERTIFICATE-----\r\n"
          },
          "privateKey": {
            "password": "password",
            "source": "value",
            "uri": "",
            "value": "-----BEGIN RSA PRIVATE KEY-----\r\nMIIJKgIBAAKCA ... gDxWRoBg==\r\n-----END RSA PRIVATE KEY-----"
          }
        }
      }
    }
  }
}

note

If the private key is encrypted, then you must provide the corresponding password under password.