Introduction

Serles is a tiny ACME-CA implementation to enhance your existing Certificate Authority infrastructure. Initially developed to support ACME with the Open Source version of PrimeKey’s EJBCA’s (ACME support is only available in the Enterprise version), the software is designed for easy adaptation to other PKI software/CAs which provide an API to issue certificates.

We sometimes call it a proxy, as it delegates certificate issuance to your existing PKI. From a user’s point of view, serles-acme can be your own private Let’s Encrypt, when combined with EJBCA.

If you want to use another PKI, feel free to implement your own backends. Contributions are welcome.

Who is this project for?

• You want to build up your own PKI, either for company or home use

• You want to automate the issuing process for all your devices

• You already use another PKI Software and want to use certbot with it

Architecture

Serles is intended to automate certificate issuance from your existing CA. It will verify the legitimacy of certificate requests, and, if this is the case, pass them on to a plugin/backend.

+--------+                            +--------+                        +---------+
|        | (1) ---{authentication}--> |        |                        | Backend |
|  Web   | (2) ---{order cert}------> | Serles |                        |  (e.g.  |
| Server | <-----{validation}-----(3) |  ACME  |                        |  EJBCA) |
|        | (4) ---{CSR}-------------> |        | (5) ---{CSR}---------> |         |
+--------+ <-----{certificate}--- (7) +--------+ <--{certificate}-- (6) +---------+

The threat model is execution inside a (trusted) enterprise network. Yet, care has been taken when accepting any user data. While there is no user authentication (i.e. anyone who can access Serles is allowed to ask for certificates), one may specify to which IP subnets requested domains must resolve in order to be granted a certificate.

Installation

See installation https://serles-acme.readthedocs.io/en/latest/installation.html.

Configuration

The configuration file can be set using the CONFIG environment variable. If it is absent, it is loaded from /etc/serles.ini. An extensively commented example configuration file is included as config.ini.example. You may copy (and rename) it to the beforementioned location. Serles is compatible with any WSGI server; please consult your server’s manual for its configuration.

Backends

The software ships with a few predefined backends, but it is easy to write others. If you do, please send patches!

A backend is simply a class (no inheritance required) and has the following methods:

• a constructor taking the parsed config (ConfigParser object; dict-like)

• a method sign(self, csr, subjectDN, subjectAltNames, email):

  Parameters:

  • csr: the CSR as coming from the client (in PEM-encoded PKCS#10 format)

  • subjectDN: The CSR’s Distinguished Name as a string or, if absent, one created from the template string in the config file.

  • subjectAltNames: a list of domain names (as strings) that are to be written in the certificate’s SAN extension attributes.

  • email: the email stored in the requesting account (or None). Intended to be passed on to the backend for notification of the client.

  Returns:

  • on success, the tuple (pem_chain, None) where pem_chain is the full PEM-encoded certificate chain.

  • on error, the tuple (None, error_msg), where error_msg is a string (possibly forwarded from the backend) that describes why the CSR has been rejected. This is forwarded to the client in a badCSR problem document.

class SomeBackend:
    def __init__(self, config):
        self.config = config
    def sign(self, csr, subjectDN, subjectAltNames, email):
        return None, "not implemented"

Optionally, one can also inherit from the abstract serles.backends.base:

class SomeBackend(serles.backends.base):
    def sign(self, csr, subjectDN, subjectAltNames, email):
        return None, "not implemented"

preferred-challenges=dns
dns-route53

preferred-challenges=dns
dns-cloudflare
dns-cloudflare-credentials=/path/to/cloudflare.ini

config-dir=/local/acme/certbot/config
work-dir=/local/acme/certbot/work
logs-dir=/local/acme/certbot/logs

Dependencies

Dependencies are stated in setup.py.