Starting point for this administration guide

At first you need to ensure that you have command line access to the deaddrop system. Details on how this works is described in the system administration document, but in general works as any other linux based system (e.g. ssh)

Prerequisites

To use client certificates or smartcards, you need to have trusted CA that can issue client certificates. This is not included in deaddrop.

Defining trusted certificate authorities

The first step is to define the list of all trusted certificate authorities for client client certificates. This is not to be confused with other CA:s, (such as lets encrypt, which provides a trusted webserver certificate).

This is a list of PEM-encoded x509 certficates stored in the following file:

/opt/sysctl/deaddrop/etc/deaddrop/certs/ca-bundle.trust.crt

Note that the trust from these certificates are absolute and global. All CA:s are trusted equally.

Once this file is updated, it must be loaded. Issue the following commands:

cp /opt/sysctl/deaddrop/etc/deaddrop/conf.d/ca-trust.conf.disabled /opt/sysctl/deaddrop/etc/deaddrop/conf.d/ca-trust.conf
systemctl restart deaddrop

Mapping client certificates to email addresses

Mappings are done by creating a json file stored in

/opt/sysctl/deaddrop/conf/certmap.json

It is a array mappings, where each mapping is a array of hashes consisting of issues subject pairs to email addresses.

An example file is provided in

/opt/sysctl/deaddrop/conf/certmap.json.example

that can be used as a template. Examples of expected formating of subject and issuer fields can be obtained by browsing to the https://deaddropurl/x509/cgi/list.cgi with a trusted smart card plugged in. This will show the values in the correct notation.

To enable the certificate login button, edit the admin config file /opt/sysctl/deaddrop/conf/admin.conf and add the following row:

client_cert_enabled=1

Certmap updates

The certmap file is monitored by the system and gets updated automatically. The following logic applies:

If the file is missing, the certmap update will exit on start.
If the file is invalid, the certmap update program will exit with an error
If the file gets updated, the certmap update program will update all existing userconf.d files containing x509 client certificate mappings

Fixing a broken certmap file will directly rewrite all declared mappings. Config files where previous mappings existed that have been removed from the certmap will be locked.

It is possible for an administrator to manually start the certmap update program by issuing the following command:

systemctl start deaddrop-certmapsync

The program logs to the following path: /var/log/deaddrop/backend/certmap.log

Note: Certmap will only update files that exists. If a mapping exists, but has never been used (thus not creating the relevant account), certmap will ignore the entry.

Certificate revocation

To enable Certificate revocation checks, the following steps need to be performed:

Edit /opt/sysctl/deaddrop/conf/crllist.conf and add the url(s) to the CRL file
Start the crlfetch daemon.

starting the crl-fetch task

Issue the following command

systemctl enable --now deaddrop-crlfetch.timer

This will start fetching the crls every hour. To force the system to fetch the crl, perform the following command:

systemctl start deaddrop-crlfetch

This will fetch the initial crls and store them in the /opt/sysctl/deaddrop/etc/deaddrop/crls/complete.crl file.

To inspect the logs from the daemon, issue the following command:

journalctl -f -u deaddrop-crlfetch

Deaddrop will monitor all changes to the /opt/sysctl/deaddrop/etc/deaddrop/crls/complete.crl file. If it is changed, a validation will be performed to see if the file is a valid CRL file. If it is, deaddrop will load the file and restart, to ensure that all threads are subject to the revocation list.

If the file is not a valid CRL file, deaddrop will remove the loading of the CRL, but it will not restart as that would remove the exiting CRL:s in memory.

It does this by creating (and removing) the /opt/sysctl/deaddrop/etc/deaddrop/conf.d/revocation.conf file.