certbot-dns-netcup 2.0.2__py3-none-any.whl

certbot_dns_netcup-2.0.2.dist-info/METADATA

@@ -0,0 +1,229 @@
+Metadata-Version: 2.4
+Name: certbot-dns-netcup
+Version: 2.0.2
+Summary: netcup DNS Authenticator plugin for Certbot
+Author-email: Thomas Gläßle <thomas@coldfix.de>
+License-Expression: Apache-2.0
+Project-URL: Source Code, https://github.com/coldfix/certbot-dns-netcup
+Project-URL: Issue Tracker, https://github.com/coldfix/certbot-dns-netcup/issues
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Plugins
+Classifier: Intended Audience :: System Administrators
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Security
+Classifier: Topic :: System :: Installation/Setup
+Classifier: Topic :: System :: Networking
+Classifier: Topic :: System :: Systems Administration
+Classifier: Topic :: Utilities
+Requires-Python: >=3.7
+Description-Content-Type: text/x-rst
+License-File: LICENSE.txt
+Requires-Dist: certbot>=2.7
+Requires-Dist: requests
+Dynamic: license-file
+
+certbot-dns-netcup
+==================
+
+|Version| |License| |ImageSize|
+
+netcup_ DNS Authenticator plugin for certbot_.
+
+This plugin automates the process of completing a ``dns-01`` challenge by
+creating, and subsequently removing, ``TXT`` records using the netcup `CCP
+API`_.
+
+**Note:** This plugin requires certbot ≥ v2.7.
+
+If you need support for older certbot versions, check version 1.4.X and below.
+
+.. _netcup: https://www.netcup.de/
+.. _certbot: https://certbot.eff.org/
+.. _CCP API: https://www.netcup.com/en/helpcenter/documentation/domain/our-api
+.. _certbot-dns-cloudflare: https://certbot-dns-cloudflare.readthedocs.io/en/latest/
+
+
+Installation
+------------
+
+Since this package acts as a plugin for certbot_, the installation method can
+vary depending on how certbot is installed.
+
+pip
+~~~
+
+If certbot is installed normally as a python package, the plugin can be
+installed using::
+
+    pip install certbot-dns-netcup
+
+snap
+~~~~
+
+If certbot is installed as a snap, you'll have to install this plugin as
+follows::
+
+    sudo snap install certbot-dns-netcup
+
+Furthermore, the following seems to be required in order to connect the plugin
+to certbot::
+
+    sudo snap set certbot trust-plugin-with-root=ok
+    sudo snap connect certbot:plugin certbot-dns-netcup
+
+docker
+~~~~~~
+
+The official docker image of this repository is available from
+`docker.io/coldfix/certbot-dns-netcup`_ or
+`ghcr.io/coldfix/certbot-dns-netcup`_.
+
+Accordingly, you can pull the image as follows::
+
+    docker pull docker.io/coldfix/certbot-dns-netcup
+
+or::
+
+    docker pull ghcr.io/coldfix/certbot-dns-netcup
+
+.. _docker.io/coldfix/certbot-dns-netcup: https://hub.docker.com/repository/docker/coldfix/certbot-dns-netcup-testing/general
+.. _ghcr.io/coldfix/certbot-dns-netcup: https://github.com/coldfix/certbot-dns-netcup/pkgs/container/certbot-dns-netcup
+
+Usage
+-----
+
+To acquire a single certificate for both ``example.com`` and
+``*.example.com``, waiting 1200 seconds (20min) for DNS propagation::
+
+    certbot certonly \\
+      --authenticator dns-netcup \\
+      --dns-netcup-credentials ~/.secrets/certbot/netcup.ini \\
+      --dns-netcup-propagation-seconds 1200 \\
+      --keep-until-expiring --non-interactive --expand \
+      --server https://acme-v02.api.letsencrypt.org/directory \
+      -d 'example.com' \\
+      -d '*.example.com'
+
+The parameters and the format of the credentials file are described below.
+
+
+Named Arguments
+---------------
+
+To start using DNS authentication for netcup, pass the following arguments on
+certbot's command line:
+
+======================================== =======================
+``--authenticator dns-netcup``           select the authenticator
+                                         plugin (Required)
+
+``--dns-netcup-credentials FILE``        netcup credentials_
+                                         INI file. (Required)
+
+``--dns-netcup-propagation-seconds NUM`` | waiting time for DNS to propagate before asking
+                                         | the ACME server to verify the DNS record.
+                                         | (Default: 900, Recommended: >= 600)
+
+``--dns-netcup-login-retries NUM``       | Number of login retry attempts in case the
+                                         | netcup API client session times out.
+                                         | (Default: 3, Recommended: >= 1)
+
+``--dns-netcup-zone-name DOMAIN``        | Zone name to operate on (often second-level-domain).
+                                         | Will be determined using brute-force
+                                         | requests if not specified.
+======================================== =======================
+
+**NOTE:**
+You may need to set an unexpectedly high propagation time (≥ 900 seconds) to
+give the netcup DNS time to propagate the entries! This may be annoying when
+calling certbot manually but should not be a problem in automated setups.
+In exceptional cases, 20 minutes may be required. See `#28`_.
+
+.. _#28: https://github.com/coldfix/certbot-dns-netcup/issues/28
+
+
+Credentials
+-----------
+
+Use of this plugin requires a configuration file containing netcup API
+credentials, obtained from your netcup `account page`_. See also the `CCP
+API`_ documentation.
+
+.. _account page: https://ccp.netcup.net/run/daten_aendern.php?sprung=api
+
+An example ``credentials.ini`` file:
+
+.. code-block:: ini
+
+   dns_netcup_customer_id  = 123456
+   dns_netcup_api_key      = 0123456789abcdef0123456789abcdef01234567
+   dns_netcup_api_password = abcdef0123456789abcdef01234567abcdef0123
+
+The path to this file can be provided interactively or using the
+``--dns-netcup-credentials`` command-line argument. Certbot
+records the path to this file for use during renewal, but does not store the
+file's contents.
+
+**CAUTION:** You should protect these API credentials as you would the
+password to your netcup account. Users who can read this file can use these
+credentials to issue arbitrary API calls on your behalf. Users who can cause
+Certbot to run using these credentials can complete a ``dns-01`` challenge to
+acquire new certificates or revoke existing certificates for associated
+domains, even if those domains aren't being managed by this server.
+
+Certbot will emit a warning if it detects that the credentials file can be
+accessed by other users on your system. The warning reads "Unsafe permissions
+on credentials configuration file", followed by the path to the credentials
+file. This warning will be emitted each time Certbot uses the credentials file,
+including for renewal, and cannot be silenced except by addressing the issue
+(e.g., by using a command like ``chmod 600`` to restrict access to the file).
+
+
+Docker
+------
+
+You can pull the latest version of the docker image directly from Docker Hub
+as follows::
+
+    docker pull coldfix/certbot-dns-netcup
+
+Alternatively, the docker image can be built from a local checkout and the
+included ``Dockerfile`` as follows::
+
+    docker build -t coldfix/certbot-dns-netcup .
+
+Once that's finished, the application can be run as follows::
+
+    docker run --rm \
+      -v /var/lib/letsencrypt:/var/lib/letsencrypt \
+      -v /etc/letsencrypt:/etc/letsencrypt \
+      --cap-drop=all \
+      coldfix/certbot-dns-netcup certbot certonly \
+        --authenticator dns-netcup \
+        --dns-netcup-propagation-seconds 900 \
+        --dns-netcup-credentials /var/lib/letsencrypt/netcup_credentials.ini \
+        --keep-until-expiring --non-interactive --expand \
+        --server https://acme-v02.api.letsencrypt.org/directory \
+        --agree-tos --email "webmaster@example.com" \
+        -d example.com -d '*.example.com'
+
+You may want to change the volumes ``/var/lib/letsencrypt`` and
+``/etc/letsencrypt`` to local directories where the certificates and
+configuration should be stored.
+
+
+.. Badges:
+
+.. |Version| image::   https://img.shields.io/pypi/v/certbot-dns-netcup.svg
+   :target:            https://pypi.python.org/pypi/certbot-dns-netcup
+   :alt:               Version
+
+.. |License| image::   https://img.shields.io/pypi/l/certbot-dns-netcup.svg
+   :target:            https://github.com/coldfix/certbot-dns-netcup/blob/master/LICENSE.txt
+   :alt:               License: Apache
+
+.. |ImageSize| image:: https://img.shields.io/docker/image-size/coldfix/certbot-dns-netcup
+   :target:            https://hub.docker.com/repository/docker/coldfix/certbot-dns-netcup
+   :alt:               Docker image size

certbot_dns_netcup-2.0.2.dist-info/RECORD

@@ -0,0 +1,7 @@
+certbot_dns_netcup.py,sha256=Oi2Mijy-zin_otguy6AmL4pLk0s4qqir3Ox-E_amdjc,9819
+certbot_dns_netcup-2.0.2.dist-info/licenses/LICENSE.txt,sha256=LMXecVrlqXbwhvukkwiAyeQhkUFz_IURG_9RTUdXEj8,10786
+certbot_dns_netcup-2.0.2.dist-info/METADATA,sha256=TMPKTDN8BM1X_XDRIR9EY6tQBnxwDm6VK-J-Db323gU,8416
+certbot_dns_netcup-2.0.2.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+certbot_dns_netcup-2.0.2.dist-info/entry_points.txt,sha256=IehCRjN03ty7slp0M2AZZds-lreWMooFiKADMRe6Cpw,64
+certbot_dns_netcup-2.0.2.dist-info/top_level.txt,sha256=qRnyOkExBSkekrVie6ME3KVbQgT_gLYJxYj9Vl2xegg,19
+certbot_dns_netcup-2.0.2.dist-info/RECORD,,

certbot_dns_netcup-2.0.2.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

certbot_dns_netcup-2.0.2.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[certbot.plugins]
+dns-netcup = certbot_dns_netcup:Authenticator

certbot_dns_netcup-2.0.2.dist-info/licenses/LICENSE.txt

@@ -0,0 +1,190 @@
+   Copyright 2015 Electronic Frontier Foundation and others
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS

certbot_dns_netcup-2.0.2.dist-info/top_level.txt

@@ -0,0 +1 @@
+certbot_dns_netcup

certbot_dns_netcup.py

@@ -0,0 +1,278 @@
+"""
+This module defines a certbot plugin to automate the process of completing a
+``dns-01`` challenge (`~acme.challenges.DNS01`) by creating, and subsequently
+removing, TXT records using the netcup CCP API.
+"""
+
+# Keep metadata before any imports (for setup.py)!
+__version__ = '2.0.2'
+__url__     = 'https://github.com/coldfix/certbot-dns-netcup'
+__all__     = ['Authenticator']
+
+import json
+import logging
+import requests
+
+from certbot.plugins import dns_common
+from certbot.errors import PluginError
+
+
+API_URL = 'https://www.netcup-wiki.de/wiki/CCP_API'
+API_ENDPOINT = "https://ccp.netcup.net/run/webservice/servers/endpoint.php?JSON"
+
+LOGGER = logging.getLogger(__name__)
+
+
+class Authenticator(dns_common.DNSAuthenticator):
+    """DNS Authenticator for netcup
+
+    This Authenticator uses the netcup API to fulfill a dns-01 challenge.
+    """
+
+    description = ('Obtain certificates using a DNS TXT record (if you are '
+                   'using netcup for DNS).')
+
+    def __init__(self, *args, **kwargs):
+        super(Authenticator, self).__init__(*args, **kwargs)
+        self.credentials = None
+        self.api_session_id = None
+
+    # DNSAuthenticator overrides
+
+    @classmethod
+    def add_parser_arguments(cls, add):
+        super().add_parser_arguments(add, default_propagation_seconds=900)
+        add('credentials', help='netcup credentials INI file.')
+        add('login-retries', default=3, type=int,
+            help="login retry attempts in case of session timeout")
+        add('zone-name', help=(
+            "zone name to operate on (often second-level-domain). "
+            "Will be determined using brute-force requests if not specified."))
+
+    def more_info(self):
+        return ('This plugin configures a DNS TXT record to respond to a '
+                'dns-01 challenge using the netcup API.')
+
+    def _setup_credentials(self):
+        self.credentials = self._configure_credentials(
+            'credentials',
+            'netcup credentials INI file',
+            {
+                'customer-id':  'Customer ID associated with netcup account',
+                'api-key':      'Key for CCP API, see {}'.format(API_URL),
+                'api-password': 'Password for CCP API, see {}'.format(API_URL),
+            }
+        )
+
+    def _perform(self, domain, validation_name, validation):
+        LOGGER.debug("add_dns_record (%s, %s)", domain, validation_name)
+        client = self._get_netcup_client()
+        self._determine_zone(domain, lambda domain: (
+            client.add_dns_record(domain, validation_name, validation)))
+
+    def _cleanup(self, domain, validation_name, validation):
+        LOGGER.debug("delete_dns_record(%s, %s)", domain, validation_name)
+        client = self._get_netcup_client()
+        self._determine_zone(domain, lambda domain: (
+            client.delete_dns_record(domain, validation_name, validation)))
+
+    def _determine_zone(self, domain, func):
+        """Find the domain_id for a given domain."""
+        zone_name = self.conf('zone-name')
+        if zone_name:
+            return func(zone_name)
+
+        domain_name_guesses = dns_common.base_domain_name_guesses(domain)
+
+        for domain_name in domain_name_guesses:
+            try:
+                return func(domain_name)
+            except NetcupZoneError:
+                pass
+
+        raise PluginError(
+            'Unable to determine zone identifier for {0} using zone names: {1}'
+            .format(domain, domain_name_guesses))
+
+    def _get_netcup_client(self):
+        credentials = self.credentials.conf
+        return APIClient(
+            credentials('customer-id'),
+            credentials('api-key'),
+            credentials('api-password'),
+            self.conf('login-retries'))
+
+
+class APIClient:
+
+    def __init__(self, customer_id, api_key, api_password, login_retries):
+        self._customer_id = customer_id
+        self._api_key = api_key
+        self._api_password = api_password
+        self._api_session_id = None
+        self._login_retries = login_retries
+        if login_retries < 0:
+            raise PluginError((
+                "Invalid value for --dns-netcup-login-retries: {}. "
+                "Must be >= 0."
+            ).format(login_retries))
+
+    # public interface
+
+    def add_dns_record(self, domain, name, content):
+        """Create record."""
+        record = _make_record(domain, name, content)
+        self._update_records(domain, [record])
+
+    def delete_dns_record(self, domain, name, content):
+        """Delete an existing record. If record does not exist, do nothing."""
+        # Note that id/type/hostname/destination are all mandatory when
+        # deleting. We must query first to retrieve the record id.
+        record = _make_record(domain, name, content)
+        queried_records = self._query_records(domain, record)
+        self._update_records(domain, [
+            dict(record_with_id, deleterecord=True)
+            for record_with_id in queried_records
+        ])
+
+    # internal helpers
+
+    def _query_records(self, domain, record):
+        """Query list of record using netcup API."""
+        responsedata = self._authenticate_and_call(
+            "infoDnsRecords",
+            domainname=domain)
+        dnsrecords = responsedata.get("dnsrecords", [])
+        return [
+            retrieved_record
+            for retrieved_record in dnsrecords
+            if all(retrieved_record[k] == record[k] for k in record)
+        ]
+
+    def _update_records(self, domain, records):
+        """Insert or update a list of DNS records.
+
+        The fields ``hostname``, ``type``, and ``destination`` are mandatory.
+        The field ``id`` is mandatory when ``deleterecord=True``
+        """
+        return self._authenticate_and_call(
+            "updateDnsRecords",
+            domainname=domain,
+            dnsrecordset={"dnsrecords": records})
+
+    def _authenticate(self, force=False):
+        """Authenticate with netcup server. Must be called first."""
+
+        if force or not self._api_session_id:
+            responsedata = _apicall("login", {
+                "customernumber": self._customer_id,
+                "apikey": self._api_key,
+                "apipassword": self._api_password,
+            })
+
+            self._api_session_id = responsedata.get("apisessionid")
+            if not self._api_session_id:
+                raise PluginError("Login failed due to unknown reason.")
+
+        return {
+            "customernumber": self._customer_id,
+            "apikey": self._api_key,
+            "apisessionid": self._api_session_id,
+        }
+
+    def _authenticate_and_call(self, action, domainname, **param):
+        """Authenticate and then perform API call.
+        Auto retry login if session timed out."""
+        param = dict(param, domainname=domainname)
+        session_auth = self._authenticate(False)
+
+        for i in range(self._login_retries):
+            try:
+                return _apicall(action, session_auth, **param)
+            except NetcupSessionTimeoutError:
+                LOGGER.warning(
+                    "Login session timed out during call %s for domain %s. "
+                    "Retrying login (attempt %d)",
+                    action, domainname, i + 1)
+                session_auth = self._authenticate(True)
+
+        return _apicall(action, session_auth, **param)
+
+
+def _make_record(domain, name, content):
+    name = name.removesuffix('.' + domain)
+    return {
+        "type": "TXT",
+        "hostname": name,
+        "destination": content,
+    }
+
+
+def _apicall(action, credentials, **param):
+    """Call an API method and return response data. For more info, see:
+    https://ccp.netcup.net/run/webservice/servers/endpoint"""
+
+    LOGGER.debug("_apicall: %s(%s)", action, param.get('domainname', ''))
+
+    data = {
+        "action": action,
+        "param": dict(param, **credentials),
+    }
+    response = requests.post(
+        API_ENDPOINT,
+        data=json.dumps(data),
+        headers={
+            "Accept": "application/json",
+            "Content-Type": "application/json",
+        })
+    response.raise_for_status()
+    data = response.json()
+
+    status = data.get("status")
+    statuscode = data.get("statuscode")
+    shortmessage = data.get("shortmessage")
+    longmessage = data.get("longmessage")
+
+    if status == "success":     # statuscode == 2000
+        return data.get("responsedata", {})
+
+    # This happens when the domain is not chosen properly. Full message is:
+    # "Value in field domainname does not match requirements of type: domainname"
+    if 'Value in field domainname does not match requirements' in longmessage:
+        raise NetcupZoneError(
+            action, statuscode, shortmessage, longmessage)
+
+    # The session times out after roughly 30s and fails with this error:
+    if 'The session id is not in a valid format.' in longmessage:
+        raise NetcupSessionTimeoutError(
+            action, statuscode, shortmessage, longmessage)
+
+    # When something with the JSON format was incorrect, there is also:
+    # "Api key missing. JSON decode failed while validating request."
+
+    raise NetcupError(
+        action, statuscode, shortmessage, longmessage)
+
+
+class NetcupError(PluginError):
+
+    def __init__(self, action, statuscode, shortmessage, longmessage):
+        super().__init__(self._format(
+            action, statuscode, shortmessage, longmessage))
+        self.action = action
+        self.statuscode = statuscode
+        self.shortmessage = shortmessage
+        self.longmessage = longmessage
+
+    @classmethod
+    def _format(cls, action, statuscode, shortmessage, longmessage):
+        return (f'{cls.__name__} during {action}: '
+                f'{shortmessage} ({statuscode}) {longmessage}')
+
+
+class NetcupZoneError(NetcupError):
+    pass
+
+
+class NetcupSessionTimeoutError(NetcupError):
+    pass