lets-encrypt.rst 4.4 KB

12345678910111213141516171819202122232425262728293031323334353637383940414243444546474849505152535455565758596061626364656667686970717273747576777879808182838485868788
  1. TLS Certificate with Let's Encrypt
  2. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  3. certbot with deSEC hook
  4. ```````````````````````
  5. dynDNS by deSEC supports the DNS challenge protocol to make it easy for you to
  6. obtain certificates for your domain name easily from anywhere. All you need is
  7. `certbot <https://certbot.eff.org/>`_, your credentials and our certbot hook
  8. script. As always, we appreciate your feedback. Shoot us an email!
  9. To obtain a Let's Encrypt Certificate for your dedyn.io domain, follow these
  10. steps.
  11. #. **Install Certbot.** There are many ways to install certbot, depending on
  12. your distribution and preference. Please follow the official instructions at
  13. `<https://certbot.eff.org/>`_.
  14. #. **Install hook script.** To authenticate your dedyn.io domain against Let's
  15. Encrypt using the DNS challenge mechanism, you will need to update your
  16. domain according to instructions provided by Let's Encrypt. Our hook script
  17. automates this process for you. To use it, download the following two
  18. files and place them into a directory of your choice. Make sure to change
  19. the owner/permissions of the file (``chown``/``chmod``), so that it is only
  20. readable by your certbot user (usually ``root``). ::
  21. wget https://raw.githubusercontent.com/desec-io/desec-certbot-hook/main/hook.sh
  22. wget https://raw.githubusercontent.com/desec-io/desec-certbot-hook/main/.dedynauth
  23. #. **Get a token.** You need to configure an API token so that certbot can use
  24. it to authenticate its requests towards the deSEC API. The easiest way to
  25. get such a token is to log into the web interface at https://desec.io/,
  26. navigate to "Token Management", and create a token there.
  27. #. **Configuration.** You need to provide your dedyn.io credentials to the hook
  28. script, so that it can write the Let's Encrypt challenge to the DNS on your
  29. behalf. To do so, edit the ``.dedynauth`` file to look something like::
  30. DEDYN_TOKEN=[your token] # remove brackets, token from above step
  31. DEDYN_NAME=[yourdomain.example.com] # remove brackets, add your domain to your desec.io account first
  32. #. **Run certbot.** To obtain your certificate, run certbot in manual mode as
  33. follows. (For a detailed explanation, please refer to the certbot manual.)
  34. Please notice that you need to insert your domain name one more time. (Also,
  35. for users not familiar with shell commands, please note that you need to
  36. remove the ``\`` if you reformat the command to fit on one line.) ::
  37. certbot --manual --manual-auth-hook ./hook.sh --manual-cleanup-hook ./hook.sh \
  38. --preferred-challenges dns -d "YOURDOMAINNAME.dedyn.io" certonly
  39. Please note that the hook script may wait up to two minutes to ensure that
  40. the challenge was correctly published.
  41. To include subdomains in your certificate, you can specify the ``-d``
  42. argument several times, e.g.
  43. ``-d "YOURDOMAINNAME.dedyn.io" -d "www.YOURDOMAINNAME.dedyn.io"``.
  44. Similarly, you can get wildcard certificates like so::
  45. certbot --manual --manual-auth-hook ./hook.sh --manual-cleanup-hook ./hook.sh \
  46. --preferred-challenges dns -d "example.com" -d "*.example.com" certonly
  47. To make the process headless, add ``--agree-tos -n`` (this implies agreeing
  48. to their Terms of Service!). Let's Encrypt asks for an email address to
  49. send expiration notices to, which you can provide with
  50. ``--email [your email]``. To sign up without email, use
  51. ``--register-unsafely-without-email`` instead (discouraged).
  52. If you would like to help improve this hook script, please check out our
  53. open issues at `<https://github.com/desec-io/desec-certbot-hook/issues>`_.
  54. We'd highly appreciate your help!
  55. Other ACME clients
  56. ``````````````````
  57. There are other ACME clients that support deSEC out of the box. We currently
  58. know of the following:
  59. - `acme.sh <https://github.com/Neilpang/acme.sh/wiki/dnsapi#71-use-desecio>`_
  60. - `deSEC certbot plugin <https://pypi.org/project/certbot-dns-desec/>`_
  61. - `cert-manager web hook <https://github.com/kmorning/cert-manager-webhook-desec>`_
  62. (Kubernetes)
  63. - `lego <https://github.com/go-acme/lego>`_
  64. - `Posh-ACME <https://github.com/rmbolger/Posh-ACME/blob/main/Posh-ACME/Plugins/DeSEC-Readme.md>`_
  65. - `Terraform vancluever/acme <https://registry.terraform.io/providers/vancluever/acme/latest/docs/guides/dns-providers-desec>`_
  66. Our forum has `a more updated list <https://talk.desec.io/t/tools-implementing-desec/11>`_.