Metadata-Version: 2.1
Name: certbot-regfish-hooks
Version: 2.0.0b2
Summary: regfish pre and post validation hooks for certbot
Author-email: Maximilian Kaulmann <exioreed@ownlink.eu>
License: Copyright 2024 Maximilian Kaulmann
        
        Redistribution and use in source and binary forms, with or without modification, are
        permitted provided that the following conditions are met:
        
        1. Redistributions of source code must retain the above copyright notice, this list of
           conditions and the following disclaimer.
        
        2. Redistributions in binary form must reproduce the above copyright notice, this list
           of conditions and the following disclaimer in the documentation and/or other
           materials provided with the distribution.
        
        3. Neither the name of the copyright holder nor the names of its contributors may be
           used to endorse or promote products derived from this software without specific prior
           written permission.
        
        THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS “AS IS” AND ANY
        EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
        MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL
        THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
        SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT
        OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
        INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
        LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
        OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
        
Project-URL: GitHub, https://github.com/exioReed/certbot-regfish-hooks
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Plugins
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: BSD License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Internet :: Name Service (DNS)
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Security
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pydantic~=2.9.2
Requires-Dist: requests~=2.32.3

# Certbot Regfish DNS Hooks

**Overview:**

- [Installation](#installation)
- [Usage](#usage)
- [Status](#status)

Pre and post validation hooks for Certbot to automate DNS-01 challenges using the
Regfish DNS API.

## Installation

1. Install via pip:

   ```bash
   pip install certbot-regfish-hooks
   ```

   See also
   [certbot installation via pip](https://certbot.eff.org/instructions?ws=other&os=pip).

2. Set up the Regfish API key:

   ```bash
   $ echo "your-regfish-key" > /etc/letsencrypt/regfish-api-key.txt
   $ chmod 600 /etc/letsencrypt/regfish-api-key.txt
   ```

## Usage

These Regfish DNS hooks can be used with
[Certbot's manual plugin](https://eff-certbot.readthedocs.io/en/stable/using.html#manual)
by specifying `certonly` and `--manual` on the command line:

```bash
$ certbot \
  --manual \
  --manual-auth-hook 'certbot-regfish-auth-hook --regfish-api-key-file /etc/letsencrypt/regfish-api-key.txt' \
  --manual-cleanup-hook 'certbot-regfish-cleanup-hook --regfish-api-key-file /etc/letsencrypt/regfish-api-key.txt' \
  --preferred-challenges dns-01 \
  certonly \
  <your other options>
```

Alternatively, use a
[global configuration file](https://eff-certbot.readthedocs.io/en/stable/using.html#configuration-file)
to apply your options:

```bash
$ certbot --config /etc/letsencrypt/regfish-example.ini certonly
```

`/etc/letsencrypt/regfish-example.ini`:

```ini
# register
email = your.email@example.com
no-eff-email = true
agree-tos = true

# authenticator
manual = true
manual-auth-hook = 'certbot-regfish-auth-hook --regfish-api-key-file /etc/letsencrypt/regfish-api-key.txt'
manual-cleanup-hook = 'certbot-regfish-cleanup-hook --regfish-api-key-file /etc/letsencrypt/regfish-api-key.txt'

# domain settings
domains = test.example.com,*.test.example.com

# NOTE: remove test-cert to use Let's Encrypt production endpoints
test-cert = true
preferred-challenges = dns-01
user-agent = 'autocrt/2.0'

# use ECC
key-type = ecdsa
elliptic-curve = secp384r1
```

## Status

### This is still in beta. What's missing for production?

The auth hooks have been tested as described above and this project will be deployed
across two servers shortly. Let's be honest though - a bit homework remains before I'd
consider this ready for production:

- Pre-commit hooks for linting/formatting
- Automated dependency upgrades (Dependabot)
- Integration testing with a test domain
- Automated builds and releases to PyPI

### If that's version 2, where's version 1?

In fact, this project started six years ago as the very first Python module one of my
closest friends hacked together for educational purposes. Certbot wasn't able to handle
DNS challenges back then, so he came up with a hand-rolled ACME implementation and
screen scraping interface for Regfish. This tool, which has requested over 50
certificates for our purposes by now, is what we named _autocrt-dns_.

It's been rock-solid until the day Regfish changed their DNS pad for the better and
_finally_ added an API to their product in November 2024. This public repository is a
complete rewrite of our first version, leaning towards Certbot's now well-established
ACME implementation and focusing on DNS authorization. None of the initial code survived
but for sentimental reasons, it still identifies itself with the user-agent _autocrt_,
now in version 2.
