LabCA

A private Certificate Authority for internal (lab) use, based on the open source ACME Automated Certificate Management Environment implementation from Let's Encrypt (tm).

08-dashboard

Background
Startup
Usage
Troubleshooting
Standalone version for step-ca
Legacy Mode
Contributing
License

Background

More and more websites and applications are served over HTTPS, where all traffic between your browser and the web server is encrypted. With standard HTTP the (form) data is unencrypted and open to eavesdroppers and hackers listening to communications between the user and the website. Therefore the Chrome browser now even warns about unsafe plain HTTP sites to nudge users towards HTTPS.

To a lesser extent this also applies to internal applications and sites that are not exposed publicly. Just because the users may have a higher level of trust versus users of a public facing website doesn't mean sensitive content shouldn't be protected as much as possible. Lots of hacking and theft occur from within a company's own walls, virtual or real. Also, no user should get used to ignoring any browser warnings (e.g. about self-signed certificates), even for internal sites.

no user should get used to ignoring any browser warnings

For the public internet, Let's Encrypt™ has made a big impact by providing free HTTPS certificates in an easy and automated way. There are many clients available to interact with their so called ACME (Automated Certificate Management Environment). They also have a staging environment that allows you to get things right before issuing trusted certificates and reduce the chance of your running up against rate limits.

One technical requirement however is to have a publicly reachable location where your client application and their server can exchange information (for the HTTP-01 challenge type at least, alternatively there is also the DNS-01 method). For intranet / company internal applications or for testing clients within your organization this may not always be feasible.

Luckily they have made the core of their application, called "Boulder", available as open source. It is possible to install Boulder on your own server and use it internally to hand out certificates. As long as all client machines / laptops in your organization trust your root CA certificate, all certificates it signed are trusted automatically and users see a green lock icon in their browsers.

Also if you are developing your own client application or integrating one into your own application, a local test ACME can be very handy. There is a lot of information on the internet about setting up your own PKI (Public Key Infrastructure) but those are usually not automated.

Getting Boulder up and running has quite a learning curve though and that is where LabCA comes in. It is a self-contained installation with a nice web GUI built on top of Boulder so you can quickly start using it. All regular management tasks can be done from the web interface.

Startup

NOTE: LabCA depends on the boulder engine which cannot run on a Raspberry Pi.

NOTE2: The hostname of your LabCA machine must be in a local DNS for the boulder engine to be able to give out a certificate for it.

Make sure to have docker with the compose plugin installed on the machine where you want to run LabCA, e.g. on Ubuntu/Debian machines do:

sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin

For the initial setup you need to export an environment variable LABCA_FQDN with the FQDN (Fully Qualified Domain Name, the name you would use in the browser for accessing the web pages). It is not possible to run LabCA on an IP address only, there must be a DNS mapping present.

git clone https://github.com/hakwerk/labca.git
cd labca/build
export LABCA_FQDN=labca.example.com
docker compose up -d

To tail the logs, especially if there are any issues:

docker compose logs -f

All data is stored in docker volumes, you'll want to include those in your regular backups.

In case you get an error like this after running docker compose up:

Error response from daemon: failed to create shim task: OCI runtime create failed: runc create failed: unable to start container process: exec: "labca/entrypoint.sh": stat labca/entrypoint.sh: no such file or directory: unknown

then you forgot to export the LABCA_FQDN environment variable.

Setup

After the base install you must go through the setup in your browser. To give an idea of the setup process, see these screenshots:

Once the setup is completed, please make a backup of your Root and Issuer certificates! They can be exported from the "Certificates" tab of the Manage page. On the "Backup" tab you can also create a backup of the relevant data on the server. The backup files should be synchronized to an external location, but that is out of scope of this document.

Update

By default, the latest LabCA docker image version tags are used when you start it. In case there is a newer version of images available, you can update to the new :latest versions by doing something like:

docker compose pull
docker compose up -d --remove-orphans
docker image prune

Or you can use something like watchtower to automatically keep the images updated, or Diun to inform you about new images.

If you prefer to use specific versions of the images and only update when you explicitly want to, you can set the LABCA_IMAGE_VERSION environment variable to an explicit version number. The easiest way to do this is by using a .env file in the same location as the docker-compose.yml file, e.g. by using something like this:

echo "LABCA_IMAGE_VERSION=v25.03" > labca.env

Usage

Once LabCA has been setup, your instance is ready to provide HTTPS certificates for your internal applications.

Admin

The admin section is only accessible to the user account created at the start of the setup. The dashboard gives an overview of the current status of your LabCA instance. Via the menu you can navigate to the details of your ACME objects such as the certificates, to several system logfiles and to the various management tasks such as backup/restore and changing your password.

These screenshots give a preview of the admin section:

ACME Client

To request and automatically renew certificates for your applications, you need one of the many standard ACME clients that are out there. Just make sure to configure the server hostname to be your LabCA instance.

Some of the commonly used clients are:

Make sure to configure the client to use the server URL "https://YOUR_LABCA_FQDN/directory".

Public Pages

The end users in your organization / lab can visit the public pages of you LabCA instance to get some basic information, and to download the root certificate that needs to be installed on each device that should trust the certificates generated by the LabCA instance. To give you and idea of what that looks like:

Troubleshooting

After installing sometimes the application is not starting up properly and it can be quite hard to figure out why. First, make sure that all six containers are running:

root@testpki:/home/labca/labca# docker compose ps -a
NAME                IMAGE                               COMMAND                  SERVICE     CREATED        STATUS        PORTS
labca-bconsul-1     hashicorp/consul:1.1

Labca

Install / Use

README