Skip to content

Commit 7f4bae1

Browse files
mesudipmesudip
committed
Update Readme for CLI
1 parent d1c106a commit 7f4bae1

File tree

2 files changed

+105
-67
lines changed

2 files changed

+105
-67
lines changed

‎Developer.md‎

Lines changed: 82 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,82 @@
1+
Developer Guide
2+
==============
3+
4+
Using CertApi as a Library
5+
--------------------------
6+
7+
The library supports both low-level ACME operations and a higher-level manager that handles
8+
storage and renewals. Pick the approach that fits your integration needs.
9+
10+
1.  Low-Level API: Certificate with Cloudflare
11+
------------------------------------------
12+
13+
```python
14+
import json
15+
from certapi import CertApiException, CloudflareChallengeSolver, Key, AcmeCertIssuer
16+
17+
18+
# Initialize the Cloudflare challenge solver
19+
# The API key is read from the CLOUDFLARE_API_KEY environment variable, or you can set it below.
20+
challenge_solver = CloudflareChallengeSolver(api_key=None)
21+
22+
# Initialize cert issuer with a new account key
23+
cert_issuer = AcmeCertIssuer(Key.generate("ecdsa"), challenge_solver)
24+
25+
# Perform setup i.e. fetching directory and registering ACME account
26+
cert_issuer.setup()
27+
28+
try:
29+
# Obtain a certificate for your domain
30+
(key, cert) = cert_issuer.generate_key_and_cert_for_domain("your-domain.com")
31+
32+
print("------ Private Key -----")
33+
print(key.to_pem())
34+
print("------- Certificate ------")
35+
print(cert)
36+
except CertApiException as e:
37+
print("An error occurred:", json.dumps(e.json_obj(), indent=2))
38+
```
39+
40+
2.  High-Level API: AcmeCertManager
41+
-------------------------------
42+
43+
The `AcmeCertManager` provides a high-level interface that handles certificate storage,
44+
automatic renewal checks, and multi-solver management.
45+
46+
```python
47+
from certapi import (
48+
AcmeCertManager,
49+
FileSystemKeyStore,
50+
AcmeCertIssuer,
51+
CloudflareChallengeSolver,
52+
)
53+
54+
# 1. Setup KeyStore to persist keys and certificates
55+
key_store = FileSystemKeyStore("db")
56+
57+
58+
# DNS-01 via Cloudflare (e.g. for wildcard certs or internal domains)
59+
dns_solver = CloudflareChallengeSolver(api_token="your-cloudflare-token")
60+
61+
# 3. Initialize and Setup AcmeCertManager
62+
# Create cert issuer with the default challenge solver
63+
cert_issuer = AcmeCertIssuer.with_keystore(key_store, dns_solver)
64+
65+
cert_manager = AcmeCertManager(
66+
key_store=key_store,
67+
cert_issuer=cert_issuer,
68+
challenge_solvers=[dns_solver], # other solvers can be used
69+
)
70+
cert_manager.setup()
71+
72+
# 4. Issue or Reuse Certificate
73+
# Automatically checks and saves to keystore. Renews only if necessary.
74+
response = cert_manager.issue_certificate(["example.com", "www.example.com"])
75+
76+
for cert_data in response.issued:
77+
print(f"Newly issued for: {cert_data.domains}")
78+
print(cert_data.cert)
79+
80+
for cert_data in response.existing:
81+
print(f"Reusing existing for: {cert_data.domains}")
82+
```

‎README.md‎

Lines changed: 23 additions & 67 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,16 @@ CertApi is a base library for building other tools, or to integrate Certificate
99
[![codecov](https://codecov.io/github/mesudip/certapi/graph/badge.svg?token=NYTNCH29IT)](https://codecov.io/github/mesudip/certapi)
1010
[![PyPI version](https://img.shields.io/pypi/v/certapi.svg)](https://pypi.org/project/certapi/)
1111

12+
## Why another library?
13+
14+
I designed this library so that it can be imported and plugged in to other python projects. Goal is not to provide CLIs or quick working demo, but to be versatile for any use case.
15+
16+
- Pluggable keystores for keys and certificates
17+
- Pluggable Challenge solvers for DNS and Http challenge solving
18+
- High-level manager with renewal checks and multi-solver support
19+
- Same interface for working locally, or requesting certificate from certapi server.
20+
21+
See the developer guide in [Developer.md](Developer.md) for library usage and workflows.
1222

1323

1424
## Installation
@@ -19,75 +29,21 @@ You can install CertApi using pip
1929
pip install certapi
2030
```
2131

22-
## Example: Low Leve API : Certificate with Cloudflare
23-
24-
```python
25-
import json
26-
from certapi import CertApiException, CloudflareChallengeSolver, Key, AcmeCertIssuer
27-
28-
29-
# Initialize the Cloudflare challenge solver
30-
# The API key is read from the CLOUDFLARE_API_KEY environment variable, or you can set it below.
31-
challenge_solver = CloudflareChallengeSolver(api_key=None)
32+
## CLI
3233

33-
## initialize cert issuer with a new account key
34-
cert_issuer = AcmeCertIssuer(Key.generate('ecdsa'), challenge_solver)
35-
36-
# Preform setup i.e. fetching directory and registering ACME account
37-
cert_issuer.setup()
38-
39-
try:
40-
# Obtain a certificate for your domain
41-
(key, cert) = cert_issuer.generate_key_and_cert_for_domain("your-domain.com")
42-
43-
print("------ Private Key -----")
44-
print(key.to_pem())
45-
print("------- Certificate ------")
46-
print(cert)
47-
except CertApiException as e:
48-
print(f"An error occurred:", json.dumps(e.json_obj(), indent=2))
49-
50-
```
34+
CertApi also ships with a CLI for quick verification and certificate issuance.
5135

36+
```bash
37+
## Crtapi's dependencies are already included in the python installation. This doesn't affect the system.
38+
sudo python3 -m pip install certapi --break-system-packages
39+
40+
# Use Cloudflare DNS-01 by providing API key or token
41+
export CLOUDFLARE_API_KEY="..."
42+
sudo certapi obtain example.com
5243

53-
## Example: High Level API (with AcmeCertManager)
54-
55-
The `AcmeCertManager` provides a high-level interface that handles certificate storage, automatic renewal checks, and multi-solver management.
56-
57-
```python
58-
from certapi import (
59-
AcmeCertManager,
60-
FileSystemKeyStore,
61-
AcmeCertIssuer,
62-
CloudflareChallengeSolver
63-
)
64-
65-
# 1. Setup KeyStore to persist keys and certificates
66-
key_store = FileSystemKeyStore("db")
67-
68-
69-
# DNS-01 via Cloudflare (e.g. for wildcard certs or internal domains)
70-
dns_solver = CloudflareChallengeSolver(api_token="your-cloudflare-token")
71-
72-
# 3. Initialize and Setup AcmeCertManager
73-
# Create cert issuer with the default challenge solver
74-
cert_issuer = AcmeCertIssuer.with_keystore(key_store, dns_solver)
75-
76-
cert_manager = AcmeCertManager(
77-
key_store=key_store,
78-
cert_issuer=cert_issuer,
79-
challenge_solvers=[dns_solver], # other solvers can be used
80-
)
81-
cert_manager.setup()
82-
83-
# 4. Issue or Reuse Certificate
84-
# Automatically checks sand saves to keystore. Renews only if necessary.
85-
response = cert_manager.issue_certificate(["example.com", "www.example.com"])
8644

87-
for cert_data in response.issued:
88-
print(f"Newly issued for: {cert_data.domains}")
89-
print(cert_data.cert)
45+
# If you have already setup DNS.
46+
sudo certapi verify example.com # Check that the DNS is setup correctly
47+
sudo certapi obtain example.com
9048

91-
for cert_data in response.existing:
92-
print(f"Reusing existing for: {cert_data.domains}")
93-
```
49+
```

0 commit comments

Comments
 (0)