Skip to main content

deSEC DNS Authenticator plugin for Certbot

Project description

certbot-dns-desec: Get Let's Encrypt Certificates for Domains Hosted at deSEC

main branch CI test status pypi badge

Certbot plugin to obtain TLS certificates from Let's Encrypt for domains hosted with deSEC.io, using the DNS challenge challenge mechanism.

Installation

To get certificates from Let's Encrypt, install certbot and this plugin. There are many ways to install certbot, this guide uses Python's pip:

python3 -m pip install certbot certbot-dns-desec

Prerequisites

To get a Let's Encrypt certificate for your domain $DOMAIN, you need a deSEC API token $TOKEN with sufficient permission for performing the required DNS changes on your domain. Also make sure that your domain name has been delegated to deSEC (in other words: make sure that the parent registry has the right NS records).

If you don't have a token yet, an easy way to obtain one is by logging into your account at deSEC.io. Navigate to "Token Management" and create a new one. It's good practice to restrict the token permissions as much as possible, e.g. by setting the maximum unused period to four months. This way, the token will expire if it is not continuously used to renew your certificate. Tokens can also be created using the deSEC API.

Request Certificate

To issue and renew certificates using certbot-dns-desec, an access token to your deSEC account is required. To store such a token in a secure location, use, e.g.:

DOMAIN=example.com
TOKEN=your-desec-access-token
sudo mkdir -p /etc/letsencrypt/secrets/
sudo chmod 700 /etc/letsencrypt/secrets/
echo "dns_desec_token = $TOKEN" | sudo tee /etc/letsencrypt/secrets/$DOMAIN.ini
sudo chmod 600 /etc/letsencrypt/secrets/$DOMAIN.ini

Adjust $DOMAIN and $TOKEN according to your domain and deSEC access token, respectively. The file location is just a suggestion and can be changed.

With the credentials stored, you can request a wildcard certificate for your domain by using, e.g.,

certbot certonly \
     --authenticator dns-desec \
     --dns-desec-credentials /etc/letsencrypt/secrets/$DOMAIN.ini \
     -d "$DOMAIN" \
     -d "*.$DOMAIN"

In this command, --authenticator dns-desec activates the certbot-dns-desec plugin; the --dns-desec-credentials argument provides the deSEC access token location to the plugin. These flags can be combined with more sophisticated usages of certbot, e.g. to automatically reload servers after the renewal process. Such functionality is independent of this plugin; for details, see the certbot documentation.

CLI Interface

This plugin is activated by passing the --authenticator dns-desec argument to certbot. It accepts the following command line arguments:

  1. --dns-desec-credentials <file> Specifies the file holding the deSEC API credentials (required, see below).
  2. --dns-desec-propagation-seconds Waiting time for DNS to propagate before asking the ACME server to verify the DNS record.

Credentials File Format

An example credentials.ini file:

dns_desec_token = token

Additionally, the URL of the deSEC API can be specified using the dns_desec_endpoint configuration option. https://desec.io/api/v1/ is the default.

Development and Testing

To test certbot-dns-desec, create a virtual environment at venv/ for this repository and activate it. Register a domain $DOMAIN with desec.io, and obtain a DNS management token $TOKEN. Then run

python3 -m pip install .
TOKEN=token-you-obtained-from-desec-io
DOMAIN=domain-you-registered-at-desec-io
EMAIL=youremail@example.com
echo "dns_desec_token = $TOKEN" > desec-secret.ini
chmod 600 desec-secret.ini
./venv/bin/certbot \
    --config-dir tmp/certbot/config \
    --logs-dir tmp/certbot/logs \
    --work-dir tmp/certbot/work \
    --test-cert \
    -d $DOMAIN -d "*.$DOMAIN" \
    --authenticator dns-desec \
    --dns-desec-credentials desec-secret.ini \
    --non-interactive --agree-tos \
    --email $EMAIL \
    certonly

Maintenance: Prepare New Release

  1. Make sure tests are okay (see GitHub actions)
  2. Commit all changes
  3. Clean up dist/ folder
  4. Set up new release version: RELEASE=x.y.z
  5. Update version to x.y.z in setup.py
  6. Commit with message "Release Version vx.y.z": git commit -p -m "Release Version v$RELEASE"
  7. Tag commit using git tag -as v$RELEASE -m "Release Version v$RELEASE"
  8. Push
    1. branch: git push
    2. tag: git push origin v$RELEASE
  9. Set environment variables GITHUB_TOKEN to a GitHub token, TWINE_USERNAME and TWINE_PASSWORD to PyPi credentials.
  10. Publish using python3 -m publish desec-io certbot-dns-desec

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

certbot-dns-desec-1.2.1.tar.gz (16.7 kB view details)

Uploaded Source

Built Distribution

certbot_dns_desec-1.2.1-py2.py3-none-any.whl (13.3 kB view details)

Uploaded Python 2 Python 3

File details

Details for the file certbot-dns-desec-1.2.1.tar.gz.

File metadata

  • Download URL: certbot-dns-desec-1.2.1.tar.gz
  • Upload date:
  • Size: 16.7 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/1.12.1 pkginfo/1.9.2 requests/2.25.1 setuptools/59.6.0 requests-toolbelt/0.9.1 tqdm/4.64.1 CPython/3.10.6

File hashes

Hashes for certbot-dns-desec-1.2.1.tar.gz
Algorithm Hash digest
SHA256 f22b862e2c7bd938dbc6edc986db7413c50e1e84b49952e2e3cb67bcb2c61046
MD5 ad54ec7fb7bd61a6e3811c79d5bd0fcb
BLAKE2b-256 19d67a4464f17f1de3e2a69928a061c4a082154a2881e999aff37ad4c0b26743

See more details on using hashes here.

File details

Details for the file certbot_dns_desec-1.2.1-py2.py3-none-any.whl.

File metadata

  • Download URL: certbot_dns_desec-1.2.1-py2.py3-none-any.whl
  • Upload date:
  • Size: 13.3 kB
  • Tags: Python 2, Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/1.12.1 pkginfo/1.9.2 requests/2.25.1 setuptools/59.6.0 requests-toolbelt/0.9.1 tqdm/4.64.1 CPython/3.10.6

File hashes

Hashes for certbot_dns_desec-1.2.1-py2.py3-none-any.whl
Algorithm Hash digest
SHA256 cf844dfa3b66086125ad177a117d5e575018226e4e62d1d7b6a3d5840081518d
MD5 30a948dbaa2504bbd710a194d0b3662b
BLAKE2b-256 361dd7e6bc39f4d4013350b9d1b32a842c098535fc909c9381df7e10c9b870f3

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page