Using per-domain SSL certificates

[neosonic2]

Hi all,

I'm new to Stalwart and am really enjoying it so far while I work to set it up as a replacement for my current Postfix/Dovecot cluster. The current cluster hosts email accounts for many different domains, and Postfix is configured with individual TLS certificates (issued by Let's Encrypt) for each domain, by way of the tls_server_sni_maps option in main.cf.

Does Stalwart have a similar feature? I noticed the web UI lets you add multiple certificates but, at least when using the internal directory, there doesn't seem to be a way to designate that a specific certificate is for a specific domain you've already created in the directory.

I also know you can use the file macro to retrieve certificate contents from a text file, but I'm unsure how to specify a separate certificate file for each domain, especially in a dynamic fashion (i.e. where the domain name is part of the certificate filename); the docs only give the example of using one certificate file that I assume covers multiple domains.

Ideally, I'm looking for a way to do the following:

1. Create a domain in Stalwart's internal directory.
2. Use existing processes outside of Stalwart to request a certificate for the domain (including subdomains like mail.domain.tld) via Let's Encrypt, and store it in /etc/letsencrypt/live/domain.com/fullchain.pem.
3. Tell Stalwart to use, via the file created in step 2, this particular certificate for this particular domain, so that when a user uses mail.domain.tld as their incoming or outgoing server address, they won't receive an invalid certificate error (or be told the certificate is for a different hostname). Assume this address is mapped to the Stalwart host.

Is this possible? I appreciate in advance any insights provided.

[andreymal]

Each certificate contains information about which domains it's valid for, so Stalwart can automatically select the correct certificate without any manual mapping.

Also, TLS configuration is not related to domains from the directory.

[neosonic2]

Thanks for the info. If that is the case, how would one add multiple certificates (one per domain) to the configuration file? The [example in the docs](https://stalw.art/docs/server/tls/certificates/#configuration) only shows one cert, the default used for the entire instance. Better yet, are there API endpoints for managing certificates? The [API docs](https://stalw.art/docs/api/management/endpoints) don’t seem to mention this functionality.

[andreymal]

Just duplicate it as many times as needed, remembering to change the certificate id/name

[certificate.default]
cert = "%{file:/etc/letsencrypt/live/example.org/fullchain.pem}%"
private-key = "%{file:/etc/letsencrypt/live/example.org/privkey.pem}%"
default = true

[certificate.example.net]
cert = "%{file:/etc/letsencrypt/live/example.net/fullchain.pem}%"
private-key = "%{file:/etc/letsencrypt/live/example.net/privkey.pem}%"
default = false

Since certificates are settings, /api/settings is used to manage them

[neosonic2]

Thank you, this is exactly what I was looking for! I haven't had a chance to test this setup yet but should be able to do so over the weekend, however it sounds like it should solve my problem perfectly by allowing me to define multiple certs, one per domain, either directly in the config file or via the REST API. Do you by any chance know the setting keys I'd need to refer when calling /api/settings?

[andreymal]

/api/settings is not very intuitive, I recommend playing around with the webadmin and using browser devtools (F12 > Network) to see what requests it sends when changing TLS settings

A (formatted) example of the keys generated by this config file:

$ curl -u 'admin:password' 'https://mail.example.org/api/settings/keys?prefixes=certificate.'

{
  "data": {
    "certificate.default.cert": "%{file:/etc/letsencrypt/live/example.org/fullchain.pem}%",
    "certificate.default.default": "true",
    "certificate.default.private-key": "%{file:/etc/letsencrypt/live/example.org/privkey.pem}%",
    "certificate.example.net.cert": "%{file:/etc/letsencrypt/live/example.net/fullchain.pem}%",
    "certificate.example.net.default": "false",
    "certificate.example.net.private-key": "%{file:/etc/letsencrypt/live/example.net/privkey.pem}%"
  }
}

[neosonic2]

Thanks, this was very helpful as you're right - the API docs aren't very intuitive, but to give credit where it's due the rest of the documentation is very well detailed and has been a huge help on my journey of setting up Stalwart.

I also figured out that you can use API keys to authenticate requests rather than providing the username and password as you did in your example. Your suggestion of using the browser developer console to learn the API has been working great so far given the lack of extensive documentation on each endpoint.

For the curious, the API documentation seems to suggest that you need to authenticate via oAuth and retrieve an access token before you can use it (as the first endpoint, /api/oauth, deals with retrieving this token), but this is not the case; an API key will work just fine when passed in as a bearer token via the Authorization HTTP header.