cert-utils 1.2.0__py3-none-any.whl

cert_utils/utils.py

@@ -0,0 +1,388 @@
+# General Utility Functions
+
+# stdlib
+import base64
+import binascii
+import hashlib
+import ipaddress
+import re
+import tempfile
+from typing import Iterable
+from typing import List
+from typing import Tuple
+from typing import Union
+
+# pypi
+from typing_extensions import Literal
+
+# ==============================================================================
+
+_RE_rn = re.compile(r"\r\n")
+
+
+# https://github.com/certbot/certbot/blob/master/certbot/certbot/crypto_util.py#L482
+#
+# Finds one CERTIFICATE stricttextualmsg according to rfc7468#section-3.
+# Does not validate the base64text - use crypto.load_certificate.
+#
+# NOTE: this functions slightly differently as " *?" was added
+#       the first two letsencrypt certificates added a trailing space, which may
+#       not be compliant with the specification
+CERT_PEM_REGEX = re.compile(
+    """-----BEGIN CERTIFICATE----- *?\r?
+.+?\r?
+-----END CERTIFICATE----- *?\r?
+""",
+    re.DOTALL,  # DOTALL (/s) because the base64text may include newlines
+)
+
+
+# technically we could end in a dot (\.?)
+RE_cert_domain = re.compile(
+    r"""
+^
+(?:\*\.)?                       # allow a leading "*.", to denote wildcards
+(?:
+    [A-Z0-9]                    # the first char MUST be a letter or number
+    (?:
+        (?:[A-Z0-9-]{0,61}          # inner chars can have a dash
+        [A-Z0-9]                    # the last char must be a leter or number
+    )?                          # make this optional, to support 1 letter subdomains
+    \.
+)?
+)+                              # one or more components
+(?:
+    [A-Z]{2,6}
+    |
+    [A-Z0-9-]{2,}
+    (?<!-)                      # doesn't end with a dash
+)
+
+$
+""",
+    re.I | re.X,
+)
+
+
+# https://stackoverflow.com/questions/53497/regular-expression-that-matches-valid-ipv6-addresses
+
+# IPv6 RegEx
+RE_ipv6 = re.compile(
+    r"""
+(
+([0-9a-fA-F]{1,4}:){7,7}[0-9a-fA-F]{1,4}|          # 1:2:3:4:5:6:7:8
+([0-9a-fA-F]{1,4}:){1,7}:|                         # 1::                              1:2:3:4:5:6:7::
+([0-9a-fA-F]{1,4}:){1,6}:[0-9a-fA-F]{1,4}|         # 1::8             1:2:3:4:5:6::8  1:2:3:4:5:6::8
+([0-9a-fA-F]{1,4}:){1,5}(:[0-9a-fA-F]{1,4}){1,2}|  # 1::7:8           1:2:3:4:5::7:8  1:2:3:4:5::8
+([0-9a-fA-F]{1,4}:){1,4}(:[0-9a-fA-F]{1,4}){1,3}|  # 1::6:7:8         1:2:3:4::6:7:8  1:2:3:4::8
+([0-9a-fA-F]{1,4}:){1,3}(:[0-9a-fA-F]{1,4}){1,4}|  # 1::5:6:7:8       1:2:3::5:6:7:8  1:2:3::8
+([0-9a-fA-F]{1,4}:){1,2}(:[0-9a-fA-F]{1,4}){1,5}|  # 1::4:5:6:7:8     1:2::4:5:6:7:8  1:2::8
+[0-9a-fA-F]{1,4}:((:[0-9a-fA-F]{1,4}){1,6})|       # 1::3:4:5:6:7:8   1::3:4:5:6:7:8  1::8
+:((:[0-9a-fA-F]{1,4}){1,7}|:)|                     # ::2:3:4:5:6:7:8  ::2:3:4:5:6:7:8 ::8       ::
+fe80:(:[0-9a-fA-F]{0,4}){0,4}%[0-9a-zA-Z]{1,}|     # fe80::7:8%eth0   fe80::7:8%1     (link-local IPv6 addresses with zone index)
+::(ffff(:0{1,4}){0,1}:){0,1}
+((25[0-5]|(2[0-4]|1{0,1}[0-9]){0,1}[0-9])\.){3,3}
+(25[0-5]|(2[0-4]|1{0,1}[0-9]){0,1}[0-9])|          # ::255.255.255.255   ::ffff:255.255.255.255  ::ffff:0:255.255.255.255  (IPv4-mapped IPv6 addresses and IPv4-translated addresses)
+([0-9a-fA-F]{1,4}:){1,4}:
+((25[0-5]|(2[0-4]|1{0,1}[0-9]){0,1}[0-9])\.){3,3}
+(25[0-5]|(2[0-4]|1{0,1}[0-9]){0,1}[0-9])           # 2001:db8:3:4::192.0.2.33  64:ff9b::192.0.2.33 (IPv4-Embedded IPv6 Address)
+)
+""",
+    re.I | re.X,
+)
+
+
+# IPv4 RegEx
+RE_ipv4 = re.compile(
+    r"""
+((25[0-5]|(2[0-4]|1{0,1}[0-9]){0,1}[0-9])\.){3,3}(25[0-5]|(2[0-4]|1{0,1}[0-9]){0,1}[0-9])
+""",
+    re.I | re.X,
+)
+
+
+# (RSA, (4096,))
+# (EC, ("P-384",))
+TECHNOLOGY_RETURN_VALUES = Tuple[str, Tuple[Union[str, int]]]
+
+
+# ------------------------------------------------------------------------------
+
+
+def cleanup_pem_text(pem_text: str) -> str:
+    """
+    * standardizes newlines;
+    * removes trailing spaces;
+    * ensures a trailing newline.
+
+    :param pem_text: PEM formatted string
+    :type pem_text: str
+    :returns: cleaned PEM text
+    :rtype: str
+    """
+    pem_text = _RE_rn.sub("\n", pem_text)
+    _pem_text_lines = [i.strip() for i in pem_text.split("\n")]
+    _pem_text_lines = [i for i in _pem_text_lines if i]
+    pem_text = "\n".join(_pem_text_lines) + "\n"
+    return pem_text
+
+
+def convert_binary_to_hex(input: bytes) -> str:
+    """
+    the cryptography package surfaces raw binary data
+    openssl uses hex encoding, uppercased, with colons
+    this function translates the binary to the hex uppercase.
+    the colons can be rendered on demand.
+
+    example: isrg-root-x2-cross-signed.pem's authority_key_identifier
+
+        binary (from cryptography)
+            y\xb4Y\xe6{\xb6\xe5\xe4\x01s\x80\x08\x88\xc8\x1aX\xf6\xe9\x9bn
+
+        hex (from openssl)
+            79:B4:59:E6:7B:B6:E5:E4:01:73:80:08:88:C8:1A:58:F6:E9:9B:6E
+
+        via this function:
+            79B459E67BB6E5E40173800888C81A58F6E99B6E
+    """
+    # input = "y\xb4Y\xe6{\xb6\xe5\xe4\x01s\x80\x08\x88\xc8\x1aX\xf6\xe9\x9bn"
+    _as_hex = binascii.b2a_hex(input)
+    # _as_hex = "79b459e67bb6e5e40173800888c81a58f6e99b6e"
+    _as_hex = _as_hex.upper()
+    # _as_hex = "79B459E67BB6E5E40173800888C81A58F6E99B6E"
+    _as_hex_str = _as_hex.decode("utf8")
+    return _as_hex_str
+
+
+def curve_to_nist(curve_name: str) -> str:
+    if curve_name == "secp256r1":
+        return "P-256"
+    elif curve_name == "secp384r1":
+        return "P-384"
+    raise ValueError("Unknown curve: %s" % curve_name)
+
+
+def domains_from_list(
+    domain_names: Iterable[str],
+    allow_hostname: bool = True,
+    allow_ipv4: bool = False,
+    allow_ipv6: bool = False,
+    ipv6_require_compressed: bool = False,
+) -> List[str]:
+    """
+    Turns a list of strings into a standardized list of domain names.
+
+    Will raise `ValueError("invalid domain")` if non-conforming elements are encountered.
+
+    This invokes `validate_domains`, which uses a simple regex to validate each domain in the list.
+
+    :param domain_names: (required) An iterable list of strings
+    :param allow_hostname: bool, default True
+        added in 1.0.4
+    :param allow_ipv4: bool, default False
+        added in 1.0.4
+    :param allow_ipv6: bool, default False
+        added in 1.0.4
+    :param ipv6_require_compressed: bool, default False
+        added in 1.0.5
+    """
+    domain_names = [d for d in [d.strip().lower() for d in domain_names] if d]
+    # make the list unique
+    domain_names = sorted(list(set(domain_names)))
+    # validate the list
+    validate_domains(
+        domain_names,
+        allow_hostname=allow_hostname,
+        allow_ipv4=allow_ipv4,
+        allow_ipv6=allow_ipv6,
+        ipv6_require_compressed=ipv6_require_compressed,
+    )
+    return domain_names
+
+
+def domains_from_string(
+    text: str,
+    allow_hostname: bool = True,
+    allow_ipv4: bool = False,
+    allow_ipv6: bool = False,
+    ipv6_require_compressed: bool = False,
+) -> List[str]:
+    """
+    This invokes `domains_from_list` which invokes `validate_domains`, which uses a simple regex to validate each domain in the list.
+
+    This will raise a `ValueError("invalid domain")` on the first invalid domain
+
+    :param text: (required) Turns a comma-separated-list of domain names into a list
+    :param allow_hostname: bool, default True
+        added in 1.0.4
+    :param allow_ipv4: bool, default False
+        added in 1.0.4
+    :param allow_ipv6: bool, default False
+        added in 1.0.4
+    :param ipv6_require_compressed: bool, default False
+        added in 1.0.5
+    """
+    # generate list
+    domain_names = text.split(",")
+    return domains_from_list(
+        domain_names,
+        allow_hostname=allow_hostname,
+        allow_ipv4=allow_ipv4,
+        allow_ipv6=allow_ipv6,
+        ipv6_require_compressed=ipv6_require_compressed,
+    )
+
+
+def hex_with_colons(as_hex: str) -> str:
+    # as_hex = '79B459E67BB6E5E40173800888C81A58F6E99B6E'
+    _pairs = [as_hex[idx : idx + 2] for idx in range(0, len(as_hex), 2)]
+    # _pairs = ['79', 'B4', '59', 'E6', '7B', 'B6', 'E5', 'E4', '01', '73', '80', '08', '88', 'C8', '1A', '58', 'F6', 'E9', '9B', '6E']
+    output = ":".join(_pairs)
+    # '79:B4:59:E6:7B:B6:E5:E4:01:73:80:08:88:C8:1A:58:F6:E9:9B:6E'
+    return output
+
+
+def identify_san_type(
+    san: str,
+) -> Literal["hostname", "ipv4", "ipv6"]:
+    """
+    This does a rudimentary check against hostnames (default) and optionally
+    ipv4 and ipv6.
+
+    see also: validate_domains
+    added in 1.0.4
+    """
+    if RE_cert_domain.match(san):
+        if RE_ipv4.match(san):
+            return "ipv4"
+        return "hostname"
+    if RE_ipv4.match(san):
+        return "ipv4"
+    if RE_ipv6.match(san):
+        return "ipv6"
+    raise ValueError("invalid san: `%s`" % san)
+
+
+def jose_b64(b: bytes) -> str:
+    # helper function base64 encode for jose spec
+    return base64.urlsafe_b64encode(b).decode("utf8").replace("=", "")
+
+
+def md5_text(text: Union[bytes, str]) -> str:
+    if isinstance(text, str):
+        text = text.encode()
+    return hashlib.md5(text).hexdigest()
+
+
+def new_pem_tempfile(pem_data: str) -> tempfile._TemporaryFileWrapper:
+    """
+    this is just a convenience wrapper to create a tempfile and seek(0)
+
+    :param pem_data: PEM encoded string to seed the tempfile with
+    :type pem_data: str
+    :returns: a tempfile instance
+    :rtype: tempfile.NamedTemporaryFile
+    """
+    tmpfile_pem = tempfile.NamedTemporaryFile()
+    if isinstance(pem_data, str):
+        pem_bytes = pem_data.encode()
+    tmpfile_pem.write(pem_bytes)
+    tmpfile_pem.seek(0)
+    return tmpfile_pem
+
+
+def new_der_tempfile(der_data: bytes) -> tempfile._TemporaryFileWrapper:
+    """
+    this is just a convenience wrapper to create a tempfile and seek(0)
+
+    :param der_data: DER encoded string to seed the tempfile with
+    :type der_data: str
+    :returns: a tempfile instance
+    :rtype: `tempfile.NamedTemporaryFile`
+    """
+    tmpfile_der = tempfile.NamedTemporaryFile()
+    tmpfile_der.write(der_data)
+    tmpfile_der.seek(0)
+    return tmpfile_der
+
+
+def split_pem_chain(pem_text: str) -> List[str]:
+    """
+    splits a PEM encoded Certificate chain into multiple Certificates
+
+    :param pem_text: PEM formatted string containing one or more Certificates
+    :type pem_text: str
+    :returns: a list of PEM encoded Certificates
+    :rtype: list
+    """
+    _certs = CERT_PEM_REGEX.findall(pem_text)
+    certs = [cleanup_pem_text(i) for i in _certs]
+    return certs
+
+
+def validate_domains(
+    domain_names: Iterable[str],
+    allow_hostname: bool = True,
+    allow_ipv4: bool = False,
+    allow_ipv6: bool = False,
+    ipv6_require_compressed: bool = False,
+) -> bool:
+    """
+    Ensures each items of the iterable `domain_names` is qualified for inclusion
+    in a x509 certificate.
+
+    This does a rudimentary check against hostnames (default) and optionally
+    ipv4 and ipv6.
+
+    see also: identify_san_type
+
+    :param domain_names: (required) An iterable list of strings
+    :param allow_hostname: bool, default True
+        added in 1.0.4
+    :param allow_ipv4: bool, default False
+        added in 1.0.4
+    :param allow_ipv6: bool, default False
+        added in 1.0.4
+    :param ipv6_require_compressed: bool, default False
+        added in 1.0.5
+    """
+    for d in domain_names:
+        if allow_hostname and RE_cert_domain.match(d):
+            if RE_ipv4.match(d):
+                if not allow_ipv4:
+                    raise ValueError("invalid domain: `%s`" % d)
+            continue
+        if allow_ipv4 and RE_ipv4.match(d):
+            continue
+        if allow_ipv6 and RE_ipv6.match(d):
+            # require compressed
+            if ipv6_require_compressed:
+                validate_ipv6_address(d, ipv6_require_compressed=True)
+            # TODO: drop out special prefixes
+            # https://www.iana.org/assignments/iana-ipv6-special-registry/iana-ipv6-special-registry.xhtml
+            continue
+        raise ValueError("invalid domain: `%s`" % d)
+    return True
+
+
+def validate_ipv6_address(
+    domain_name: str,
+    ipv6_require_compressed: bool = False,
+) -> Literal[True]:
+    try:
+        # _obj = ipaddress.ip_address(domain_name)
+        _obj = ipaddress.IPv6Address(domain_name)
+        if ipv6_require_compressed:
+            if _obj.compressed != domain_name:
+                raise ValueError(
+                    "invalid domain: `%s`; ipv6 must be compressed." % domain_name
+                )
+        return True
+    except ipaddress.AddressValueError as exc:
+        raise ValueError(
+            'invalid domain: `%s`; ipaddress.AddressValueError("%s").'
+            % (domain_name, exc.args[0])
+        )
+
+
+# ------------------------------------------------------------------------------

cert_utils-1.2.0.dist-info/METADATA

@@ -0,0 +1,259 @@
+Metadata-Version: 2.4
+Name: cert_utils
+Version: 1.2.0
+Summary: TLS/SSL Certificate Utilities
+Home-page: https://github.com/aptise/cert_utils
+Author: Jonathan Vanasco
+Author-email: jonathan@findmeon.com
+License: MIT
+Keywords: web
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.7
+Classifier: Programming Language :: Python :: 3.8
+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: Programming Language :: Python :: 3.14
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+License-File: LICENSE.txt
+Requires-Dist: python-dateutil
+Requires-Dist: psutil>=4.4.0
+Requires-Dist: requests
+Requires-Dist: typing_extensions
+Requires-Dist: importlib_metadata; python_version < "3.8"
+Provides-Extra: testing
+Requires-Dist: certbot; extra == "testing"
+Requires-Dist: cryptography>=42.0.0; extra == "testing"
+Requires-Dist: josepy<3; extra == "testing"
+Requires-Dist: mypy; extra == "testing"
+Requires-Dist: pytest; extra == "testing"
+Requires-Dist: pytest-cov; extra == "testing"
+Requires-Dist: pyOpenSSL; extra == "testing"
+Requires-Dist: coverage[toml]; extra == "testing"
+Requires-Dist: types-psutil; extra == "testing"
+Requires-Dist: types-python-dateutil; extra == "testing"
+Requires-Dist: types-requests; extra == "testing"
+Provides-Extra: josepy
+Requires-Dist: josepy<3; extra == "josepy"
+Dynamic: license-file
+
+![Python package](https://github.com/jvanasco/cert_utils/workflows/Python%20package/badge.svg)
+
+cert_utils
+==========
+
+**cert_utils** offers support for common operations when dealing with SSL
+Certificates, specifically within the LetsEncrypt ecosystem.
+
+This library was originally developed as a toolkit for bugfixing and
+troubleshooting large ACME installations.
+
+**cert_utils** will attempt to process operations with Python via the modern
+[Cryptography](https://cryptography.io/en/latest/) package when possible.
+If the required Python libraries are not installed, it will fallback to using
+OpenSSL commandline via subprocesses.  **cert_utils** does a bit of work to
+standardize certificate operations across versions of Python and OpenSSL that
+do not share the same inputs, outputs or invocations.
+
+**cert_utils** was formerly part of the
+**[peter_sslers](https://github.com/aptise/peter_sslers)** ACME Client and
+Certificate Management System, and has been descoped into it's own library.
+
+This library *does not* process Certificates and Certificate Data itself.
+Instead, it offers a simplified API to invoke other libraries and extract data
+from Certificates.  It was designed for developers and system administrators to
+more easily use the various libraries to accomplish specific tasks on the
+commandline or as part of other projects.
+
+This library now includes a utility, `cert_info`:
+
+Examples CLI:
+-------------
+
+The CLI tool `cert_info` can parse a cert and pull the active ARI info.
+
+The tool accepts a filepath to a local file OR a https URL to be inspected live:
+
+> cert_info https://letsencrypt.org
+
+This will gnerate the output:
+
+    ********************************************************************************
+    ********************************************************************************
+    Process URL:
+    url:  https://letsencrypt.org
+    =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
+    Connection Data:
+    {'cert_dict': {'OCSP': ('http://e6.o.lencr.org',),
+                   'caIssuers': ('http://e6.i.lencr.org/',),
+                   'issuer': ((('countryName', 'US'),),
+                              (('organizationName', "Let's Encrypt"),),
+                              (('commonName', 'E6'),)),
+                   'notAfter': 'Mar  7 14:44:04 2025 GMT',
+                   'notBefore': 'Dec  7 14:44:05 2024 GMT',
+                   'serialNumber': '04C7A73A361AC02B67BDBD6AF210285B1CC7',
+                   'subject': ((('commonName', 'letsencrypt.org'),),),
+                   'subjectAltName': (('DNS', 'lencr.org'),
+                                      ('DNS', 'letsencrypt.com'),
+                                      ('DNS', 'letsencrypt.org'),
+                                      ('DNS', 'www.lencr.org'),
+                                      ('DNS', 'www.letsencrypt.com'),
+                                      ('DNS', 'www.letsencrypt.org')),
+                   'version': 3},
+     'cert_pem': '-----BEGIN CERTIFICATE-----\n'
+                 'MIID1DCCA1qgAwIBAgISBMenOjYawCtnvb1q8hAoWxzHMAoGCCqGSM49BAMDMDIx\n'
+                 'CzAJBgNVBAYTAlVTMRYwFAYDVQQKEw1MZXQncyBFbmNyeXB0MQswCQYDVQQDEwJF\n'
+                 'NjAeFw0yNDEyMDcxNDQ0MDVaFw0yNTAzMDcxNDQ0MDRaMBoxGDAWBgNVBAMTD2xl\n'
+                 'dHNlbmNyeXB0Lm9yZzBZMBMGByqGSM49AgEGCCqGSM49AwEHA0IABDgHHaIeMwYz\n'
+                 'APO9ZgfeGansUeFRN0sW4K23nrVppRXfjHvN+83vtH170hshCrIAZRJCL+CPcA2N\n'
+                 'UqmLiSdM/M+jggJmMIICYjAOBgNVHQ8BAf8EBAMCB4AwHQYDVR0lBBYwFAYIKwYB\n'
+                 'BQUHAwEGCCsGAQUFBwMCMAwGA1UdEwEB/wQCMAAwHQYDVR0OBBYEFD2MLtcnwBWM\n'
+                 'FukcX4wMfYCQUCMAMB8GA1UdIwQYMBaAFJMnRpgDqVFojpjWxEJI2yO/WJTSMFUG\n'
+                 'CCsGAQUFBwEBBEkwRzAhBggrBgEFBQcwAYYVaHR0cDovL2U2Lm8ubGVuY3Iub3Jn\n'
+                 'MCIGCCsGAQUFBzAChhZodHRwOi8vZTYuaS5sZW5jci5vcmcvMG8GA1UdEQRoMGaC\n'
+                 'CWxlbmNyLm9yZ4IPbGV0c2VuY3J5cHQuY29tgg9sZXRzZW5jcnlwdC5vcmeCDXd3\n'
+                 'dy5sZW5jci5vcmeCE3d3dy5sZXRzZW5jcnlwdC5jb22CE3d3dy5sZXRzZW5jcnlw\n'
+                 'dC5vcmcwEwYDVR0gBAwwCjAIBgZngQwBAgEwggEEBgorBgEEAdZ5AgQCBIH1BIHy\n'
+                 'APAAdgB9WR4S4XgqexxhZ3xe/fjQh1wUoE6VnrkDL9kOjC55uAAAAZOhyXh9AAAE\n'
+                 'AwBHMEUCIAXoVc0BRK6ELL0Q1lHv+QbrobnBiPthcr2E7g0IulkHAiEAlVkiVkF9\n'
+                 '7KeR/At3XdJNRYbJda0iKaKtqKy0KH7igZgAdgATSt8atZhCCXgMb+9MepGkFrcj\n'
+                 'Sc5YV2rfrtqnwqvgIgAAAZOhyXk0AAAEAwBHMEUCIQD+yhm/6lwMMWyxBaB15Mkh\n'
+                 'g3tsQCtr0DOD4uvAzc63FAIgHgjXduGCbB/3VTtRCGWfmkWSS9z+CjfO1O6hkzGW\n'
+                 'XBowCgYIKoZIzj0EAwMDaAAwZQIxAKVLzxW03Kk8qJMBtWQCw5dgSHNWOGG9Oq03\n'
+                 'XOGr8092sx9Ezz3XsXWeq8JvokFjhAIwCZOX/UjxdHfgV/O6gkiNARQ1FokDyfS0\n'
+                 'ClynPk9psMTPVl5QWgYJzjVrJagAjtJm\n'
+                 '-----END CERTIFICATE-----\n',
+     'peername': ('100.28.201.155', 443)}
+    =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
+    =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
+    Cert Data:
+    ARI ID: kydGmAOpUWiOmNbEQkjbI79YlNI.BMenOjYawCtnvb1q8hAoWxzH
+    =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
+    Requesting ARI
+    ari_url: https://acme-v02.api.letsencrypt.org/draft-ietf-acme-ari-03/renewalInfo/kydGmAOpUWiOmNbEQkjbI79YlNI.BMenOjYawCtnvb1q8hAoWxzH
+    {'Server': 'nginx', 'Date': 'Tue, 10 Dec 2024 18:29:04 GMT', 'Content-Type': 'application/json', 'Content-Length': '101', 'Connection': 'keep-alive', 'Cache-Control': 'public, max-age=0, no-cache', 'Link': '<https://acme-v02.api.letsencrypt.org/directory>;rel="index"', 'Retry-After': '21600', 'X-Frame-Options': 'DENY', 'Strict-Transport-Security': 'max-age=604800'}
+    - - - - - - - - - - 
+    {'suggestedWindow': {'end': '2025-02-06T15:03:34Z',
+                         'start': '2025-02-04T15:03:34Z'}}
+
+
+Examples API:
+-------------
+
+For example, `cert_utils.parse_cert` returns a Python dict of key fields in a
+certificate.  This can make writing a script to analyze large directories of
+certificates fairly simple.
+
+
+### Parse a Leaf/End-Entity
+
+Example Script:
+
+```!python
+import cert_utils
+import pprint
+
+cert_path = "./tests/test_data/unit_tests/cert_001/cert.pem"
+cert_pem = open(cert_path, 'r').read()
+data = cert_utils.parse_cert(cert_pem)
+pprint.pprint(data)
+```
+
+Result:
+
+    {'SubjectAlternativeName': ['a.example.com',
+                                'b.example.com',
+                                'c.example.com',
+                                'd.example.com'],
+     'authority_key_identifier': 'D159010094B0A62ADBABE54B2321CA1B6EBA93E7',
+     'enddate': datetime.datetime(2025, 6, 16, 20, 19, 30),
+     'fingerprint_sha1': 'F63C5C66B52551EEDADF7CE44301D646680B8F5D',
+     'issuer': 'CN=Pebble Intermediate CA 601ea1',
+     'issuer_uri': None,
+     'key_technology': 'RSA',
+     'spki_sha256': '34E67CC615761CBADAF430B2E02E0EC39C99EEFC73CCE469B18AE54A37EF6942',
+     'startdate': datetime.datetime(2020, 6, 16, 20, 19, 30),
+     'subject': 'CN=a.example.com'}
+
+The payload contains `SubjectAlternativeName` listing all the domains, along
+with `enddate` and `startdate` in Python datetime objects for easy comparison.
+
+### Parse a Trusted Root
+
+Example Script:
+
+```!python
+import cert_utils
+import pprint
+
+cert_path = "./src/cert_utils/letsencrypt-certs/isrgrootx1.pem"
+cert_pem = open(cert_path, 'r').read()
+data = cert_utils.parse_cert(cert_pem)
+pprint.pprint(data)
+```
+
+Result:
+
+    {'SubjectAlternativeName': None,
+     'authority_key_identifier': None,
+     'enddate': datetime.datetime(2035, 6, 4, 11, 4, 38),
+     'fingerprint_sha1': 'CABD2A79A1076A31F21D253635CB039D4329A5E8',
+     'issuer': 'C=US\nO=Internet Security Research Group\nCN=ISRG Root X1',
+     'issuer_uri': None,
+     'key_technology': 'RSA',
+     'spki_sha256': '0B9FA5A59EED715C26C1020C711B4F6EC42D58B0015E14337A39DAD301C5AFC3',
+     'startdate': datetime.datetime(2015, 6, 4, 11, 4, 38),
+     'subject': 'C=US\nO=Internet Security Research Group\nCN=ISRG Root X1'}
+
+The payload on Trusted Roots is identical.
+
+
+Why does this exist?
+--------------------
+
+The [peter_sslers](https://github.com/aptise/peter_sslers) project was designed
+to deploy on a wide variety of production servers that did not share common
+Python and OpenSSL installations.  Earlier versions of the library
+(within peter_sslers) supported both Python2.7 and Python3, as it was common to
+encounter a machine that did not have Python3 installed.  Although it is still
+common to find these machines, Python2.7 was dropped to take advantage of
+typing.  Depending on the version of OpenSSL installed on a system,
+**cert_utils** will invoke the binary or regex the output to bridge support
+through a unified interface.
+
+Historical implementation notes: [OpenSSL reference](docs/openssl-reference.md).
+
+HTTP timeouts
+-------------
+
+`cert_info` uses a Requests `(connect, read)` timeout of `(5, 30)` seconds.
+The read timeout limits inactivity between reads; it is not a total command
+execution deadline. Override both values with positive, finite seconds:
+
+```sh
+CERT_UTILS_TIMEOUT=3,20 cert_info https://example.com
+cert_info --timeout 2,10 https://example.com
+cert_info --timeout 2,10 /path/to/cert.pem
+```
+
+Precedence is explicit CLI/Python argument, then `CERT_UTILS_TIMEOUT`, then the
+default. The CLI override also applies to directory and subsequent ARI requests.
+Python callers can pass `timeout=(connect, read)` to `new_session`, `ari_query`,
+`process_url`, `process_filepath`, `process_ari_url`, and
+`download_letsencrypt_certificates`. Sessions from `new_session` retain Requests'
+per-request timeout override support. CLI-owned sessions are closed on success
+and failure; callers retain ownership of sessions passed to `process_ari_url`.
+
+Compatibility design notes: [certificate profiles and peer hooks](docs/compatibility.md).
+
+Bundled CA snapshot and migration notes: [Let's Encrypt certificate archive](docs/letsencrypt-bundle.md).
+
+Machine-readable production rate policy: [schema 2 and migration guide](docs/rate-limits.md).
+Import `cert_utils.letsencrypt_info.rate_limits.RATE_LIMITS` without loading the CA archive.
+
+Account-signature formats and backend behavior: [signing and verification](docs/account-signatures.md).