tiny-ca 0.2.0__tar.gz → 0.3.0__tar.gz

{tiny_ca-0.2.0 → tiny_ca-0.3.0}/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 Denys (Shchusia)
+Copyright (c) 2026 Denis Shchutskyi (Shchusia)
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

{tiny_ca-0.2.0/tiny_ca.egg-info → tiny_ca-0.3.0}/PKG-INFO

@@ -1,13 +1,13 @@
 Metadata-Version: 2.4
 Name: tiny-ca
-Version: 0.2.0
+Version: 0.3.0
 Summary: A lightweight, 100%-tested Python library for managing the full lifecycle of X.509 certificates — issuance, revocation, rotation, CRL generation, PKCS#12 export, and more.
 Author-email: Denis Shchutskyi <denisshchutskyi@gmail.com>
 License: MIT
 Project-URL: Repository, https://github.com/Shchusia/tiny_ca
 Project-URL: Documentation, https://shchusia.github.io/tiny_ca/
 Project-URL: Bug Tracker, https://github.com/Shchusia/tiny_ca/issues
-Project-URL: Changelog, https://github.com/Shchusia/tiny_ca/blob/main/CHANGELOG.md
+Project-URL: Changelog, https://github.com/Shchusia/tiny_ca/blob/master/CHANGELOG.md
 Keywords: pki,x509,certificate,ca,tls,ssl,cryptography,crl,pkcs12
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Programming Language :: Python :: 3
@@ -23,11 +23,9 @@ Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: cryptography>=46.0.0
 Requires-Dist: pydantic[email]>=2.12.0
-Requires-Dist: sqlalchemy>=2.0.0
+Requires-Dist: sqlalchemy[asyncio]>=2.0.0
 Provides-Extra: async
-Requires-Dist: aiofiles>=25.1.0; extra == "async"
 Requires-Dist: aiosqlite>=0.22.0; extra == "async"
-Requires-Dist: types-aiofiles>=25.1.0; extra == "async"
 Provides-Extra: postgres
 Requires-Dist: psycopg2-binary>=2.9.0; extra == "postgres"
 Provides-Extra: postgres-async
@@ -42,8 +40,9 @@ Dynamic: license-file
 
 # tiny_ca
 
-[![Python](https://img.shields.io/badge/Python-%3E%3D3.11-informational)](https://github.com/Shchusia/tiny_ca)
+[![Python](https://img.shields.io/pypi/pyversions/tiny-ca)](https://pypi.org/project/tiny-ca/)
 [![PyPI](https://img.shields.io/pypi/v/tiny-ca?color=blue)](https://pypi.org/project/tiny-ca/)
+
 [![Coverage Status](https://coveralls.io/repos/github/Shchusia/tiny_ca/badge.svg?branch=feature/docs)](https://coveralls.io/github/Shchusia/tiny_ca?branch=feature/docs)
 [![Docs](https://img.shields.io/badge/Docs-passing-green)](https://shchusia.github.io/tiny_ca/)
 [![License](https://img.shields.io/badge/License-MIT-blue)](LICENSE)
@@ -52,6 +51,43 @@ A lightweight, **100%-tested** Python library for managing the full lifecycle of
 
 ---
 
+## REST API
+
+> Looking for a ready-to-use HTTP server built on **tiny-ca**?
+> Check out **[tiny-ca-gateway](https://github.com/Shchusia/tiny-ca-gateway)** — a framework-agnostic REST API adapter that exposes all 22 certificate lifecycle endpoints with no extra code.
+
+| | |
+|---|---|
+| **GitHub** | [github.com/Shchusia/tiny-ca-gateway](https://github.com/Shchusia/tiny-ca-gateway) |
+| **Integration guide** | [tiny-ca-gateway/blob/master/README.md](https://github.com/Shchusia/tiny-ca-gateway/blob/master/README.md) |
+| **Supported frameworks** | FastAPI · Flask · aiohttp · Django Ninja |
+
+```bash
+pip install "tiny-ca-gateway[fastapi]"   # FastAPI + Uvicorn
+pip install "tiny-ca-gateway[flask]"     # Flask + Gunicorn
+pip install "tiny-ca-gateway[aiohttp]"   # aiohttp
+pip install "tiny-ca-gateway[django]"    # Django + Django Ninja
+```
+
+```python
+# FastAPI — all 22 CA endpoints in 5 lines
+from fastapi import FastAPI
+from contextlib import asynccontextmanager
+from tiny_ca_gateway.fastapi.lifespan.manager import FastAPILifespanManager
+from tiny_ca_gateway.fastapi.api.v1.ca_routes import router
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    await FastAPILifespanManager(common_name="My CA").on_startup()
+    yield
+
+app = FastAPI(lifespan=lifespan)
+app.include_router(router, prefix="/api/v1")
+# → Swagger UI at http://localhost:8000/docs
+```
+
+---
+
 ## Table of Contents
 
 - [Features](#features)
@@ -80,14 +116,16 @@ A lightweight, **100%-tested** Python library for managing the full lifecycle of
 |---|---|
 | **CA bootstrap** | Self-signed root CA and intermediate (sub) CA with configurable `path_length` |
 | **Issuance** | Leaf certificates with SANs (DNS + IP), EKU (Server/Client Auth), email attribute |
-| **Lifecycle** | Revoke (RFC 5280 reasons), renew (same key), rotate (new key), hard-delete |
-| **CRL** | Build, sign, and verify Certificate Revocation Lists with configurable validity |
+| **Key algorithms** | RSA (2048+), ECDSA P-256 / P-384, Ed25519 — for the CA and for leaves |
+| **Lifecycle** | Revoke (RFC 5280 reasons), renew (same key), rotate (new key), hard-delete — every CA-signed certificate is registered, so it can always be revoked |
+| **CRL** | RFC 5280 CRLs with `CRLNumber`, AKI and per-entry reason codes; optional CRL Distribution Points / AIA in issued certificates |
+| **Validation** | Direct (`validate_cert`) or through intermediates (`validate_chain`, with `BasicConstraints` / `pathLen` checks); registry check is fail-closed |
 | **Inspection** | Structured `CertificateDetails` snapshot from any `x509.Certificate` — fully serialisable |
 | **Export** | PKCS#12 (`.p12`/`.pfx`) bundles with full CA chain |
 | **Co-signing** | Re-sign third-party certificates under your CA, preserving Subject and extensions |
 | **Chain** | Build `[leaf, ca]` fullchain ready for nginx, Apache, or Envoy |
 | **Monitoring** | List certs with filters, find expiring-soon, bulk-expire stale records |
-| **Storage** | `LocalStorage` (sync) and `AsyncLocalStorage` (async, aiofiles) with UUID-based isolation |
+| **Storage** | `LocalStorage` (sync) and `AsyncLocalStorage` (async) with UUID-based isolation, `0600` private keys and path-traversal protection |
 | **Database** | `SyncDBHandler` (SQLAlchemy) and `AsyncDBHandler` (aiosqlite) — SQLite, PostgreSQL, MySQL |
 | **API parity** | `CertLifecycleManager` and `AsyncCertLifecycleManager` are feature-identical |
 | **Serial numbers** | `SerialWithEncoding` — 160-bit RFC 5280-compliant, type-prefixed, name-encoded |
@@ -99,7 +137,7 @@ A lightweight, **100%-tested** Python library for managing the full lifecycle of
 
 - **Python** 3.11 or higher
 - **Core:** `cryptography >= 46`, `sqlalchemy >= 2`, `pydantic >= 2`
-- **Async extras:** `aiofiles`, `aiosqlite`
+- **Async extras:** `aiosqlite`
 - **PostgreSQL:** `psycopg2-binary` (sync) / `asyncpg` (async)
 - **MySQL:** `pymysql` (sync) / `aiomysql` (async)
 
@@ -120,7 +158,7 @@ CertLifecycleManager / AsyncCertLifecycleManager   ← application entry-point
         │
         ├── BaseStorage (ABC)
         │       ├── LocalStorage                    ← sync filesystem (UUID-isolated)
-        │       └── AsyncLocalStorage               ← async filesystem (aiofiles)
+        │       └── AsyncLocalStorage               ← async filesystem (worker threads)
         │
         └── BaseDB (ABC)
                 ├── SyncDBHandler                   ← SQLAlchemy sync
@@ -164,7 +202,13 @@ from tiny_ca.storage.local_storage import LocalStorage
 from tiny_ca.db.sync_db_manager import SyncDBHandler
 from tiny_ca.models.certificate import CAConfig
 
-storage = LocalStorage(base_folder="./pki")
+from cryptography.hazmat.primitives.serialization import BestAvailableEncryption
+
+# Private keys are always written with mode 0600; encrypt them at rest too.
+storage = LocalStorage(
+    base_folder="./pki",
+    base_encryption_algorithm=BestAvailableEncryption(b"key-passphrase"),
+)
 db = SyncDBHandler(db_url="sqlite:///pki.db")
 mgr = CertLifecycleManager(storage=storage, db_handler=db)
 
@@ -180,10 +224,19 @@ Attach the factory so the manager can issue certificates:
 from tiny_ca.ca_factory.utils.file_loader import CAFileLoader
 from tiny_ca.ca_factory.factory import CertificateFactory
 
-loader = CAFileLoader(ca_cert_path=cert_path, ca_key_path=key_path)
-mgr.factory = CertificateFactory(loader)
+loader = CAFileLoader(ca_cert_path=cert_path, ca_key_path=key_path,
+                      ca_key_password=b"key-passphrase")
+mgr.factory = CertificateFactory(
+    loader,
+    # Optional: tell relying parties where to find the CRL / CA certificate.
+    crl_distribution_points=["http://pki.example/crl.pem"],
+    ca_issuers_urls=["http://pki.example/ca.pem"],
+)
 ```
 
+`CAConfig` / `ClientConfig` accept `key_algorithm=KeyAlgorithm.EC_P256`
+(also `EC_P384`, `ED25519`, default `RSA`) — see [Configuration Models](#configuration-models).
+
 ### 2. Issue a Leaf Certificate
 
 ```python
@@ -207,7 +260,9 @@ cert, key, csr = mgr.issue_certificate(
 ### 3. Renew a Certificate (same key)
 
 Keeps the existing public key — only validity window and serial number change.
-Use when the key has **not** been compromised.
+Use when the key has **not** been compromised.  The renewed certificate is
+stored and registered (so it can be revoked); the original is revoked with
+reason `superseded`.  The private key stays in the original folder.
 
 ```python
 renewed = mgr.renew_certificate(serial=cert.serial_number, days_valid=365)
@@ -215,7 +270,9 @@ renewed = mgr.renew_certificate(serial=cert.serial_number, days_valid=365)
 
 ### 4. Rotate a Certificate (new key)
 
-Atomically revokes the old cert and issues a replacement with a fresh key pair.
+Issues a replacement with a fresh key pair, then revokes the old cert
+(`superseded`).  If the old cert cannot be revoked, the replacement is rolled
+back and `CertRevocationError` is raised.
 
 ```python
 new_cert, new_key, new_csr = mgr.rotate_certificate(
@@ -240,6 +297,10 @@ crl = mgr.generate_crl(days_valid=7)   # written to <base_folder>/crl.pem
 mgr.verify_crl(crl)                     # raises ValidationCertError on failure
 ```
 
+Revoked certificates stay on the CRL until they expire.  If the database
+cannot be read, `generate_crl` raises `DBOperationError` and the previous
+`crl.pem` is left untouched — an empty CRL is never published.
+
 ### 7. Issue an Intermediate CA
 
 ```python
@@ -248,6 +309,10 @@ sub_ca_cert, sub_ca_key = mgr.issue_intermediate_ca(
     path_length=0, organization="ACME Corp", country="UA",
     cert_path="intermediate",
 )
+
+# The intermediate is registered (revocable via the root's CRL).  Verify a
+# leaf issued by it through the chain:
+mgr.verify_certificate(leaf_cert, intermediates=[sub_ca_cert])
 ```
 
 ### 8. Export PKCS#12
@@ -265,6 +330,7 @@ with open("nginx.p12", "wb") as f:
 from cryptography import x509
 third_party = x509.load_pem_x509_certificate(open("partner.pem", "rb").read())
 cosigned = mgr.cosign_certificate(cert=third_party, days_valid=365)
+# stored + registered like any other certificate issued by this CA
 ```
 
 ### 10. Inspect a Certificate
@@ -349,7 +415,8 @@ python examples/acomplete_example.py
 | `common_name` | `str` | `"Internal CA"` | CA Common Name (CN) |
 | `organization` | `str` | `"My Company"` | Organization (O) |
 | `country` | `str` | `"UA"` | Two-letter ISO 3166-1 alpha-2 code |
-| `key_size` | `int` | `2048` | RSA key length in bits |
+| `key_size` | `int` | `2048` | RSA key length in bits (≥ 2048; ignored for EC / Ed25519) |
+| `key_algorithm` | `KeyAlgorithm` | `RSA` | `RSA`, `EC_P256`, `EC_P384` or `ED25519` |
 | `days_valid` | `int` | `3650` | Validity period in days |
 | `valid_from` | `datetime \| None` | `None` | Explicit UTC start; `None` = now |
 
@@ -359,14 +426,15 @@ python examples/acomplete_example.py
 |---|---|---|---|
 | `common_name` | `str` | — | Certificate CN |
 | `serial_type` | `CertType` | `SERVICE` | Certificate category |
-| `key_size` | `int` | `2048` | RSA key length |
+| `key_size` | `int` | `2048` | RSA key length (≥ 2048; ignored for EC / Ed25519) |
+| `key_algorithm` | `KeyAlgorithm` | `RSA` | `RSA`, `EC_P256`, `EC_P384` or `ED25519` |
 | `days_valid` | `int` | `3650` | Validity period |
 | `email` | `EmailStr \| None` | `None` | `emailAddress` Subject attribute |
 | `is_server_cert` | `bool` | `True` | Adds ServerAuth EKU + CN as DNS SAN |
 | `is_client_cert` | `bool` | `False` | Adds ClientAuth EKU |
 | `san_dns` | `list[str] \| None` | `None` | Extra DNS Subject Alternative Names |
 | `san_ip` | `list[str] \| None` | `None` | IP address SANs |
-| `name` | `str \| None` | `None` | Override output file base name |
+| `name` | `str \| None` | `None` | Override output file base name (letters, digits, `.`, `-`, `_`; no leading dot) |
 
 ### `CertType`
 
@@ -393,14 +461,23 @@ storage = LocalStorage(base_folder="./pki")
 ./pki/
 └── [cert_path/]
     └── <uuid>/
-        ├── nginx.pem    ← x509.Certificate
-        ├── nginx.key    ← RSA private key
-        └── nginx.csr    ← CSR
+        ├── nginx.pem    ← x509.Certificate        (0644)
+        ├── nginx.key    ← private key             (0600)
+        └── nginx.csr    ← CSR                     (0644)
 ```
 
+- Private keys are written with mode `0600`.  They are **unencrypted unless**
+  `base_encryption_algorithm=BestAvailableEncryption(password)` is passed — a
+  warning is logged once per storage instance otherwise.
+- `file_name`, `cert_path` and `uuid_str` are validated: absolute paths, `..`
+  segments and backslashes raise `InvalidPathError`.
+- Without `is_overwrite=True` files are created with `O_EXCL`, so an existing
+  file is never replaced.
+
 ### `AsyncLocalStorage` (async)
 
-Drop-in async replacement — same constructor, same layout, all I/O via `aiofiles`.
+Drop-in async replacement — same constructor, same layout and the same
+security properties; blocking I/O runs in worker threads.
 
 ---
 
@@ -431,6 +508,13 @@ await db._db.init_db()
 | `delete_by_uuid(uuid)` | Hard-delete a record |
 | `update_status_expired()` | Bulk-mark stale VALID records as EXPIRED |
 
+Read methods (and `update_status_expired`) raise `DBOperationError` on any
+database failure instead of returning `None` / an empty list — a CA must fail
+closed.  `register_cert_in_db` returns `False` on failure; the managers turn
+that into `DBOperationError` and remove the artefacts they wrote.  Datetimes
+are stored as naive UTC (`DateTime` columns without time zone), which keeps
+PostgreSQL / asyncpg happy.
+
 ---
 
 ## Serial Number Encoding
@@ -440,7 +524,7 @@ await db._db.init_db()
 ```
 ┌──────────────┬──────────────────────┬────────────────────┐
 │  16-bit type │  80-bit name         │  64-bit random     │
-│  prefix      │  (up to 10 chars)    │  (UUID fragment)   │
+│  prefix      │  (up to 10 chars)    │  (secrets.randbits)│
 └──────────────┴──────────────────────┴────────────────────┘
 ```
 
@@ -453,6 +537,10 @@ cert_type, name = SerialWithEncoding.parse(serial)
 # cert_type == CertType.SERVICE, name == "nginx"
 ```
 
+Non-ASCII characters are stored as `?`, so a Cyrillic CN can never overflow
+into the type prefix.  The top bit is always zero, so the DER encoding fits the
+20-octet limit of RFC 5280.
+
 ---
 
 ## Error Reference
@@ -469,6 +557,9 @@ cert_type, name = SerialWithEncoding.parse(serial)
 | `IsNotFile` | CA PEM path is a directory | Provide a file, not a directory |
 | `WrongType` | Unsupported file extension | Use `.pem`, `.key`, or `.csr` |
 | `ErrorLoadCert` | PEM deserialisation failed | Check file format and integrity |
+| `DBOperationError` | Registry could not be read / written | Check the database; nothing was trusted or published |
+| `CertRevocationError` | Rotation/renewal could not revoke the old cert | Retry; the replacement was rolled back |
+| `InvalidPathError` | Storage path would escape `base_folder` | Use plain names / relative sub-paths |
 
 ---
 
@@ -478,7 +569,16 @@ cert_type, name = SerialWithEncoding.parse(serial)
 Yes — load it with `CAFileLoader` or `AsyncCAFileLoader`.
 
 **What's the difference between `renew` and `rotate`?**
-`renew` keeps the key pair and extends validity. `rotate` generates a new key and revokes the old cert.
+`renew` keeps the key pair and extends validity. `rotate` generates a new key. Both revoke the old cert with reason `superseded`.
+
+**Why does `verify_certificate` reject a certificate signed by my CA?**
+Since 0.3.0 a certificate issued directly by the CA must also be present in the
+registry — otherwise its revocation status is unknown.  Certificates created
+with older versions via `renew` / `cosign` were not registered; re-issue them.
+
+**How do I see the library's logs?**
+`tiny_ca` only attaches a `NullHandler`; configure the `"TinyCA"` logger in your
+application, e.g. `logging.getLogger("TinyCA").setLevel(logging.INFO)`.
 
 **How do I schedule CRL regeneration?**
 Use APScheduler or any cron solution:
@@ -586,4 +686,3 @@ Do **not** open public issues for security vulnerabilities. Email the maintainer
 | SQLAlchemy | MIT |
 | Pydantic | MIT |
 | aiosqlite | MIT |
-| aiofiles | Apache 2.0 |

{tiny_ca-0.2.0 → tiny_ca-0.3.0}/README.md

@@ -1,7 +1,8 @@
 # tiny_ca
 
-[![Python](https://img.shields.io/badge/Python-%3E%3D3.11-informational)](https://github.com/Shchusia/tiny_ca)
+[![Python](https://img.shields.io/pypi/pyversions/tiny-ca)](https://pypi.org/project/tiny-ca/)
 [![PyPI](https://img.shields.io/pypi/v/tiny-ca?color=blue)](https://pypi.org/project/tiny-ca/)
+
 [![Coverage Status](https://coveralls.io/repos/github/Shchusia/tiny_ca/badge.svg?branch=feature/docs)](https://coveralls.io/github/Shchusia/tiny_ca?branch=feature/docs)
 [![Docs](https://img.shields.io/badge/Docs-passing-green)](https://shchusia.github.io/tiny_ca/)
 [![License](https://img.shields.io/badge/License-MIT-blue)](LICENSE)
@@ -10,6 +11,43 @@ A lightweight, **100%-tested** Python library for managing the full lifecycle of
 
 ---
 
+## REST API
+
+> Looking for a ready-to-use HTTP server built on **tiny-ca**?
+> Check out **[tiny-ca-gateway](https://github.com/Shchusia/tiny-ca-gateway)** — a framework-agnostic REST API adapter that exposes all 22 certificate lifecycle endpoints with no extra code.
+
+| | |
+|---|---|
+| **GitHub** | [github.com/Shchusia/tiny-ca-gateway](https://github.com/Shchusia/tiny-ca-gateway) |
+| **Integration guide** | [tiny-ca-gateway/blob/master/README.md](https://github.com/Shchusia/tiny-ca-gateway/blob/master/README.md) |
+| **Supported frameworks** | FastAPI · Flask · aiohttp · Django Ninja |
+
+```bash
+pip install "tiny-ca-gateway[fastapi]"   # FastAPI + Uvicorn
+pip install "tiny-ca-gateway[flask]"     # Flask + Gunicorn
+pip install "tiny-ca-gateway[aiohttp]"   # aiohttp
+pip install "tiny-ca-gateway[django]"    # Django + Django Ninja
+```
+
+```python
+# FastAPI — all 22 CA endpoints in 5 lines
+from fastapi import FastAPI
+from contextlib import asynccontextmanager
+from tiny_ca_gateway.fastapi.lifespan.manager import FastAPILifespanManager
+from tiny_ca_gateway.fastapi.api.v1.ca_routes import router
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    await FastAPILifespanManager(common_name="My CA").on_startup()
+    yield
+
+app = FastAPI(lifespan=lifespan)
+app.include_router(router, prefix="/api/v1")
+# → Swagger UI at http://localhost:8000/docs
+```
+
+---
+
 ## Table of Contents
 
 - [Features](#features)
@@ -38,14 +76,16 @@ A lightweight, **100%-tested** Python library for managing the full lifecycle of
 |---|---|
 | **CA bootstrap** | Self-signed root CA and intermediate (sub) CA with configurable `path_length` |
 | **Issuance** | Leaf certificates with SANs (DNS + IP), EKU (Server/Client Auth), email attribute |
-| **Lifecycle** | Revoke (RFC 5280 reasons), renew (same key), rotate (new key), hard-delete |
-| **CRL** | Build, sign, and verify Certificate Revocation Lists with configurable validity |
+| **Key algorithms** | RSA (2048+), ECDSA P-256 / P-384, Ed25519 — for the CA and for leaves |
+| **Lifecycle** | Revoke (RFC 5280 reasons), renew (same key), rotate (new key), hard-delete — every CA-signed certificate is registered, so it can always be revoked |
+| **CRL** | RFC 5280 CRLs with `CRLNumber`, AKI and per-entry reason codes; optional CRL Distribution Points / AIA in issued certificates |
+| **Validation** | Direct (`validate_cert`) or through intermediates (`validate_chain`, with `BasicConstraints` / `pathLen` checks); registry check is fail-closed |
 | **Inspection** | Structured `CertificateDetails` snapshot from any `x509.Certificate` — fully serialisable |
 | **Export** | PKCS#12 (`.p12`/`.pfx`) bundles with full CA chain |
 | **Co-signing** | Re-sign third-party certificates under your CA, preserving Subject and extensions |
 | **Chain** | Build `[leaf, ca]` fullchain ready for nginx, Apache, or Envoy |
 | **Monitoring** | List certs with filters, find expiring-soon, bulk-expire stale records |
-| **Storage** | `LocalStorage` (sync) and `AsyncLocalStorage` (async, aiofiles) with UUID-based isolation |
+| **Storage** | `LocalStorage` (sync) and `AsyncLocalStorage` (async) with UUID-based isolation, `0600` private keys and path-traversal protection |
 | **Database** | `SyncDBHandler` (SQLAlchemy) and `AsyncDBHandler` (aiosqlite) — SQLite, PostgreSQL, MySQL |
 | **API parity** | `CertLifecycleManager` and `AsyncCertLifecycleManager` are feature-identical |
 | **Serial numbers** | `SerialWithEncoding` — 160-bit RFC 5280-compliant, type-prefixed, name-encoded |
@@ -57,7 +97,7 @@ A lightweight, **100%-tested** Python library for managing the full lifecycle of
 
 - **Python** 3.11 or higher
 - **Core:** `cryptography >= 46`, `sqlalchemy >= 2`, `pydantic >= 2`
-- **Async extras:** `aiofiles`, `aiosqlite`
+- **Async extras:** `aiosqlite`
 - **PostgreSQL:** `psycopg2-binary` (sync) / `asyncpg` (async)
 - **MySQL:** `pymysql` (sync) / `aiomysql` (async)
 
@@ -78,7 +118,7 @@ CertLifecycleManager / AsyncCertLifecycleManager   ← application entry-point
         │
         ├── BaseStorage (ABC)
         │       ├── LocalStorage                    ← sync filesystem (UUID-isolated)
-        │       └── AsyncLocalStorage               ← async filesystem (aiofiles)
+        │       └── AsyncLocalStorage               ← async filesystem (worker threads)
         │
         └── BaseDB (ABC)
                 ├── SyncDBHandler                   ← SQLAlchemy sync
@@ -122,7 +162,13 @@ from tiny_ca.storage.local_storage import LocalStorage
 from tiny_ca.db.sync_db_manager import SyncDBHandler
 from tiny_ca.models.certificate import CAConfig
 
-storage = LocalStorage(base_folder="./pki")
+from cryptography.hazmat.primitives.serialization import BestAvailableEncryption
+
+# Private keys are always written with mode 0600; encrypt them at rest too.
+storage = LocalStorage(
+    base_folder="./pki",
+    base_encryption_algorithm=BestAvailableEncryption(b"key-passphrase"),
+)
 db = SyncDBHandler(db_url="sqlite:///pki.db")
 mgr = CertLifecycleManager(storage=storage, db_handler=db)
 
@@ -138,10 +184,19 @@ Attach the factory so the manager can issue certificates:
 from tiny_ca.ca_factory.utils.file_loader import CAFileLoader
 from tiny_ca.ca_factory.factory import CertificateFactory
 
-loader = CAFileLoader(ca_cert_path=cert_path, ca_key_path=key_path)
-mgr.factory = CertificateFactory(loader)
+loader = CAFileLoader(ca_cert_path=cert_path, ca_key_path=key_path,
+                      ca_key_password=b"key-passphrase")
+mgr.factory = CertificateFactory(
+    loader,
+    # Optional: tell relying parties where to find the CRL / CA certificate.
+    crl_distribution_points=["http://pki.example/crl.pem"],
+    ca_issuers_urls=["http://pki.example/ca.pem"],
+)
 ```
 
+`CAConfig` / `ClientConfig` accept `key_algorithm=KeyAlgorithm.EC_P256`
+(also `EC_P384`, `ED25519`, default `RSA`) — see [Configuration Models](#configuration-models).
+
 ### 2. Issue a Leaf Certificate
 
 ```python
@@ -165,7 +220,9 @@ cert, key, csr = mgr.issue_certificate(
 ### 3. Renew a Certificate (same key)
 
 Keeps the existing public key — only validity window and serial number change.
-Use when the key has **not** been compromised.
+Use when the key has **not** been compromised.  The renewed certificate is
+stored and registered (so it can be revoked); the original is revoked with
+reason `superseded`.  The private key stays in the original folder.
 
 ```python
 renewed = mgr.renew_certificate(serial=cert.serial_number, days_valid=365)
@@ -173,7 +230,9 @@ renewed = mgr.renew_certificate(serial=cert.serial_number, days_valid=365)
 
 ### 4. Rotate a Certificate (new key)
 
-Atomically revokes the old cert and issues a replacement with a fresh key pair.
+Issues a replacement with a fresh key pair, then revokes the old cert
+(`superseded`).  If the old cert cannot be revoked, the replacement is rolled
+back and `CertRevocationError` is raised.
 
 ```python
 new_cert, new_key, new_csr = mgr.rotate_certificate(
@@ -198,6 +257,10 @@ crl = mgr.generate_crl(days_valid=7)   # written to <base_folder>/crl.pem
 mgr.verify_crl(crl)                     # raises ValidationCertError on failure
 ```
 
+Revoked certificates stay on the CRL until they expire.  If the database
+cannot be read, `generate_crl` raises `DBOperationError` and the previous
+`crl.pem` is left untouched — an empty CRL is never published.
+
 ### 7. Issue an Intermediate CA
 
 ```python
@@ -206,6 +269,10 @@ sub_ca_cert, sub_ca_key = mgr.issue_intermediate_ca(
     path_length=0, organization="ACME Corp", country="UA",
     cert_path="intermediate",
 )
+
+# The intermediate is registered (revocable via the root's CRL).  Verify a
+# leaf issued by it through the chain:
+mgr.verify_certificate(leaf_cert, intermediates=[sub_ca_cert])
 ```
 
 ### 8. Export PKCS#12
@@ -223,6 +290,7 @@ with open("nginx.p12", "wb") as f:
 from cryptography import x509
 third_party = x509.load_pem_x509_certificate(open("partner.pem", "rb").read())
 cosigned = mgr.cosign_certificate(cert=third_party, days_valid=365)
+# stored + registered like any other certificate issued by this CA
 ```
 
 ### 10. Inspect a Certificate
@@ -307,7 +375,8 @@ python examples/acomplete_example.py
 | `common_name` | `str` | `"Internal CA"` | CA Common Name (CN) |
 | `organization` | `str` | `"My Company"` | Organization (O) |
 | `country` | `str` | `"UA"` | Two-letter ISO 3166-1 alpha-2 code |
-| `key_size` | `int` | `2048` | RSA key length in bits |
+| `key_size` | `int` | `2048` | RSA key length in bits (≥ 2048; ignored for EC / Ed25519) |
+| `key_algorithm` | `KeyAlgorithm` | `RSA` | `RSA`, `EC_P256`, `EC_P384` or `ED25519` |
 | `days_valid` | `int` | `3650` | Validity period in days |
 | `valid_from` | `datetime \| None` | `None` | Explicit UTC start; `None` = now |
 
@@ -317,14 +386,15 @@ python examples/acomplete_example.py
 |---|---|---|---|
 | `common_name` | `str` | — | Certificate CN |
 | `serial_type` | `CertType` | `SERVICE` | Certificate category |
-| `key_size` | `int` | `2048` | RSA key length |
+| `key_size` | `int` | `2048` | RSA key length (≥ 2048; ignored for EC / Ed25519) |
+| `key_algorithm` | `KeyAlgorithm` | `RSA` | `RSA`, `EC_P256`, `EC_P384` or `ED25519` |
 | `days_valid` | `int` | `3650` | Validity period |
 | `email` | `EmailStr \| None` | `None` | `emailAddress` Subject attribute |
 | `is_server_cert` | `bool` | `True` | Adds ServerAuth EKU + CN as DNS SAN |
 | `is_client_cert` | `bool` | `False` | Adds ClientAuth EKU |
 | `san_dns` | `list[str] \| None` | `None` | Extra DNS Subject Alternative Names |
 | `san_ip` | `list[str] \| None` | `None` | IP address SANs |
-| `name` | `str \| None` | `None` | Override output file base name |
+| `name` | `str \| None` | `None` | Override output file base name (letters, digits, `.`, `-`, `_`; no leading dot) |
 
 ### `CertType`
 
@@ -351,14 +421,23 @@ storage = LocalStorage(base_folder="./pki")
 ./pki/
 └── [cert_path/]
     └── <uuid>/
-        ├── nginx.pem    ← x509.Certificate
-        ├── nginx.key    ← RSA private key
-        └── nginx.csr    ← CSR
+        ├── nginx.pem    ← x509.Certificate        (0644)
+        ├── nginx.key    ← private key             (0600)
+        └── nginx.csr    ← CSR                     (0644)
 ```
 
+- Private keys are written with mode `0600`.  They are **unencrypted unless**
+  `base_encryption_algorithm=BestAvailableEncryption(password)` is passed — a
+  warning is logged once per storage instance otherwise.
+- `file_name`, `cert_path` and `uuid_str` are validated: absolute paths, `..`
+  segments and backslashes raise `InvalidPathError`.
+- Without `is_overwrite=True` files are created with `O_EXCL`, so an existing
+  file is never replaced.
+
 ### `AsyncLocalStorage` (async)
 
-Drop-in async replacement — same constructor, same layout, all I/O via `aiofiles`.
+Drop-in async replacement — same constructor, same layout and the same
+security properties; blocking I/O runs in worker threads.
 
 ---
 
@@ -389,6 +468,13 @@ await db._db.init_db()
 | `delete_by_uuid(uuid)` | Hard-delete a record |
 | `update_status_expired()` | Bulk-mark stale VALID records as EXPIRED |
 
+Read methods (and `update_status_expired`) raise `DBOperationError` on any
+database failure instead of returning `None` / an empty list — a CA must fail
+closed.  `register_cert_in_db` returns `False` on failure; the managers turn
+that into `DBOperationError` and remove the artefacts they wrote.  Datetimes
+are stored as naive UTC (`DateTime` columns without time zone), which keeps
+PostgreSQL / asyncpg happy.
+
 ---
 
 ## Serial Number Encoding
@@ -398,7 +484,7 @@ await db._db.init_db()
 ```
 ┌──────────────┬──────────────────────┬────────────────────┐
 │  16-bit type │  80-bit name         │  64-bit random     │
-│  prefix      │  (up to 10 chars)    │  (UUID fragment)   │
+│  prefix      │  (up to 10 chars)    │  (secrets.randbits)│
 └──────────────┴──────────────────────┴────────────────────┘
 ```
 
@@ -411,6 +497,10 @@ cert_type, name = SerialWithEncoding.parse(serial)
 # cert_type == CertType.SERVICE, name == "nginx"
 ```
 
+Non-ASCII characters are stored as `?`, so a Cyrillic CN can never overflow
+into the type prefix.  The top bit is always zero, so the DER encoding fits the
+20-octet limit of RFC 5280.
+
 ---
 
 ## Error Reference
@@ -427,6 +517,9 @@ cert_type, name = SerialWithEncoding.parse(serial)
 | `IsNotFile` | CA PEM path is a directory | Provide a file, not a directory |
 | `WrongType` | Unsupported file extension | Use `.pem`, `.key`, or `.csr` |
 | `ErrorLoadCert` | PEM deserialisation failed | Check file format and integrity |
+| `DBOperationError` | Registry could not be read / written | Check the database; nothing was trusted or published |
+| `CertRevocationError` | Rotation/renewal could not revoke the old cert | Retry; the replacement was rolled back |
+| `InvalidPathError` | Storage path would escape `base_folder` | Use plain names / relative sub-paths |
 
 ---
 
@@ -436,7 +529,16 @@ cert_type, name = SerialWithEncoding.parse(serial)
 Yes — load it with `CAFileLoader` or `AsyncCAFileLoader`.
 
 **What's the difference between `renew` and `rotate`?**
-`renew` keeps the key pair and extends validity. `rotate` generates a new key and revokes the old cert.
+`renew` keeps the key pair and extends validity. `rotate` generates a new key. Both revoke the old cert with reason `superseded`.
+
+**Why does `verify_certificate` reject a certificate signed by my CA?**
+Since 0.3.0 a certificate issued directly by the CA must also be present in the
+registry — otherwise its revocation status is unknown.  Certificates created
+with older versions via `renew` / `cosign` were not registered; re-issue them.
+
+**How do I see the library's logs?**
+`tiny_ca` only attaches a `NullHandler`; configure the `"TinyCA"` logger in your
+application, e.g. `logging.getLogger("TinyCA").setLevel(logging.INFO)`.
 
 **How do I schedule CRL regeneration?**
 Use APScheduler or any cron solution:
@@ -544,4 +646,3 @@ Do **not** open public issues for security vulnerabilities. Email the maintainer
 | SQLAlchemy | MIT |
 | Pydantic | MIT |
 | aiosqlite | MIT |
-| aiofiles | Apache 2.0 |