Secure digital QSL cards, part 2: shell script

Following on from Creating secure digital QSL cards with your LoTW certificate, here’s a Bash script to generate encrypted signed PDF QSLs. You will need to edit the certificate file name, the QSL blank file name, your call sign, your LoTW password and the PDF encryption password. After doing so, please keep the script safe, as whoever has your LoTW password can pretend to be you.

The only checks that this script doesn’t do (and probably should) are if you have pdftk and PortableSigner executables in your path. PortableSigner is rather weird the way it runs; you need to specify full paths for all files, or it dies.

The script is called like this:

mkdqsl.sh callsign date utc mhz mode report

for example:

mkdqsl.sh VE3KPK 2011-10-02 2341 7.03581 CW 499

Code below the fold.

Continue reading “Secure digital QSL cards, part 2: shell script”

Creating secure digital QSL cards with your LoTW certificate

Hams have sent out QSL cards since the hobby began. It may be less popular than it used to be, because mail seems slow now (especially when QSL bureaux are used), and there are online alternatives like eQSL, QRZ.com, and the ARRL‘s Logbook of the World (LoTW).

LoTW has been criticized for being too complex. It uses an X.509 public key signature to verify your submitted log entries, and a QSL is confirmed when the other party sends in a matching entry. In a way, it’s rather elegant, as the LoTW server does the work of matching the entries, so QSLs “magically” appear in your log. You don’t get a fancy QSL card in the mail or on your screen, and I think a lot of users miss that.

X.509 might be a bit unweildy, but props to ARRL for setting up a industry standard, robust (-ish; X.509 has its flaws), general purpose signing infrastructure. Since other file formats — notably PDF — support X.509 signing, you can use your LoTW certificate to make other data tamper-evident.

Here I document a method of creating a digital QSL card that can be e-mailed, and subsequently verified by the recipient as being legitimate. Any alterations to the file will break the signature, and the file will just appear as a regular PDF (or not display properly). The process can be used to sign any other Acrobat file. There are probably more streamlined ways to do this, but I only came up with it last night as the beginning of a scriptable solution.

You will need:

  • Your ARRL LoTW electronic certificate file. This is called callsign.p12; mine is VA3PID.P12
  • A means of making a QSL card as a PDF fill-in form. I used Scribus; it’s a free but powerful DTP system.
  • Pdftk, “the” PDF toolkit, to apply the QSL details to the PDF form. If you’re on Windows, you might want the Pdftk GUI.
  • PortableSigner, a java application for signing Acrobat files using an X.509 certificate.

(Quite a bit of what follows was learnt from the two pages Your first PDF form with Scribus – Scribus Wiki and filling in forms with pdftk, so thanks to the authors of those for the guidance.)

First, make your QSL card. Since you’re not going to print this, it can be any size you want, but postcard size is standard. At the very least, create spaces for the recipient callsign, the date, the time, frequency, mode used, and signal report.

Under these headings, I’ve made six PDF text form fields. Scribus creates form fields like text frames/boxes. I used plain text fields (which are selected by this icon: ), centred text, and with the name of the field set from the PDF Options → Field Properties context menu. Each field needs a different name. I used callsign, date, utc, mhz, mode, and report.

Save your QSL card as PDF. It might be an idea to check it to see if the form fields are really there and editable:

Now it starts to get really nerdy. Adobe specified the Forms Data Format (FDF) to allow PDF form data to be slung around. FDF looks a bit like PostScript or raw PDF:

%FDF-1.2

1 0 obj
<<
/FDF << /Fields 2 0 R>>
>>
endobj
2 0 obj
[<< /T (callsign) /V (VE3KPK) >>
<< /T (date) /V (2011-10-02) >>
<< /T (mhz) /V (7.03581) >>
<< /T (mode) /V (CW) >>
<< /T (report) /V (499) >>
<< /T (utc) /V (2341) >>
]
endobj
trailer
<< /Root 1 0 R >>
%%EOF

If you think of the T & V values above as Tag and Value, you can see that the file defines callsign=VE3KPK, date=2011-10-02, mode=CW, and so on. This step can be easily scripted. If you’re not sure what the fields are called, pdftk has a “dump_data_fields” option that spits out the field names as plain text.

pdftk is also used to put the data from the FDF file into the PDF template. It’s a slightly hairy command line:

pdftk QSL-blank.pdf fill_form VE3KPK.fdf output QSL-VE3KPK.pdf flatten

Here the source file is QSL-blank.pdf, the FDF data is VE3KPK.fdf, and the output is to QSL-VE3KPK.pdf. The flatten option turns the pdf form into regular, uneditable PDF. (These details are from a real QSO, by the way, and by utter coincidence I’m writing this in a hotel in Ken VE3KPK’s home town in Northern Ontario.)

Checking that this worked in Adobe Reader:

For many people this is probably enough (or perhaps, too much already!) but I really want to have a digital QSL card that will stand up to some scrutiny. This is where your LoTW certificate file comes in.

PortableSigner is a java application for signing PDF files. It seems quite happy signing the files made in this workflow. It can run from the command line, or as a windowed application:

You use your .p12 signature file and its password to sign the PDF. Once the file is signed, you can send it to your contact, and they can prove (and hopefully, any certification/contest agency will agree) that the contact was confirmed.

Viewing the signed document is deeply unimpressive:

It’s not such a big deal that Reader says that “the validity of the certification is unknown”. It’s just that Adobe doesn’t have the ARRL’s certificate loaded into everyone’s reader (what!? mock outrage!) and so it doesn’t match a certificate it knows about. You have to dig a bit deeper into the signature panel to check out who is responsible for this.

Well, that’s a start; at least it was signed by someone with my e-mail address. There’s more under Show Signature Properties:

There’s the ARRL signature in there. Buried deep in another properties tree is my callsign; can’t find it today, but I saw it in there last night. Either way, the digital QSL PDF is now signed and certified that it came from me, as an ARRL LoTW user.