Alibaba Cloud 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 Alibaba Cloud DNS
API.

.. note::
   This plugin utilizes the official Alibaba Cloud SDK (specifically
   ``alibabacloud_alidns20150109``) to interact with the DNS service.

Installation
------------

.. code-block:: bash

    pip install certbot-dns-alibabacloud

Named Arguments
---------------

==========================================  ==================================================
``--dns-alibabacloud-credentials``          Alibaba Cloud credentials_ INI file. (Required)
``--dns-alibabacloud-propagation-seconds``  The number of seconds to wait for DNS to propagate
                                            before asking the ACME server to verify the DNS
                                            record. (Default: 30)
==========================================  ==================================================

Credentials
-----------

You need to provide a credentials file containing your Alibaba Cloud
AccessKey to Certbot so that it can communicate with Alibaba Cloud and
complete the DNS-01 domain validation on your behalf. The Access Key can
be created through the Alibaba Cloud RAM (Resource Access Management)
console.

An example credentials file is shown below:

.. code-block:: ini

    # Alibaba Cloud API credentials used by Certbot
    dns_alibabacloud_access_key_id = LTAI5txxxxxxxxxxxxxxxxxx
    dns_alibabacloud_access_key_secret = yyyyyyyyyyyyyyyyyyyyyyyyyyyyyy

To manage the DNS records required for the challenge, the plugin first
needs to locate the corresponding managed domain in Alibaba Cloud DNS
for the requested certificate domain name.

The Access Key must have permission to list managed domains in Alibaba
Cloud DNS, create and delete DNS records, and query existing records for
challenge cleanup after the validation completes:

* ``alidns:DescribeDomains``
* ``alidns:AddDomainRecord``
* ``alidns:DeleteDomainRecord``
* ``alidns:DescribeDomainRecords``

Here is an example RAM policy that follows the Principle of Least
Privilege:


.. code-block:: json

    {
      "Version": "1",
      "Statement": [
        {
          "Effect": "Allow",
          "Action": "alidns:DescribeDomains",
          "Resource": "*"
        },
        {
          "Effect": "Allow",
          "Action": [
            "alidns:AddDomainRecord",
            "alidns:DeleteDomainRecord",
            "alidns:DescribeDomainRecords"
          ],
          "Resource": "acs:alidns:*:*:domain/YOUR-DOMAIN-NAME.COM"
        }
      ]
    }

.. caution::

    You should protect the credentials file as you would protect your
    passwords by setting restrictive file permissions (for example,
    ``chmod 600``), preventing other users or programs on the system
    from reading the sensitive file.

    Certbot will also warn you if the credentials file has overly
    permissive permissions.

    Leaked credentials could allow malicious users to manipulate your
    DNS records and issue certificates for domains under your control.

Examples
--------

To acquire a certificate for ``example.com``:

.. code-block:: bash

    certbot certonly \
      --authenticator dns-alibabacloud \
      --dns-alibabacloud-credentials ~/.secrets/certbot/alibabacloud.ini \
      -d example.com

To acquire a single certificate for both ``example.com`` and ``www.example.com``:

.. code-block:: bash

    certbot certonly \
      --authenticator dns-alibabacloud \
      --dns-alibabacloud-credentials ~/.secrets/certbot/alibabacloud.ini \
      -d example.com \
      -d www.example.com

To acquire a certificate for ``example.com``, waiting 60 seconds for DNS
propagation:

.. code-block:: bash

    certbot certonly \
      --authenticator dns-alibabacloud \
      --dns-alibabacloud-credentials ~/.secrets/certbot/alibabacloud.ini \
      --dns-alibabacloud-propagation-seconds 60 \
      -d example.com