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
}

You can also configure the zerossl issuer explicitly with your ZeroSSL account’s API key:

{
    cert_issuer zerossl <api_key>
}

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; Caddy 2.2 can do that for you using the first two configurations.

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 an API key:

tls {
    issuer zerossl <api_key>
}

Or, with manually-generated EAB credentials:

tls {
   ca  https://acme.zerossl.com/v2/DV90
   eab <key_id> <mac_key>
}
3 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.

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:

1 Like