StecCA

An easy to deploy Certificate Authority using CFSSL, Lemur and Docker magic!

About • Technologies • Key Features • How To Use • Contributing • Support • License

About The Project

I needed to manage certificates for my home lab, I'm self-hosting some services and of course, I wanted a full working SSL without errors.

In these situations, a Certificate Authority is needed, but using OpenSSL just from the terminal resulted unpractically and not ideal for managing the various certificates; so I decided to deploy a better system to do these tasks.

So I came across Lemur and CFSSL... I choose CFSSL because it has a very easy to use CLI, offers an OSCP responder and it is integrable with Lemur; Lemur is a platform that offers a web interface and SQL Database for managing the certificates, this way issuing, revoking, and keep track of them would be much more efficient to do.

Anyways, there were no products that integrated all of these technologies so using some guides and my expertise I've set up them together using docker and some scripts to have everything as clean as possible and very easy to redeploy.

Now I'm publishing it to GitHub because it could be really useful for a lot of people! I'd also like to further improve the projects making the integration better and adding even more functionalities for various use cases.

Need to quickly set up your CA in a matter of minutes? It is not a problem anymore!

Built with

This project uses the following technologies:

CFSSL acts as the core engine for SSL, being called upon the generation of CA and certificates while Lemur offers an integrated system with a web interface to make the management very very easy.

Everything is stored thanks to the PostgreSQL DB.

The deployment is done with docker and some bash scripting, it makes data persistence and deployment really fast and repeatable.

Key Features

• Easy and fast deploy!
  • Thanks to docker and bash scripting deploying a fully working CA doesn't take hours anymore!
• Root CA and Intermediary CA
  • Root CA is not directly exposed, an Intermediate CA (signed by root) will be signing the user created certificates.
• Web Interface
  • Lemur provides an easy-to-use web interface to issue, manage and revoke certificates.
• Automation
  • Lemur provides various automated checks on certificates, some have already been enabled but many many more can be enabled depending on your needs.
• Persistence
  • The integration with PostgreSQL of both CSSL and Lemur allows to easily manage and make persistent all the data needed.
• OSCP Responder
  • CFSSL's OSCP responder has been set up, including automatic updates. (I'm Not sure if it is already working as I configured it, so any help is really appreciated)

Getting Started

Getting the CA up and running is fairly easy if you pay attention in following these little steps, the guide and the scripts are assuming that you are using a Debian based Linux distro (including Ubuntu Server or Raspbian) but support for other distro is very feasible because only the 'apt' commands need to be changed.

If on debian, pay attention during the passage in wich the scripts imports the golang ppa

Windows is a nono, but maybe adapting the setup scripts will make it doable.

Prerequisites

As a prerequisite, you should just need an up and running Docker and Docker Compose installation. This will not be done by the script.

Please refer to the Docker install guide and Docker-Compose install guide to complete this passage

It is very quick and easy, don't worry.

You need a working firewall, i suggest to

• Install UFW

  sudo apt update
  sudo apt install ufw

Otherwise, you need to edit lines 69 and 70 of setup_cfssl.sh to obtain the same firewall rules, this is very important or otherwise, the ROOT CA will be exposed in the network! (CFSSL Auth cannot be integrated with Lemur yet)

Installation

I'm using nano in some commands, but you can use any editor you want of course!

1. Clone the repo

   git clone https://github.com/Steccas/stecCA.git

2. Edit cfssl-config.json to have the right url for yor crl and oscp, it may be localhost. Leave the same ports.

   nano ./cfssl-config.json

3. Edit csr_root_ca.json and csr_intermediate_ca.json to setup the right values for your root CA and intermediate CA, there are already exaple values, change them and you are good to go.

   nano ./csr_root_ca.json
   nano ./csr_intermediate_ca.json

4. Similiarly, edit ocsp.csr.json to have the right informations for your OCSP.

   nano ./ocsp.csr.json

5. Edit lemur.env to have the same informations available to Lemur. Don't touch the password, it will be set later automatically.

   nano ./lemur.env

6. Edit creds.env to setup username and password for DB and other services, they will be automatically changed in the other files and will be automatically used; so use a complicated one.

   nano ./creds.env

   CHANGE THEM, the one put in the files are meant to be a placeholder or a default password for testing at best!

7. Start the setup script as root, it will ask if you configured everything, but if you don't do and something doesn't work as expected or you leave the default password (that everyone in github will know) it is up to you! Also, before running make sure that you have the execute permission flag.

   chmod u+x ./setup_cfssl.sh
   sudo ./setup_cfssl.sh

8. The setup will ask at some point to paste the pem certs data at the bottom of lemur.conf.py, it is important or Lemur WILL NOT WORK.

   nano ./lemur.conf.py

   and at the bottom look for these values and change them according to the outputted PEMs and your choosen url.

   CFSSL_URL ="http://ca.example.lan:8888" #change this with machine ip or dns name
   CFSSL_ROOT ="""<insert root pem here>"""
   CFSSL_INTERMEDIATE ="""<insert intermediate pem here>"""

   After this it will start everything up and as a last passage it will ask to add this to crontab, of course set also your desired frequency, which wil be opened for you in 5 seconds.

   cfssl ocspdump -db-config /etc/cfssl/db_config.json> /etc/cfssl/ocspdump

9. Check the health of the containers with

   docker ps

   If they are not healty or something doesn't work, check every passage, open an Issue or check Support.

10. Enjoy

Usage

You can now simply open Lemur at port 443 of your machine (using your IP, localhost, or DNS name) and log in with your defined credentials, the web interface password is defined in the lempass environment variable, the username is "lemur".

Of course, remember to add your CA to your OSes and browsers.

The interface is really easy, but please refer to Lemur documentation for better instructions.

If you need to reboot your server it is not a problem, docker-compose should bring services up again and thanks to data persistence everything will be there.

This means that if you backup your CFSSL data and Docker volumes you can easily migrate to another machine.

Contributing

Contributions are what make the open source community such an amazing place to be learn, inspire, and create.

And this project can be greatly improved!

Any contributions you make are greatly appreciated.

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

You can also consider to help with a donation ❤️

Support

This project comes without any warranty, you are responsible for the deployment. If you encounter open an issue, consider getting a sponsor plan or contact me to get dedicated support.

License

Distributed under the GNU GPL V3 License. See LICENSE for more information.

---

linktr.ee  ·  GitHub @Steccas  ·  LinkedIn Luca Steccanella