cert-utils 1.0.3__tar.gz → 1.0.4__tar.gz

{cert_utils-1.0.3 → cert_utils-1.0.4}/CHANGES.txt

@@ -1,3 +1,17 @@
+1.0.4
+    The following functions now accept new kwargs:
+        * kwargs:
+            allow_hostname: bool = True
+            allow_ipv4: bool = False
+            allow_ipv6: bool = False
+        * functions
+            - domains_from_list
+            - domains_from_string
+            - validate_domains
+    * new functions
+        utils.identify_san_type
+    * updated repo to not allow admins to bypass rules
+    
 1.0.3
     * exception did not properly interpolate variable
 

cert_utils-1.0.4/PKG-INFO

@@ -0,0 +1,234 @@
+Metadata-Version: 2.2
+Name: cert_utils
+Version: 1.0.4
+Summary: TLS/SSL Certiicate 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: License :: OSI Approved :: MIT License
+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
+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: 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: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: keywords
+Dynamic: license
+Dynamic: provides-extra
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+![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.

{cert_utils-1.0.3 → cert_utils-1.0.4}/src/cert_utils/__init__.py

@@ -5,4 +5,4 @@ from .utils import *  # noqa: F401, F403
 
 # ==============================================================================
 
-__VERSION__ = "1.0.3"
+__VERSION__ = "1.0.4"

{cert_utils-1.0.3 → cert_utils-1.0.4}/src/cert_utils/utils.py

@@ -11,6 +11,9 @@ 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")
@@ -34,11 +37,67 @@ CERT_PEM_REGEX = re.compile(
 
 
 # technically we could end in a dot (\.?)
-RE_domain = re.compile(
-    r"""^(?:\*\.)?(?:[A-Z0-9](?:[A-Z0-9-]{0,61}[A-Z0-9])?\.)+(?:[A-Z]{2,6}|[A-Z0-9-]{2,}(?<!-))$""",
-    re.I,
+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
+    \.
+)?
+)+                              # 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]]]
@@ -100,7 +159,12 @@ def curve_to_nist(curve_name: str) -> str:
     raise ValueError("Unknown curve: %s" % curve_name)
 
 
-def domains_from_list(domain_names: Iterable[str]) -> List[str]:
+def domains_from_list(
+    domain_names: Iterable[str],
+    allow_hostname: bool = True,
+    allow_ipv4: bool = False,
+    allow_ipv6: bool = False,
+) -> List[str]:
     """
     Turns a list of strings into a standardized list of domain names.
 
@@ -109,26 +173,53 @@ def domains_from_list(domain_names: Iterable[str]) -> List[str]:
     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
     """
     domain_names = [d for d in [d.strip().lower() for d in domain_names] if d]
     # make the list unique
-    domain_names = list(set(domain_names))
+    domain_names = sorted(list(set(domain_names)))
     # validate the list
-    validate_domains(domain_names)
+    validate_domains(
+        domain_names,
+        allow_hostname=allow_hostname,
+        allow_ipv4=allow_ipv4,
+        allow_ipv6=allow_ipv6,
+    )
     return domain_names
 
 
-def domains_from_string(text: str) -> List[str]:
+def domains_from_string(
+    text: str,
+    allow_hostname: bool = True,
+    allow_ipv4: bool = False,
+    allow_ipv6: bool = False,
+) -> List[str]:
     """
-    :param text: (required) Turns a comma-separated-list of domain names into a list
-
     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
     """
     # generate list
     domain_names = text.split(",")
-    return domains_from_list(domain_names)
+    return domains_from_list(
+        domain_names,
+        allow_hostname=allow_hostname,
+        allow_ipv4=allow_ipv4,
+        allow_ipv6=allow_ipv6,
+    )
 
 
 def hex_with_colons(as_hex: str) -> str:
@@ -140,6 +231,27 @@ def hex_with_colons(as_hex: str) -> str:
     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("=", "")
@@ -197,15 +309,42 @@ def split_pem_chain(pem_text: str) -> List[str]:
     return certs
 
 
-def validate_domains(domain_names: Iterable[str]) -> bool:
+def validate_domains(
+    domain_names: Iterable[str],
+    allow_hostname: bool = True,
+    allow_ipv4: bool = False,
+    allow_ipv6: bool = False,
+) -> bool:
     """
-    Ensures each items of the iterable `domain_names` matches a regular expression.
+    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
     """
     for d in domain_names:
-        if not RE_domain.match(d):
-            raise ValueError("invalid domain: `%s`" % d)
+        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):
+            # 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