Digitally signing PDF documents in Linux: with hardware token & Okular

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

  1. 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 file pkcs11.txt in that directory to be sure).
  2. Open Okular and go to SettingsConfigure backendPDF and choose/set the correct certificate database path, if not already set by default.
Fig. 1: Okular PDF certificate database configuration.
  1. Start the smart card service (usually auto-started, you won’t have to do this): either pcsc_wd.service (for WatchData keys) or pcscd.service.
  2. Plug in the hardware token.
  3. Open a PDF in Okular. Add digitial signature using menu ToolsDigitally Sign
  4. This should prompt for the hardware token password.
Fig. 2: Digital token password prompt when adding digital sign in the PDF document.
  1. 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.
Fig. 3: Add digital signature by drawing a rectangle.
  1. Signature will be placed on a new PDF file (with suffix -signed) and it will open automatically.
Fig. 4: Digitally signed document.
  1. You can also see the details of the hardware token in PDF backend settings.
Fig. 5: Signature present in hardware token visible on the PDF backend settings.

Thanks to the free software projects & developers who made this possible.

Okular 20.08 — redesigned annotation tools

Last year I wrote about some enhancements made to Okular’s annotation tool and in one of those, Simone Gaiarin commented that he was working on redesigning the Annotation toolbar altogether. I was quite interested and was also thinking of ‘modernizing’ the tool — only, I had no idea how much work it would be.

The existing annotation tool works, but it had some quirks and had many advanced options which were documented pretty well in the Handbook but not obvious to an unscrupulous user. For instance, if the user would like to highlight some part of the text, she selects (single-clicks) the highlighter tool, applies it to a block of text. When another part of text is to be highlighted, you’d expect the highlighter tool to apply directly; but it didn’t ‘stick’ — tool was unselected after highlighting the first block of text. There is an easy way to make the annotation tool ‘stick’ — instead of single-click to select the tool, simply double-click, and it persists. Another instance is the ‘Strikeout’ annotation which is not displayed by default, but can be added to the tools list.

Simone, with lots of inputs, testing and reviews from David Hurka, Nate Graham and Albert Astals Cid et al., has pulled off a magnificent rewrite of Okular’s annotation toolbar. To get an idea of the amount of work went into this, see this phabricator task and this invent code review. The result of many months of hardwork is a truly modern, easy to explore-and-use annotation support. I am not aware of any other libre PDF reader with such good annotation features.

Annotation toolbar in Okular 20.08.

Starting from the left, default tools are: Highlight (brush icon), Underline (straight line) and Squiggle (wobbly line), Strike out, Insert text (Typewriter), Inline note, Popup note, Freehand drawing and Shapes (arrows, lines, rectangles etc.). The line thickness, colour, opacity and font of the tools can be customized easily from the drawer. Oh, and the selected annotation tool ‘sticks’ by default (see the ‘pin’ icon at the right end of toolbar).

When upgrading to okular-20.08 from a previous version, it will preserve the customized annotation tools created by the user and make those available under ‘Quick annotations’, and these can be quickly applied using Alt+n (Alt-1, Alt-2 etc.) short cuts. It did reset my custom shortcuts keys for navigation (I use Vim keys gg to go to the first page and G to go to the last page), which can be manually added back.

Custom tools (Quick annotations) can be applied with short cuts.

Here is the new toolbar in action.

WatchData PROXKey digital signature using emSigner in Fedora 30

TL;DR — go to the Howto section to make WatchData PROXKey work with emSigner in GNU/Linux system.

Introduction

Hardware tokens with digital signature are used for filing various financial documents in Govt of India portals. The major tokens supported by eMudhra are WatchData ProxKey, ePass 2003, Aladdin, Safenet, TrustKey etc. Many of these hardware tokens come (in CDROM image mode) with drivers and utilities to manage the signatures, unfortunately only in Windows platform.

Failed attempts

Sometime in 2017, I tried to make these tokens work for signing GST returns under GNU/Linux, using the de-facto pcsc tool. I got a WatchData PROXKey, which doesn’t work out-of-the-box with pcsc. Digging further brings up this report and it seems the driver is a spinoff of upstream (LGPL licensed), but no source code made available, so there is no hope of using these hardware tokens with upstream tools. The only option is depending on vendor provided drivers, unfortunately. There are some instructions by a retailer to get this working under Ubuntu.

Once you download and install that driver (ProxKey_Redhat.rpm), it does a few things — installs a separate pcsc daemon named pcscd_wd, installs the driver CCID bundles and certain supporting binaries/libraries. (The drawback of such custom driver implementations is that different drivers clash with each other (as each one provides a different pcscd_wd binary and their installation scripts silently overwrite existing files!). To avoid any clashes with this pcscd_wd daemon, disable the standard pcscd daemon by systemctl stop pcscd.service.

Plug in the USB hardware token and to the dismay observe that it spews the following error messages in journalctl:

Oct 06 09:16:51 athena pcscd_wd[2408]: ifdhandler.c:134:IFDHCreateChannelByName() failed
Oct 06 09:16:51 athena pcscd_wd[2408]: readerfactory.c:1043:RFInitializeReader() Open Port 0x200001 Failed (usb:163c/0417:libhal:/org/freedesktop/Hal/devices/usb_device_163c_0417_serialnotneeded_if1)
Oct 06 09:16:51 athena pcscd_wd[2408]: readerfactory.c:335:RFAddReader() WD CCID UTL init failed.

This prompted me to try different drivers, mostly from the eMudhra repository — including eMudhra Watchdata, Trust Key and even ePass (there were no *New* drivers at this time) — none of them seemed to work. Many references were towards Ubuntu, so I tried various Ubuntu versions from 14.04 to 18.10, they didn’t yield different result either. At this point, I have put the endeavour in the back burner.

A renewed interest

Around 2019 September, KITE announced that they will start supporting government officials using digital signatures under GNU/Linux, as most of Kerala government offices now run on libre software. KITE have made the necessary drivers, signing tools and manuals available.

I tried this in a (recommended) Ubuntu 18.04 system, but the pcscd_wd errors persisted and NICDSign tool couldn’t recognize the PROXKey digital token. Although, their installation methods gave me a better idea of how these drivers are supposed to work with the signing middleware.

Couple of days ago, with better understanding of how these drivers work, I thought that these should also work in Fedora 30 system (which is my main OS), I set out for another attempt.

How to

  1. Removed all the wdtokentool-proxkey, wdtokentool-trustkey, wdtokentool-eMudhra, ProxKey_Redhat and such drivers, if installed; to start from a clean slate.
  2. Download WatchData ProxKey (Linux) *New* driver from eMudhra.
  3. Unzip and install wdtokentool-ProxKey-1.1.1 RPM/DEB package. Note that this package installs the TRUSTKEY driver (/usr/lib/WatchData/TRUSTKEY/lib/libwdpkcs_TRUSTKEY.so), not ProxKey driver (/usr/lib/WatchData/ProxKey/lib/libwdpkcs_SignatureP11.so) and it seems the ProxKey token only works with TRUSTKEY driver! Update: the libwdpkcs_SignatureP11.so library works fine for ProxKey, it is the emSigner binary that doesn’t look for it.
  4. To make emSigner work, symlink to one of the libraries it checks for (ensure target directory doesn’t exist because you installed another driver): mkdir -p /usr/lib/WatchData/TRUSTKEY/lib/; ln -s /usr/lib/WatchData/ProxKey/lib/libwdpkcs_SignatureP11.so /usr/lib/WatchData/TRUSTKEY/lib/libwdpkcs_TRUSTKEY.so
  5. Start pcscd_wd.service by systemctl start pcscd_wd.service (only if not auto-started)
  6. Plug in your PROXKey token. (journalctl -f would still show the error message, but — lesson learned — this error can be safely ignored!)
  7. Download emsigner from GST website and unzip it into your ~/Documents or another directory (say ~/Documents/emSigner).
  8. Ensure port 1585 is open in firewall settings: firewall-cmd --add-port=1585/tcp --zone=FedoraWorkstation (adjust the firewall zone if necessary). Repeat the same command by adding --permanent to make this change effective across reboot).
  9. Go to ~/Documents/emSigner in shell and run ./startserver.sh (make sure to chmod 0755 startserver.sh, or double-click on this script from a file browser). Note that you’d need openjdk-1.8 or Oracle java due to windowslookandfeel component.
  10. Login to GST portal and try to file your return with DSC.
  11. f you get the error Failed to establish connection to the server. Kindly restart the Emsigner when trying to sign, open another tab in browser window and go to https://127.0.0.1:1585 and try signing again (don’t use localhost, as it would cause self-signed certificate mismatch).
  12. You should be prompted for the digital signature PIN and signing should succeed.

It is possible to use this digital token also in Firefox (via Preferences → Privacy & Security → Certificates → Security Devices → Load with Module filename as /usr/lib/WatchData/ProxKey/lib/libwdpkcs_SignatureP11.so) as long as the key is plugged in. Here again, you can skip the error message unable to load the module. Update: this error message is caused by a permission issue of pkcs11.txt file in firefox profiles directory, change that file’s owner to your user.