SSL Certificates

There can be good reasons to use "Let's Encrypt" certificates; you may already have SMTP and HTTP setup for Let's Encrypt, so why not also use that key and certificate material in a gemini server? Some may stop reading here. (You may want to configure Let's Encrypt to reuse the same private key so that gemini clients may issue fewer warnings about certificate changes, but that may have downsides.)

Certificates with "short expiry times annoy users because they get warnings (e.g. on Lagrange)", according to a user on the #gemini channel of the tilde IRC network. I'm not sure if this applies to Let's Encrypt certificates. Amfora may show a dialog when a certificate rotates, so there may be a goldilocks zone between a certificate that does not expire too quickly and one that lasts for too long: annoying users with too many pop-ups is as bad as never notifying them when there is some need to do so.

Perfect forward security may help mitigate the effects of a certificate that lasts for too long, though on the other hand some software may require that a certificate not last for too long. However, details on generating and using certificates may be more useful than me rambling on for too long.

This document covers LibreSSL on OpenBSD 7.2; anything different may need varying degrees of adaptation. Probably this documentation will get out of date as new innovations are made to the art of certificate, so be sure to check other fine manuals for details.

Self-Signed Certificate

A self-signed certificate can be generated with a single `openssl req` command. Adjust to fit your systems as necessary.

    #!/bin/sh
    openssl req -x509 -newkey rsa:4096 -sha256 -days 99999 -nodes \
    -keyout host.key -out host.cert -subj "/CN=thrig.me" -addext \
    "subjectAltName=DNS:thrig.me,IP:104.207.156.138,IP:2001:19f0:8001:143b:5400:4ff:fe1a:8ed6"

A productive use of a self-signed certificate is a pair of processes that only talk to one another, each verifying the other. Only the self-signed certificate is used for verification:

pingpong.gmi

Another use is of course to serve up gemini requests. In this case the server generally does not verify the client, and the clients use TOFU (or less, or also the usual verification process) to verify the server. The verification can become pretty complicated.

The `openssl req` command however does several things that we may want to handle separately. In particular, the above generates a new private key; another option is to reuse an existing private key. In that case different commands must be used to generate the private key and certificate, or certificates.

Private Key

    $ ( umask 0077; openssl genrsa -out host.key 4096 )
    ...

The private key should be readable by as little as possible, hence the umask change in a subshell. Subshells are pretty neat, except when they are not.

    $ umask ;( umask 000; umask ); umask
    022
    000
    022

Self-Signed Certificate From Private Key

With a private key, multiple certificates can be generated. This uses `openssl req` as prior except it specifies the key to use, generated prior.

    #!/bin/sh
    openssl req -x509 -new -sha256 -days 99 -nodes -key host.key \
    -out host.cert -subj "/CN=example.org" -addext \
    "subjectAltName=DNS:example.org"

Reusing the same private key has various disadvantages, notably when someone has obtained a copy of it somehow. There may also be churn every time the certificate changes; this may be no issue if the software is managed under configuration management and everything is automated, or possibly a huge concern if third party software or users must do things on each change. There are multiple ways that a self-signed certificate can be verified.

verification.gmi

../gemini/tofu.gmi

Otherwise, the usual method is to trust some certificate authority, and verify certificates that have been signed by some authority. There are perhaps too many such authorities. Maybe they can be trusted, or maybe not? How would you know? A certificate authority can also be a local one, which hopefully is trustable.

Local Certificate Authority

local-ca.gmi

Client Certificates

These may be required by various servers, gemini servers in particular. Mostly I have this here because I'll forget how to configure it in amfora before too long.

gemini://makeworld.space/amfora-wiki/Client-Certificates.gmi

    #!/bin/sh
    # cargo culted from the Amfora documentation. the filename may need to
    # be based off of the host(s) you use the certificate on, or maybe based
    # on some role?
    uname=${1:-thrig}
    openssl req -new -subj /CN="$uname" -x509 -newkey ec -pkeyopt ec_paramgen_curve:prime256v1 -days 9999 -nodes -out "$uname"cert.pem -keyout "$uname"key.pem

index.gmi