Metadata-Version: 2.4
Name: gufo_acme
Version: 0.5.0
Summary: Python Automatic Certificate Management Environment (ACME) client
Author: Gufo Labs
License: BSD 3-Clause License
Project-URL: Bug Tracker, https://github.com/gufolabs/gufo_acme/issues
Project-URL: Changelog, https://github.com/gufolabs/gufo_acme/blob/master/CHANGELOG.md
Project-URL: Documentation, https://docs.gufolabs.com/gufp_acme/
Project-URL: Homepage, https://github.com/gufolabs/gufo_acme/
Project-URL: Source Code, https://github.com/gufolabs/gufo_acme/
Keywords: ACME,Automatic Certificate Management Environment,RFC8555
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
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: Programming Language :: Python :: 3.13
Classifier: License :: OSI Approved :: BSD License
Classifier: Topic :: Software Development
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Operating System :: OS Independent
Classifier: Typing :: Typed
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE.md
Requires-Dist: cryptography>=41
Requires-Dist: httpx[http2]>=0.25
Requires-Dist: josepy>=1.14
Provides-Extra: docs
Requires-Dist: mkdocs-material==9.5.44; extra == "docs"
Requires-Dist: mkdocstrings[python]==0.27.0; extra == "docs"
Requires-Dist: mkdocs-gen-files==0.5.0; extra == "docs"
Requires-Dist: mkdocs-literate-nav==0.6.1; extra == "docs"
Requires-Dist: mkdocs-section-index==0.3.9; extra == "docs"
Provides-Extra: ipython
Requires-Dist: ipython==8.0.1; extra == "ipython"
Provides-Extra: lint
Requires-Dist: mypy==1.13.0; extra == "lint"
Requires-Dist: ruff==0.11.2; extra == "lint"
Requires-Dist: types-PyYAML==6.0.12.3; extra == "lint"
Provides-Extra: test
Requires-Dist: pytest==8.3.3; extra == "test"
Requires-Dist: coverage[toml]==7.6.4; extra == "test"
Requires-Dist: PyYAML>=6.0; extra == "test"
Dynamic: license-file

# Gufo ACME

*Gufo ACME is a Python asyncio client for the ACME protocol.*

[![PyPi version](https://img.shields.io/pypi/v/gufo_acme.svg)](https://pypi.python.org/pypi/gufo_acme/)
![Downloads](https://img.shields.io/pypi/dw/gufo_acme)
![Python Versions](https://img.shields.io/pypi/pyversions/gufo_acme)
[![License](https://img.shields.io/badge/License-BSD_3--Clause-blue.svg)](https://opensource.org/licenses/BSD-3-Clause)
![Build](https://img.shields.io/github/actions/workflow/status/gufolabs/gufo_acme/py-tests.yml?branch=master)
![Sponsors](https://img.shields.io/github/sponsors/gufolabs)
[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/charliermarsh/ruff/main/assets/badge/v0.json)](https://github.com/charliermarsh/ruff)
---

**Documentation**: [https://docs.gufolabs.com/gufo_acme/](https://docs.gufolabs.com/gufo_acme/)

**Source Code**: [https://github.com/gufolabs/gufo_acme/](https://github.com/gufolabs/gufo_acme/)

---

The Automatic Certificate Management Environment (ACME) protocol defines a method
for automated certificate signing, now widely used by services
such as Let's Encrypt. Gufo ACME is a Python asyncio ACME client library that
simplifies the protocol complexity with a straightforward and robust API.

Gufo ACME contains various clients which can be applied to your tasks:

* AcmeClient - base client to implement any fulfillment functionality
    by creating subclasses.
* DavAcmeClient - http-01 fulfillment using WebDAV methods.
* PowerDnsAcmeClient - dns-01 PowerDNS fulfillment.
* WebAcmeClient - http-01 static file fulfillment.

## Supported Certificate Authorities

* [Letsencrypt](https://letsencrypt.org/)
* [ZeroSSL](https://zerossl.com/)
* Google Public CA
* Any [RFC-8555](https://tools.ietf.org/html/rfc8555) compatible CA.

## Examples

### Account Creation

Create an account and store state to the file.
``` python
client_key = AcmeClient.get_key()
async with AcmeClient(DIRECTORY, key=client_key) as client:
    await client.new_account(email)
    state = client.get_state()
with open(client_state_path, "wb") as fp:
    fp.write(state)
```

### Private Key Generation

To generate a private key in PEM format.
``` python
private_key = AcmeClient.get_domain_private_key()
```

### Generate CSR

To generate a certificate signing request.
``` python
csr = AcmeClient.get_domain_csr(domain, private_key)
```

### Sign Certificate

Sign the certificate using `http-01` challenge:

``` python
CHALLENGE_DIR = "/www/acme/"


class SignAcmeClient(AcmeClient):
    async def fulfill_http_01(
        self, domain: str, challenge: AcmeChallenge
    ) -> bool:
        v = self.get_key_authorization(challenge)
        with open(os.path.join(CHALLENGE_DIR, challenge.token), "wb") as fp:
            fp.write(v)
        return True

    async def clear_http_01(
        self: AcmeClient, domain: str, challenge: AcmeChallenge
    ) -> None:
        os.unlink(os.path.join(CHALLENGE_DIR, challenge.token))

    ...
async with SignAcmeClient.from_state(state) as client:
    cert = await client.sign(domain, csr)
```

## Features

* Pure-Python implementation.
* Asynchronous.
* Fully typed.
* Clean API.
* Built with security in mind.
* Robust well-tested code.
* Batteries included.
* 99%+ test coverage.

## On Gufo Stack

This product is a part of [Gufo Stack][Gufo Stack] - the collaborative effort 
led by [Gufo Labs][Gufo Labs]. Our goal is to create a robust and flexible 
set of tools to create network management software and automate 
routine administration tasks.

To do this, we extract the key technologies that have proven themselves 
in the [NOC][NOC] and bring them as separate packages. Then we work on API,
performance tuning, documentation, and testing. The [NOC][NOC] uses the final result
as the external dependencies.

[Gufo Stack][Gufo Stack] makes the [NOC][NOC] better, and this is our primary task. But other products
can benefit from [Gufo Stack][Gufo Stack] too. So we believe that our effort will make 
the other network management products better.

[Gufo Labs]: https://gufolabs.com/
[Gufo Stack]: https://docs.gufolabs.com/
[NOC]: https://getnoc.com/
