We are living in 2022. And it is now possible to digitally sign a PDF document using libre software. This is a love letter to libre software projects, and also a manual.
For a long time, one of the challenges in using libre software in ‘enterprise’ environments or working with Government documents is that one will eventually be forced to use a proprietary software that isn’t even available for a libre platform like GNU/Linux. A notorious use-case is digitally signing PDF documents.
Recently, Poppler (the free software library for rendering PDF; used by Evince and Okular) and Okular in particular has gained a lot of improvements in displaying digital signature and actually signing a PDF document digitally (see this, this, this, this, this and this). When the main developer Albert asked for feedback on what important functionality would the community like to see incorporated as part this effort; I had asked if it would be possible to use hardware tokens for digital signature. Turns out, poppler uses nss (Network Security Services, a Mozilla project) for managing the certificates, and if the token is enrolled in NSS database, Okular should be able to just use it.
This blog post written a couple of years ago about using hardware token in GNU/Linux is still actively referred by many users. Trying to make the hardware token work with Okular gave me some more insights. With all the other prerequisites (token driver installation etc.) in place, follow these steps to get everything working nicely.
Howto
- There are 2 options to manage NSSDB: (i) manually by setting up
$HOME/.pki/nssdb, or (ii) use the one automatically created by Firefox if you already use it. Assuming the latter, the nssdb would be located in the default profile directory$HOME/.mozilla/firefox/<random.dirname>/(check for existence of the filepkcs11.txtin that directory to be sure). - Open Okular and go to
Settings→Configure backend→PDFand choose/set the correct certificate database path, if not already set by default.
- Start the smart card service (usually auto-started, you won’t have to do this): either
pcsc_wd.service(for WatchData keys) orpcscd.service. - Plug in the hardware token.
- Open a PDF in Okular. Add digitial signature using menu
Tools→Digitally Sign - This should prompt for the hardware token password.
- Click & drag a square area where you need to place the signature and choose the certificate. Note that, since Poppler 22.03, it is also possible to insert signature in a designated field.
- Signature will be placed on a new PDF file (with suffix
-signed) and it will open automatically.
- You can also see the details of the hardware token in PDF backend settings.
Thanks to the free software projects & developers who made this possible.
Soliloquies 
5 responses to “Digitally signing PDF documents in Linux: with hardware token & Okular”
[…] Digitally signing PDF documents in Linux: with hardware token & Okular – Soliloquies […]
Very nice article.. unfortunately I still couldn’t use this on my Ubuntu 22.04 setup =(
First it must be said that original firefox (from snap) must be replaced in order to be able to load pkcs11 library on security devices menu. But even then, and with poppler properly installed, pkcs11 certificate is still not listed on Okular Backend, no matter wich certificate database I setup (standard or $USER/.pki/nssdb or any other).
Thus, everytime I try to use sign tool it says no certificate available =(
I’m using Firefox 108.0, Poppler 22.12.0, Okular 22.08.2 and unfortunately it doesn’t work, would you have any advice to overcome this situation?
You could try a few things:
1. Really make sure the correct nss db path is set. Note that $USER/.pki/nssdb is something manually configured (refer its documentation). Simpler approach is to use the correct Firefox profile directory ()
2. Is Firefox able to load the digital signature? If not, it may not work in Okular either. If Firefox can load it, you may need to close Firefox first before opening Okular.
3. Make sure the certificate is not expired 🙂
I keep trying from time to time to sign a document without having to use other OS where it is a trivial procedure >,< On my last attempt to do so, I've noticed that poppler, by using the pdfsig -list-nicks only shows the certificate related to my USB Token PKCS11 when I set the token password – by using -nss-pwd directive even though my nss database does not have a password set.
I don't know if it's a bug but maybe that is what is preventing Okular – which uses poppler infrastracture – from listing my usb token certificate. I tried to set my nss pkcs11.txt file to allow public listing of the certificate without success on having the certificate listed by pdfsig without informing password (which I believe could be the source of problem on my setup).
Have you ever seem any problem like this? Would it be possible to improve nss database in order to have all certificates listed pubicly including pkcs11 types?
@noliveira
I am made aware of `pdfsig` for the first time now; and found that the digital token key need to be passed as `-nss-pwd` to recognize the key. But once that is done, I was able to sign pdf documents, though a misleading error “NSS_Shutdown failed” occurs (that is already fixed, see https://gitlab.freedesktop.org/poppler/poppler/-/issues/1326).
You may want to open a discussion with poppler project about the nssdb handling and/or usability improvements.