Using ZeroSSL's ACME endpoint

Wiki
1

ZeroSSL is an ACME-compatible certificate authority alternative to Let’s Encrypt.

ZeroSSL’s ACME endpoint is already compatible with Caddy because it implements RFC 8555. But Caddy 2.2 has more convenient support for ZeroSSL because it will automatically generate the necessary External Account Binding (EAB) credentials for you.

As of Caddy 2.2, there are several ways to use ZeroSSL. I’ll demonstrate the Caddyfile config, but you can use caddy adapt to get the equivalent JSON.

Using global options

The easiest way is to specify the ZeroSSL ACME directory endpoint along with your email address at the top of your Caddyfile (no account required):

{
    acme_ca https://acme.zerossl.com/v2/DV90
    email   you@yours.com
}

If you manually generated EAB credentials from your account:

Screen Shot 2020-08-11 at 11.04.55 AM
Screen Shot 2020-08-11 at 11.04.55 AM736×438 14.9 KB

Then you can specify them directly (this also works with Caddy 2.1):

{
    acme_ca https://acme.zerossl.com/v2/DV90
    acme_eab {
        key_id  <key_id>
        mac_key <mac_key>
    }
}

Note that EAB is always required with ZeroSSL, but you do not have to manually generate the EAB credentials if you provide your email address.

Using the tls directive

If you want to use ZeroSSL for only some of your sites, you can use the tls directive like you’re used to:

tls you@yours.com {
    ca https://acme.zerossl.com/v2/DV90
}

Or, with manually-generated EAB credentials:

tls {
   ca  https://acme.zerossl.com/v2/DV90
   eab <key_id> <mac_key>
}
4 Likes
2

A post was split to a new topic: JSON equivalent of cert_issuer global option

3

(global options)

This is lacking in description. You also need acme_ca, Like “Using the tls directive”:

{
    acme_ca https://acme.zerossl.com/v2/DV90
    acme_eab {
        key_id  <key_id>
        mac_key <mac_key>
    }
}
1 Like
4

Good point, thanks. (This is a wiki, so you could also edit the post, FYI.)

1 Like
5

2 posts were split to a new topic: Business contact

6

Quick question: the default which falls back from LE to ZeroSSL is quite nice (thanks!) so I was wondering, would it be possible to specify ZeroSSL credentials (so it’s using a known account and we can see certs in the UI, etc…) while still keeping the LE / ZeroSSL fallback?

7

Yeah, the tls directive lets you specify multiple issuers so you can still use both Let’s Encrypt and ZeroSSL.

tls {
   issuer acme
   issuer zerossl <api_key>
}
8

Oh that’s nice! will try it then.
Sorry if I missed it but I didn’t see this in the documentation, is it somewhere?
Also is the order important here? will it always try let’s encrypt first and then zerossl after (some?) retries?
Thanks for this great tool :wink:

9

Do not use the settings using eab in multiple environments.
It applies to only one environment and will fail to publish in the other.
You should use your email address or API instead.

https://github.com/jetstack/cert-manager/issues/2882

10

I have a question.
How can I use both the options letsencrypt and zerossl?
Or I need to do nothing if I want to use zerossl as a fallback option.

In my configuration file, email was not mentioned and certificate couldn’t be generated by letsencrypt due to some reason. So in that case, caddy didn’t generate certificate using fallback option i.e. zerossl.

11

Issuer fallback is enabled by default, unless you explicitly configure issuers, in which case it would replace the defaults.

If you’re not sure or need more help, please open a new topic and fill out the help topic template.

1 Like
12

Doesn’t look like this works anymore?

I tried with the tls directive:

143.198.139.109 {
    tls coolaj86+test@gmail.com {
        ca https://acme.zerossl.com/v2/DV90
    }
    root * /tmp/public/
    file_server
}

2022/06/10 08:54:47.587	ERROR	tls.obtain	will retry	{"error": "[143.198.139.109] Obtain: subject does not qualify for a public certificate: 143.198.139.109", "attempt": 1, "retrying_in": 60, "elapsed": 0.000437592, "max_duration": 2592000}

And with the cert_issuer directive:

rm -rf ~/.config/caddy
rm -rf ~/.local/share/caddy

{
	cert_issuer zerossl yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy
}

143.198.139.109 {
	root * /tmp/public/
	file_server
}

No error, but the certs aren’t generate via zerossl.

13

@coolaj86 AFAIK no ACME issuer currently supports IP certificates. But ZeroSSL supposedly does now but it needs to be tested by making a change in Certmagic before we enable it:

2 Likes
14

Hello @matt!

Would it be possible to use the following configuration and would it be valid?

Using global options

{
    email   you@yours.com
    cert_issuer zerossl
}

Using the tls directive

tls you@yours.com {
    issuer zerossl
}

That is, use cert_issuer zerossl (or issuer zerossl) without the api_key but setting the email.

On the other hand, is setting the ZeroSSL ACME directory endpoint using acme_ca (global options)/ca (tls directive) equivalent to doing it using cert_issuer (global options)/issuer (tls directive) zerossl? Is there any other change beyond cert_issuer/issuer supporting the api_key?

That is, what are the implications of doing this configuration using acme_ca/ca with respect to doing it using cert_issuer/issuer?

Thanks in advance.

15

To use the ZeroSSL issuer, you’ll need to put your API key in the configuration. The API doesn’t have a way to get API key from email address.

However, if you specify only an email address, Caddy will default to using Let’s Encrypt and ZeroSSL ACME endpoints with that email address.

Specifying the zerossl issuer always uses the ZeroSSL API.

Anything using the keyword zerossl is going to use the ZeroSSL API; if you want to use their ACME endpoint, specify ACME-related config options, and be sure to give ZeroSSL’s ACME endpoint.

If you have any questions about the implications of a complex Caddyfile config, run caddy adapt on it and inspect the JSON to be sure.

2 Likes