django-cats/README.md

# CAcert Assurer Training System - CATS

This is a Django port of the original
[CATS](https://code.cacert.org/cacert/cats/). The goal of this port is to use
current best practices in software engineering and to reduce boilerplate by
using a properly maintained web framework.

## Development setup

The project uses [Poetry](https://python-poetry.org/docs/) for dependency
management. On a Debian 12 system you can use the following commands to install
poetry and required dependencies:

```shell
sudo apt update
sudo apt install -y build-essential pkg-config default-libmysqlclient-dev python3-dev pipx
pipx install poetry
pipx ensurepath
```

If `pipx ensurepath` recommends to open a new shell, do it.

```shell
git clone https://code.cacert.org/cacert/django-cats.git
cd django-cats
poetry install
```

## Enabling client certificate authentication using nginx

The application expects a client to send a client certificate. You may
configure nginx as a reverse proxy to accomplish this. The configuration
example below assumes that you have the application running on port 8000
(either via `poetry run python3 manage.py runserver` or via
`poetry run gunicorn -c config/gunicorn/dev.py`).

You will need a private key and certificate for your local hostname
(`cats-dev.localhost` in the example below).
[`mkcert`](https://github.com/FiloSottile/mkcert) is a good choice to create
these.

You will also need the concatenated PEM encoded CA certificates that you want
to allow for client certificate authentication. You may retrieve the CAcert
CA certificates using:

```shell
(curl https://www.cacert.org/certs/CAcert_Class3Root_x14E228.crt ; \
 curl https://www.cacert.org/certs/root_X0F.crt) \
  > cacert_ca_certificates.pem
```

```
server {
	listen 80;
	listen [::]:80;
	listen 443 ssl;
	listen [::]:443;
	server_name cats-dev.localhost;

  	ssl_certificate /<path to your certificates>/cats-dev.localhost.pem;
  	ssl_certificate_key /<path to your certificates>/cats-dev.localhost-key.pem;
  	ssl_protocols TLSv1.2 TLSv1.3;
  	ssl_ciphers kEECDH+AESGCM:kEECDH+RC4:kEECDH+AES:kEECDH:EDH+AESGCM:kEDH+RC4:kEDH+AES:kEDH:AESGCM:RC4:ALL:!LOW:!EXP:!MD5:!aNULL:!eNULL;
  	ssl_prefer_server_ciphers on;
  	ssl_session_cache shared:SSL:10m;

	ssl_client_certificate /<path to your certificates>/cacert_ca_certificates.pem;
	ssl_verify_client optional;
	ssl_verify_depth 1;

	add_header Strict-Transport-Security "max-age=31536000; includeSubDomains";

	if ($https = "") {
		return 301 https://$host$uri;
	}

	location / {
		proxy_pass	 http://localhost:8000;
		proxy_set_header Host $host;
		proxy_set_header X-SSL-CERT $ssl_client_escaped_cert;
	}
}
```

## License

CATS
Copyright (C)  CAcert

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program.  If not, see <https://www.gnu.org/licenses/>.