Recently we added a new Marketplace plugin called Digital Signature for Document Management and Nuxeo CAP. This brings a new interesting feature to our Open Source Document Management System.
Its purpose is to allow Nuxeo users to digitally sign PDF documents so that the document author, or signer, can later be verified. Is the installation simple? When using the Nuxeo Marketplace system it is very simple - like with other Marketplace plugins - and you can test this plugin immediately after it is installed. The only hitch is that the default configuration contains a sample certificate. What if you wanted to set it up with a real certificate - the one associated with your company or organization? Well, you will have to install that certificate in Nuxeo before using it for document signing. In this blog entry I’ll try to help you set up your real certificate inside the local Certificate Authority (CA).
“Why do we need a Certificate Authority in the first place?”, you might ask. We will address this question later, but a short answer would be - the CA will be used for issuing user certificates, and to establish a level of trust reaching beyond a single user. During the setup process I’ll explain the sequence of events before a document is signed, as well as introduce some terminology and principles related to digital signing.
If you did not install this plugin yet, install it directly in your registered instance using Nuxeo Marketplace.
Principles
Let me introduce some principles used for digital signing in Nuxeo DM:
• documents are signed to protect them from modification, especially at critical stages in their life-cycle
- document- and user-certification in Nuxeo DM follow principles of asymmetric cryptography, PKI & the X.509 standards
- to sign a document, a user needs a personal certificate
- each user can create her own certificate
- certificates are certified by Certificate Authorities (CAs)
Now, for the purpose of this blog entry let’s concentrate on two types of Certificate Authorities:
The Local CA and the Root CA
Root Certificate Authority:
The highest level certificates are created by root CAs 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 CA:
Your Local 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. The local CA certificate has to be created in your system.
The default Local CA that comes with our plugin is 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:
1) The document signature includes => the signer’s certificate (user certificate)
2) user certificate was signed with => your local CA certificate
3) your local CA certificate was signed by => a higher level CA certificate
4) the higher level CA certificate was signed by => a still higher CA certificate
… and so on… …and then, finally:
5) a 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 - via the sequence of intermediary CAs - verify it for you.
The 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
… as applied to you local CA certificate:
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. This has to be done only once per PDF viewing program and an example of certificate installation in a PDF viewer has been presented in our documentation.
Why does one need a local CA?
The user certificate generation step requires a Certificate Authority certificate (CA) to be set up inside the Nuxeo DM system as all user certificates have to be signed by a CA with a recognizable identity - a company rather than a single user. The term local CA can be understood here as “company Certificate Authority” or “system-wide Certificate Authority”. Note that there is only one CA certificate per system but each user can have his own certificate.
Set up your local CA certificate
For this exercise you will need the following software:
- keytool
- openssl
Configuration overview:
Here is the overview of the steps that need to be followed:
1) create company keys & certificate
2) create a certificate signing request (CSR)
3) sign the CSR (or have it signed by a trusted CA)
4) save your keys and the certificate in the jks keystore
Detailed steps:
- create a keypair
keytool -genkey -keyalg RSA -alias alternatekey -keypass bbbbbb -validity 360 -keysize 1024 -dname "cn=alternateCompanyCA, c=US" -keystore alternate.jks
- create a certificate signing request (CSR)
keytool -keystore alternate.jks -storepass aaaaaa -alias alternatekey -keypass bbbbbb -certreq -file alternate.csr
- submit the CSR to a well-known 3rd party Certificate Authority of your choice to sign it
You can find examples of 3rd party CAs here and here.
An alternative method would be to set up a local signing CA and use it for signing certificates (keeping in mind that this approach, though it could work for small-scale deployments, is not recommended for production purposes):
Generate the rootCA key pair:
openssl genrsa -des 1024 -out ROOTCA.key
Generate a self-signed rootCA certificate:
openssl req -new -key ROOTCA.key -x509 -days 3650 -out ROOTCA.crt
openssl x509 -req -in alternate.csr -CA ROOTCA.crt -CAkey ROOTCA.key -CAcreateserial -CAserial alternate.seq -out alternate.crt
# Import a signed primary certificate to an existing Java keystore
keytool -import -trustcacerts -alias alternatecert -file alternate.crt -keystore alternate.jks
Now you will need to replace the sample certificate with your own that you just created. You can use the configuration information from the Digital Signature plugin documentation which explains how to override the sample certificate with your company certificate.
This concludes this exercise… (and this entry). Please provide your comments.