Key Store (Digital Signature)

The Digital Signature feature adds PDF signing capabilities to the LogicalDOC Platform. It also also provides generation of user certificates, which are required for document signing.

LogicalDOC allows users to:

  • download the PDF for previewing,
  • download the root certificate to install inside your PDF viewer for verifying any future certificates,
  • navigate to certificate generation,
  • sign the PDF,
  • view existing certificates without opening the signed PDF.

Concepts

Principles

  • Documents are signed to protect them from modification, especially at critical stages in their lifecycle.
  • Document- and user-certification in the LogicalDOC follow principles of asymmetric cryptography, PKI & the X.509 standards.
  • To sign a document, a user needs a personal certificate.
  • Each user can create his own certificate.
  • Certificates are issued by Certificate Authorities (CAs).

What Is a Digital Signature?

Digital signatures uniquely identify the document signer. They provide a similar functionality to handwritten signatures on paper, and are a convenient alternative to signing and scanning documents when a digital version of a document is required. Digital signatures are meant to assure authenticity and integrity of documents, that is to verify that the document originator - or signer - is who they claim to be, and to ascertain that a document has not been tampered with between the moment of signing and the subsequent viewing.

What Is a Digital Certificate?

Before you sign a document you need a digital certificate. Certificates are attached to documents to verify the identity of the signer, that is to check that the person signing the message is who they claim to be. Certificates are issued by Certificate Authorities (CA, also known as Issuer). To verify that a certificate has not been tampered with, it has to be validated against the CA's public key. If this verification is passed it means that the CA certifies the authenticity of the signer. Digital certificates are formatted using PKI standards, the most common of them is X.509, which is also used in LogicalDOC.

Local and Root Certificate Authorities

Root Certificate Authority

The highest level certificates are created by root Certificate Authorities (CA) which are supposed to be trusted publicly. No higher authority can certify the root certificates: those are the top-level certificates. You can see examples of those in your browser, under the certificate authorities / CA section.

Here are some of the more popular ones:

  • Equifax Secure CA,
  • VeriSign Class 3 Public Primary Certification Authority,
  • Visa eCommerce Root,
  • Deutsche Telekom Root CA 2.

Local Certificate Authority

Your Local Certificate Authority (CA) will be used to sign user certificates. The local CA certificate can either be signed by a higher-level certificate authority, or be self-signed. A local CA certificate can be created inside your LogicalDOC instance.

Warning

Even if LogicalDOC can create a local CA for you, it is intended to be just an example certificate to be used for initial setup testing, and it should not be used for signing production documents.

 

Certification Chains

Now let's consider the following relationships:

  • The document signature includes => the signer's certificate (user certificate).
  • The user certificate was signed with => your local CA certificate.
  • Your local CA certificate was signed by => a higher level CA certificate.
  • The higher level CA certificate was signed by => a still higher CA certificate (… and so on… …and then, finally).
  • A very high level CA certificate was signed by => the root CA certificate.
  • The root CA certificate closes the chain that leads down to the user's certificate.

Now, instead of verifying all the intermediary certificates, it is enough for your PDF viewer to have the root Certificate Authority verify it for you, via the sequence of intermediary CAs.

Root certificates are usually already present in popular PDF viewers and browsers, and if not, they can be updated automatically provided your software has been set up properly.

CA-Signing vs Self-Signing

If your local CA certificate was signed by a certificate authority, the users usually don't have to install your company's certificate in their browsers to verify the signed documents.

On the other hand, if your local CA was self-signed, the CA certificate has to be manually installed in the PDF viewer prior to verifying signatures.

Configure the Key Store

LogicalDOC handles a Java Key Store for each tenant and uses it to maintain all the certificates.

Setting up the Local Root Certificate

Enter the section Administration > Settings > Key Store

Here put:

  • the alias for the root certificate(let's say root)
  • a password to protect the whole key store
  • informations about your organization

Check is the path of the external commands Keytool and OpenSSL are correct and press the button Generate a new Key Store

Setting up a CA certificate from a 3rd party authority

For this task you will need the following software:

  • keytool: the keytool comes with your JDK (Java Development Kit) installation.
  • openssl: Open SSL

1. Create a keypair (with alias root in this example).

keytool -genkey -keyalg RSA -alias root -keypass password -validity 365 -keysize 1024 -dname "cn=PDF-CA, ou=Headquarters, o=Example Organization, c=US" -keystore pdfca-keystore.jks

This creates a keypair (private and public key), and self-signs it automatically.

2. Create a certificate signing request (CSR).

keytool -keystore pdfca-keystore.jks -storepass aaaaaa -alias alternatekey -keypass password -certreq -file pdfca.csr

3. Submit the CSR to a well-known 3rd party Certificate Authority of your choice to sign it.

4. When you receive the signed certificate pdfca.crt, import it into your keystore using a new new alias (root in this example).

keytool -import -trustcacerts -alias root -file pdfca.crt -keystore pdfca-keystore.jks

Warning

Please follow the guide provided by your CA to know how exactly install their certificates into a Java key store

5. Now you can import the key store by clicking on Import, please put in Local CA alias the same alias used in the key store so LogicalDOC can found your certificate

Customization

Optionally you can choose to have the signature visible like a stamp in the document.

If the Visual option is selected, the name of the user that signed the file will be displayed in the first page of the document and these are the settings you can define for the signature:

  • Opacity: 100 means totally opaque, 0 means totally transparent
  • Font size: font size
  • Color: text color
  • Expr. X: expression that defines the horizontal coordinate, you can use variables that will be expanded dynamically
  • Expr. Y: expression that defines the vertical coordinate, you can use variables that will be expanded dynamically
  • Width: dimension of the signature

Variables for Expr. X, Expr. Y and Width

  • PAGE_WIDTH
  • PAGE_HEIGHT
  • PAGE_CENTER
  • PAGE_MIDDLE

To reference a variable, just put the dollar sign followed by the variable's name, so to center the signature you could type:

Expr. X: $PAGE_CENTER
Expr. Y: $PAGE_TOP + 5