Add Personality to Your Blog Posts with a Signature

As you may know already, I use Hugo to create this blog, with a custom theme I’m putting together by forking a nice reimplementation of the Antora default UI because I wanted to write my blog using the AsciiDoc markup language. Also, as I said before, I also have a working OpenPGP setup with GPG. I’ll skip describing it here. You can refer to this awesome guide about OpenPGP key management or comment in this post if you’d like to see a complete description of how I set up my OpenPGP keys.

There must certainly be a better way to do this with Hugo, but I found straightforward enough to just add an intermediary step invoking gpg --detach-sign between building the website and publishing it. Here’s how it looks like:

I opted for a detached signature because it’s easier to ensure integrity this way, even though it’s a little bit harder for readers to verify the signature (as you’ll see later, there are some extra measures to compensate for the extra complexity on the reader’s end). An attacker would have to take control of more than one file served from my hosting solution to be able to alter the signature and the page contents so they would match. The alternative of embedding the signature together with the page contents in a single file requires GPG to mark part of the file as the signed contents (not the file as a whole), thus an attacker could inject a malicious JavaScript outside of the HTML DOM area, browsers would load that happily and my signature mechanism wouldn’t be any helpful in detecting the integrity violation of the content being shared under my name. But, although I take confidentiality and integrity seriously, I’m mostly making this for the sake of fun ;) This is a content website, not an application.

Later on, in the same Makefile I have the "deploy" target, which depends on both build and sign ( deploy: build sign) so I don’t have to invoke any of these targets if I don’t want to. Since everything under the public\ directory is deployed to my hosting solution, the detached signatures can now be served to you, the reader.

If I later decide to change the key used to sign those posts, with that Makefile I’ll do one change and all pages will be re-signed with the new key.

Those readers familiar with OpenPGP and GPG, now armed with all that information, can figure out how to determine if the contents they are receiving are the same I intended to publish:

But not everybody will read this post first. How would you otherwise know that I went through the roofs to to assure you the integrity of the content being claimed as written by me by gpg-signing my posts?

I need to present you that information in the posts themselves in a nice way.

Presenting the signature must not alter the HTML page being served, otherwise the signature would be invalid from the get-go. Since the signatures are in separate files with a predictable name, we can easily leverage the HTML iframe tag to load their contents. To modify my theme accordingly I just needed a new partial being called out in the single.html layout (the one rendering the individual posts) handling this iframe:

To make it Hugo-idiomatic, let’s imagine that the client site would be configured with the following parameters related to OpenPGP:

That assumes all the pages will be signed with the same key, which is my case for now. If I decide to change the signing key this configuration and the Makefile are the only places I need to touch.

So the partial needs to enclose the HTML content in a {{ with .Site.Params.openPGP }}/ {{ end }} pair, such that if there is no configuration related to OpenPGP, nothing is added to the rendered page. The iframe itself would look like (assuming "." is the page context):

Notice that we are composing a code block inside a quote block in the Markdown syntax. It contains the commands to receive my key from the keyserver as configured via the site parameters. Finally the composed string is rendered with the Page.RenderString Hugo method. In this snippet signatureInfo and signatureDetails and translatable text resources declared inside the i18n\<lang>.yaml files. In English they are:

Good, but when writing a new post I won’t have a signature file right away, so the iframe would look horrible with a 404. I’d rather not display it at all. For that we need some JavaScript. <2> Let’s expand the second ellipsis:

With that in place, when the iframe finishes loading with 404 or if it fails to load at all, we just hide the wrapper div gracefully. Finally some CSS to make this thing look a little bit nicer:

We style the iframe child of the signature class to take the entire height and width of the parent, aiming to avoid scrolling. The media queries define some breakpoints to change the aspect ratio of the enclosing div, making the whole arrangement more responsive and mobile-friendly. If I was using CSS frameworks like Tailwind CSS, that kind of thing would be handled by the framework.

Once again, the entire post-signature.html partial for contemplation:

It was all great! With all of that in place, instead of doing this:

I can do this:

Depending on how your hosting solution is configured, it’s possible that the iframe would download the *.html.asc files instead of rendering them in place. To solve it we must ensure that those files will be served with the Content-Type=text/plain and Content-Disposition=inline.

That’s how I do with Firebase Hosting, via editing firebase.json:

If you also work with Firebase Hosting and need to do something similar, refer to the full hosting configuration docs.

Was all that effort worth it? If you consider the amount of users that would go care to run those commands and validate my post signature, I’d definitely say that’s not worth it. I wish people took OpenPGP more seriously and use it more often in digital communications. It’s a great way in theory to avoid fake news, automated spammy content and what not when you have well established web of trust. It’s usefulness is dimmed by the lack of adoption, though, which is unfortunate.

But, as I said in the beginning, it was more for the sake of the joke than the actual usefulness, and I learned a few tricks about HTML, CSS and even JavaScript when doing all of this, so it was definitely fun and worth it. Maybe this becomes a trend and everybody starts signing and checking signatures of blog posts? Who knows ;) Or maybe storage becomes a concern and I decide to remove all the signature files in the future. Who knows. What matters is the fun along the way.

I’m not a web guy and don’t intend to be, but it’s good to learn a few tricks every now and then.

I hope you enjoyed the ride! Cheers!