From 054e85d6da697bc0c37a3786e9ee2defb44b0f39 Mon Sep 17 00:00:00 2001 From: Remco Koopmans Date: Thu, 1 Aug 2024 18:25:20 +0200 Subject: [PATCH] Update docs --- README.md | 40 +++++++++++++++++++++--------------- cert_chain_resolver/api.py | 1 + docs/api.rst | 15 ++++++++++---- docs/cert_chain_resolver.rst | 13 ------------ 4 files changed, 36 insertions(+), 33 deletions(-) diff --git a/README.md b/README.md index 80be833..44b9f1d 100644 --- a/README.md +++ b/README.md @@ -11,13 +11,27 @@ Resolve / obtain the certificate intermediates and root of a x509 certificate using the CLI or python API. The CLI provides easy access to a certificate bundle and its metadata while the Python API can be used to inspect, iterate and complete certificate bundles. + +## Minimal shell + +Read more about the shell usage on [read the docs](https://certificate-resolver.readthedocs.io/en/latest/cli_usage.html) + +``` + $ cert_chain_resolver certificate.crt > bundle.crt + 1. + 2. + 3. +``` + +## Minimal python + +Read more regarding the python API on [read the docs](https://certificate-resolver.readthedocs.io/en/latest/api.html) ``` from cert_chain_resolver.api import resolve -from cert_chain_resolver.root.certifi import CertifiStore with open('cert.pem', 'rb') as f: fb = f.read() - chain = resolve(fb, include_root=True, root_ca_store=CertifiStore()) + chain = resolve(fb) >>> for cert in chain: print(cert) @@ -26,36 +40,26 @@ for cert in chain: ``` +## + ## Support * PKCS7, PEM and DER formats * LetsEncrypt certificates -* Resolving the root certificate through a CA Bundle +* Resolving the root certificate through an auto detected OR chosen CA bundle ## Dependencies * cryptography -## Documentation - -Read more on [readthedocs](https://certificate-resolver.readthedocs.io/en/latest/) - ## Install [Pypi](https://pypi.org/project/cert-chain-resolver/) - - Core package $ pip install cert-chain-resolver - -With certifi support for finding the matching root certificate - - $ pip install cert-chain-resolver[certifi] - - ## Usage ### Installed using PIP @@ -66,7 +70,11 @@ Resolve without helpers, just the leaf and intermediates: Resolve complete chain up to the root: - $ cert_chain_resolver certificate.crt --include-root --use-store-certifi > bundle.crt + $ cert_chain_resolver certificate.crt --include-root > bundle.crt + +Resolve complete chain with your own root bundle: + + $ cert_chain_resolver certificate.crt --include-root --ca-bundle-path /path/to/bundle.pem > bundle.crt Or read from stdin diff --git a/cert_chain_resolver/api.py b/cert_chain_resolver/api.py index 4cc3687..a8aabb0 100644 --- a/cert_chain_resolver/api.py +++ b/cert_chain_resolver/api.py @@ -1,2 +1,3 @@ from cert_chain_resolver.resolver import resolve from cert_chain_resolver.models import CertificateChain, Cert +from cert_chain_resolver.castore.file_system import FileSystemStore diff --git a/docs/api.rst b/docs/api.rst index 0a78a10..9e32a61 100644 --- a/docs/api.rst +++ b/docs/api.rst @@ -41,22 +41,29 @@ This will print each certificate in the chain, starting with the leaf and ending Advanced Usage ============== -Using the certifi CA Store for resolving root certs +Using the System CA Store or own bundle for resolving root certs --------------------------------------------------- -Not all intermediates provide a resolvable path, but we can create the path by matching it with our own CA bundle +Not all CA intermediates provide a web traversable path to the root certificate. Therefore we need to find the root ourselves if we want to have the complete chain of trust. .. code-block:: python - from cert_chain_resolver.api import resolve - from cert_chain_resolver.root.certifi import CertifiStore + from cert_chain_resolver.api import resolve, FileSystemStore # Load your certificate with open('cert.pem', 'rb') as f: file_bytes = f.read() + # Will try to find the root bundle on your systemm will raise if it cannot be found chain = resolve(file_bytes, root_ca_store=CertifiStore()) + # We override the path to the root certificate bundle + chain = resolve(file_bytes, root_ca_store=CertifiStore('/etc/cabundles/mine.pem')) + + # We leverage certifi for the root bundle + import certifi + chain = resolve(file_bytes, root_ca_store=CertifiStore(certifi.where())) + for cert in chain: print(cert) diff --git a/docs/cert_chain_resolver.rst b/docs/cert_chain_resolver.rst index 64f8c13..bc815d4 100644 --- a/docs/cert_chain_resolver.rst +++ b/docs/cert_chain_resolver.rst @@ -29,19 +29,6 @@ cert\_chain\_resolver.utils module :undoc-members: :show-inheritance: -cert\_chain\_resolver.root module ----------------------------------- - -.. automodule:: cert_chain_resolver.root.base_store - :members: - :undoc-members: - :show-inheritance: - -.. automodule:: cert_chain_resolver.root.certifi - :members: - :undoc-members: - :show-inheritance: - cert\_chain\_resolver.cli module --------------------------------