Metadata-Version: 2.4
Name: certbot-dns-myracloud
Version: 0.2.2
Summary: Provide Myracloud DNS with Certbot for DNS-01 challenge type
Keywords: myracloud,certbot,myrasecurity,myra
Author: Myra Security
Author-email: Myra Security <noc@myrasecurity.com>
License-Expression: Apache-2.0
License-File: LICENSE
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Plugins
Classifier: Intended Audience :: System Administrators
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.4
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
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-Dist: certbot>=2.11.0
Requires-Dist: requests>=2.32.3
Requires-Python: >=3.8
Project-URL: Homepage, https://myrasecurity.com
Project-URL: Repository, https://github.com/Myra-Security-GmbH/certbot-dns-myracloud
Description-Content-Type: text/markdown

# Certbot DNS-Myracloud Authenticator Plugin

> **This GitHub repository is a read-only mirror.**
> Development happens internally at Myra Security. Issues and pull requests
> opened here are not monitored. To report a security vulnerability, please
> follow [SECURITY.md](SECURITY.md).

The Certbot DNS-Myracloud Authenticator Plugin facilitates the procurement of SSL/TLS certificates from Let's Encrypt
utilizing the DNS-01 challenge methodology in conjunction with Myracloud as the designated DNS service provider. This
document elucidates the procedural steps for the installation and operational utilization of this plugin.

The plugin talks to the Myracloud **v2 API** (`apiv2.myracloud.com`). The credentials' service account must have access
to the domain (zone) for which the certificate is requested; the plugin resolves the zone's numeric domain id and owning
organization automatically. The retired v1 API (`api.myracloud.com/en/rapi`) is no longer used.

## Installation

To initialize the Certbot DNS-Myracloud Authenticator Plugin, deploy the following pip command:

```bash
pip install certbot-dns-myracloud
```

## Plugin Usage

Upon successful integration of the plugin, it becomes viable to employ it with Certbot for the retrieval of SSL/TLS
certificates. The subsequent section delineates the pertinent arguments and their respective examples:

### Arguments

| Argument                              | Example Value     | Description                                                                                                                                                                            |
|---------------------------------------|-------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `--authenticator`                     | dns-myracloud     | Engages the Myracloud authenticator mechanism. This must be configured as dns-myracloud. (Mandatory)                                                                                   |
| `--dns-myracloud-credentials`         | ./credentials.ini | Denotes the directory path to the credentials file for Myracloud DNS. This document must encapsulate the dns_myracloud_auth_token and dns_myracloud_auth_secret variables. (Mandatory) |
| `--dns-myracloud-propagation-seconds` | 900               | Configures the delay prior to initiating the DNS record query. A 900-second interval (equivalent to 15 minutes) is recommended. (Default: 900)                                         |

### Example

Below is a structured example detailing the application of Certbot in conjunction with the DNS-Myracloud
Authenticator Plugin to retrieve a certificate:

```bash

# prepare environment
python3 -m venv e
. e/bin/activate

# install myracloud DNS authenticator
pip install certbot-dns-myracloud

# do not forget to have proper permissions set on your credentials.ini,
# like chmod 400 <path_to_credentials.ini>
# the auto

# retrieve cert
certbot certonly \
  --authenticator dns-myracloud \
  --dns-myracloud-credentials ./path_to_credentials.ini \
  --dns-myracloud-propagation-seconds 180 \
  --server https://acme-v02.api.letsencrypt.org/directory \
  --agree-tos \
  --elliptic-curve secp384r1 \
  --preferred-challenges dns \
  -d 'example.com' \
  -d '*.example.com'
```

For this example, example.com represents the designated domain (zone) for certificate procurement.

### Obtaining your credentials (API Key)

The plugin authenticates with the Myracloud v2 API using an **API Key**, which consists of a **token** (the key
identifier) and a **secret**. Create one in the Myra application under:

> **Personal Account → API Access → API Keys**

Add a new API Key there. When it is created you are shown the **token** and the **secret** — copy both immediately, as
the secret is only displayed once. The account that owns the API Key must have access to the domain (zone) for which you
request the certificate, with permission to create DNS records.

### Example of credentials.ini

To operationalize the plugin, it's imperative to curate a credentials.ini file encompassing your Myracloud DNS
credentials:

```ini
dns_myracloud_auth_token = "your_token_here"
dns_myracloud_auth_secret = "your_secret_here"
```

Replace `your_token_here` and `your_secret_here` with the **token** and **secret** of the API Key created above
(**Personal Account → API Access → API Keys**). The account that owns the API Key must have permission to create DNS
records in the target zone.
