doknow/crypt-le repository overview

⁠Lightweight client for Let's Encrypt, Buypass, other ACME-compatible CAs and servers - Docker version, Alpine Linux based.

Note: This repository supersedes https://hub.docker.com/r/zerossl/client⁠.

Current base version: 0.39, runs as 'ssl' user in the container, not as 'root'.

APIv2 is default, unless a custom server is used or the API version is specified explicitly.

The client supports both ACME v1 and ACME v2 (default) protocols, wildcard certificates issuance, IDN (internationalized domain names), EAB (External Account Binding), etc.

Please consider removing --api 2 option from the command line if you used it before. Even though the client will still work with that option, not having it explicitly set should ensure a better future compatibility if and when APIv3 comes out.

Previous version can be pulled using "previous" tag ("docker pull doknow/crypt-le:previous").

⁠For additional details and documentation visit GitHub repo⁠.

Questions or issues - contact via GitHub⁠ or Do-Know.com⁠.

How to use:

To make it possible to write certificate-related files on the host file system, map /data appropriately or as shown below in the alias example.

• Pull the image (Note: you may need to be in docker group to use it)

  $ docker pull doknow/crypt-le

• Decide which host directory you will be keeping certificate files and keys in and which host directory is your 'acme-challenge' one (the latter is usually created as /webroot/.well-known/acme-challenge, where 'webroot' is the main directory with your web-server pages, often public_html). Let's say you keep files in /home/my_user/keys_and_certs and you are using /home/my_user/public_html/.well-known/acme-challenge. Those directories should be writable by your current user.

• Run the container directly or create an alias similar to the one shown below

  $ alias le.pl='docker run -it -v /home/my_user/keys_and_certs:/data -v /home/my_user/public_html/.well-known/acme-challenge:/webroot -u $(id -u) --rm doknow/crypt-le'

• If you have created an alias (you can add it into your .bashrc for convenience), you can then run le.pl as normal. Without parameters you will be presented with a help screen listing the available options. To see the extended help screen, including usage examples, use --help option.

  $ le.pl

  $ le.pl --help

• If you are using --path option (with or without --unlink) to create verification files automatically, use the mapped path, not the real one, so in the example above it will be /webroot

  $ le.pl --key account.key --csr domain.csr --csr-key domain.key --crt domain.crt --domains "my.domain1.com,my.domain2.com" --generate-missing --path /webroot --unlink

If you want to include domains with different webroots on the same certificate, you should define the mappings first (as demonstrated above, using -v option in an alias command example) and then list webroots for each domain in the --path option (comma separated, in the same order as you list domains themselves).

• If you want to issue a wildcard certificate for your domain, use DNS verification and specify the domain in the following format: *.some.domain. You will also need to use --handle-as dns parameter:

  $ le.pl --key account.key --csr domain.csr --csr-key domain.key --crt domain.crt --domains "*.domain.com" --generate-missing --handle-as dns

Important - if you are issuing a wildcard certificate and also want a so-called "naked domain" ("some.domain") to be covered, list both of those names in the domains parameter. You will then need to create two TXT records with identical names but different values - this is normal and this is how you should create them.

$ le.pl ... --domains "*.some.domain, some.domain" --generate-missing --handle-as dns

---

Don't forget that by default the test certificate is generated, so you will need to use --live option to generate a 'real' trusted one.

---

By default RSA encryption is used, if you want to use ECC, specify a curve name with --curve option. You can use --curve default to use prime256v1.

To update your contact details at Let's Encrypt (to receive expiration notifications), you can use --update-contacts option as shown below:

$ le.pl --key account.key --update-contacts "[email protected]⁠, [email protected]⁠" --live

To remove your contact details use "none" as a value:

$ le.pl --key account.key --update-contacts "none" --live

You can also use --quiet option to suppress all messages but errors (useful when run from crontab).

⁠Using other Certificate Authorities

⁠Some examples:

1. Using ZeroSSL, providing the server parameter explicitly (to be deprecated), and providing eab-kid and eab-hmac-key:

1. Using ZeroSSL, providing the directory parameter explicitly, and providing eab-kid and eab-hmac-key:

1. Using ZeroSSL, providing the ca parameter, and providing eab-kid and eab-hmac-key:

(notice the --live parameter in this case - that is because there is no staging environment, so running the command without --live would produce an error "CA does not support staging environment, please specify 'live' explicitly.")

1. Using Buypass.com (staging environment):

(notice that email parameter is mandatory for this CA, and without it you would get an error "Email is a required contact")

1. Using Buypass.com (production environment):

(notice that email parameter is mandatory for this CA, and without it you would get an error "Email is a required contact")

If CA is ACME-compatible, but not listed above, it would still be supported as long as you know the correct directory URL to specify via a directory parameter - for example, Digicert is supported, but you would need to get a unique directory URL⁠ along with the values for the eab-kid and eab-hmac-key parameters.