spiffe-tls 0.1.0__tar.gz

spiffe_tls-0.1.0/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

spiffe_tls-0.1.0/PKG-INFO

@@ -0,0 +1,79 @@
+Metadata-Version: 2.1
+Name: spiffe-tls
+Version: 0.1.0
+Summary: TLS Support using SPIFFE
+License: Apache-2.0
+Author: Max Lambrecht
+Author-email: maxlambrecht@gmail.com
+Requires-Python: >=3.9,<4.0
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Dist: pyOpenSSL (>=24.0,<25.0)
+Requires-Dist: spiffe (>=0.1.0,<0.2.0)
+Description-Content-Type: text/markdown
+
+# `spiffe-tls` Module
+
+This `py-spiffe` module provides TLS utilities that facilitate creating secure TLS connections leveraging SPIFFE IDs for
+authentication. It wraps [pyOpenSSL](https://pypi.org/project/pyOpenSSL/), offering easy-to-use functions for setting up
+TLS clients and servers with SPIFFE-based authentication using `X509Source` to manage and automatically update X.509
+certificates and CA trusted bundles.
+
+## Key Features
+
+- Establish TLS connections with SPIFFE ID validation.
+- Support for Mutual TLS (MTLS) and TLS with server authorization.
+- Extensible options for server and client configurations.
+
+## Quick Start
+
+### Server Setup
+
+Use the `listen()` function to create a TLS server socket bound to a specified address, configured according to SPIFFE
+X.509 SVIDs.
+
+```python
+from spiffetls import listen, ListenOptions
+from spiffe import SpiffeId, X509Source
+from spiffetls.mode import ServerTlsMode
+from spiffetls.tlsconfig.authorize import authorize_id
+
+x509_source = X509Source()
+options = ListenOptions(
+    tls_mode=ServerTlsMode.MTLS,
+    authorize_fn=authorize_id(SpiffeId("spiffe://example.org/client-service")),
+)
+
+listener = listen("localhost:8443", x509_source, options)
+```
+
+### Client Connection
+
+Use the `dial()` function to establish a secure client connection to a TLS server.
+
+```python
+from spiffetls import dial
+from spiffe import SpiffeId, X509Source
+from spiffetls.tlsconfig.authorize import authorize_id
+
+x509_source = X509Source()
+
+conn = dial(
+    "localhost:8443",
+    x509_source,
+    authorize_fn=authorize_id(SpiffeId("spiffe://example.org/client-service")),
+)
+```
+
+### Authorization Functions
+
+The module supports custom authorization functions for additional certificate validation:
+
+- `authorize_any()`: Authorizes any valid SPIFFE ID.
+- `authorize_id(expected_spiffe_id)`: Authorizes a specific SPIFFE ID.
+- `authorize_one_of(allowed_ids)`: Authorizes any SPIFFE ID in a given set.
+- `authorize_member_of(allowed_trust_domain)`: Authorizes any SPIFFE ID within a specific trust domain.

spiffe_tls-0.1.0/README.md

@@ -0,0 +1,61 @@
+# `spiffe-tls` Module
+
+This `py-spiffe` module provides TLS utilities that facilitate creating secure TLS connections leveraging SPIFFE IDs for
+authentication. It wraps [pyOpenSSL](https://pypi.org/project/pyOpenSSL/), offering easy-to-use functions for setting up
+TLS clients and servers with SPIFFE-based authentication using `X509Source` to manage and automatically update X.509
+certificates and CA trusted bundles.
+
+## Key Features
+
+- Establish TLS connections with SPIFFE ID validation.
+- Support for Mutual TLS (MTLS) and TLS with server authorization.
+- Extensible options for server and client configurations.
+
+## Quick Start
+
+### Server Setup
+
+Use the `listen()` function to create a TLS server socket bound to a specified address, configured according to SPIFFE
+X.509 SVIDs.
+
+```python
+from spiffetls import listen, ListenOptions
+from spiffe import SpiffeId, X509Source
+from spiffetls.mode import ServerTlsMode
+from spiffetls.tlsconfig.authorize import authorize_id
+
+x509_source = X509Source()
+options = ListenOptions(
+    tls_mode=ServerTlsMode.MTLS,
+    authorize_fn=authorize_id(SpiffeId("spiffe://example.org/client-service")),
+)
+
+listener = listen("localhost:8443", x509_source, options)
+```
+
+### Client Connection
+
+Use the `dial()` function to establish a secure client connection to a TLS server.
+
+```python
+from spiffetls import dial
+from spiffe import SpiffeId, X509Source
+from spiffetls.tlsconfig.authorize import authorize_id
+
+x509_source = X509Source()
+
+conn = dial(
+    "localhost:8443",
+    x509_source,
+    authorize_fn=authorize_id(SpiffeId("spiffe://example.org/client-service")),
+)
+```
+
+### Authorization Functions
+
+The module supports custom authorization functions for additional certificate validation:
+
+- `authorize_any()`: Authorizes any valid SPIFFE ID.
+- `authorize_id(expected_spiffe_id)`: Authorizes a specific SPIFFE ID.
+- `authorize_one_of(allowed_ids)`: Authorizes any SPIFFE ID in a given set.
+- `authorize_member_of(allowed_trust_domain)`: Authorizes any SPIFFE ID within a specific trust domain.

spiffe_tls-0.1.0/pyproject.toml

@@ -0,0 +1,49 @@
+[tool.poetry]
+name = "spiffe-tls"
+version = "0.1.0"
+description = "TLS Support using SPIFFE"
+authors = ["Max Lambrecht <maxlambrecht@gmail.com>"]
+readme = "README.md"
+license = "Apache-2.0"
+
+packages = [
+    { include = "spiffetls", from = "src" },
+]
+
+[tool.poetry.dependencies]
+python = "^3.9"  # >= 3.9, < 4.0
+spiffe = "~0.1.0"
+pyOpenSSL = "^24.0"
+
+[tool.poetry.dev-dependencies]
+black = "^24.3"
+mypy = "^1.9"
+mypy-protobuf = "^3.0"
+types-pyOpenSSL = "^24.0"
+pytest = "^8.1"
+pytest-mock = "^3.14"
+pre-commit = "^3.7"
+flake8 = "^7.0"
+testutils = { path = "../testutils" }
+
+[build-system]
+requires = ["poetry-core>=1.9.0"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.mypy]
+ignore_missing_imports = true
+files = ["src", "tests"]
+
+
+[tool.black]
+skip-string-normalization = true
+target-version = ['py39']
+
+
+[tool.pytest.ini_options]
+addopts = [
+    "--doctest-modules",
+]
+testpaths = [
+    "tests",
+]

spiffe_tls-0.1.0/src/spiffetls/__init__.py

@@ -0,0 +1,4 @@
+from .listen import listen, ListenOptions  # noqa: F401
+from .mode import ServerTlsMode, ClientTlsMode  # noqa: F401
+from .dial import dial  # noqa: F401
+from .context import create_ssl_context  # noqa: F401

spiffe_tls-0.1.0/src/spiffetls/context.py

@@ -0,0 +1,147 @@
+"""
+(C) Copyright 2021 Hewlett Packard Enterprise Development LP
+
+Licensed under the Apache License, Version 2.0 (the "License"); you may
+not use this file except in compliance with the License. You may obtain
+a copy of the License at
+
+https://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+License for the specific language governing permissions and limitations
+under the License.
+"""
+
+import logging
+from typing import Optional, Callable
+
+from OpenSSL import SSL, crypto
+from cryptography.hazmat.primitives import serialization
+
+from spiffe import X509Source
+from spiffetls.errors import SslContextError
+
+logger = logging.getLogger(__name__)
+
+
+def create_ssl_context(
+    method: int,
+    x509_source: X509Source,
+    authorize_fn: Optional[Callable[[crypto.X509], bool]] = None,
+    verify_mode: int = SSL.VERIFY_PEER | SSL.VERIFY_FAIL_IF_NO_PEER_CERT,
+    use_system_trusted_cas=False,
+) -> SSL.Context:
+    """Configures and returns an SSL context for secure connections.
+
+    This function abstracts the complexity of configuring SSL contexts with
+    certificates provided by a X509Source, including setting up custom
+    certificate verification if needed.
+
+    Args:
+        method: SSL method to use (e.g., SSL.TLS_SERVER_METHOD).
+        x509_source: Provides the certificates and private keys.
+        authorize_fn: Optional callback for additional cert verification.
+        verify_mode: Determines the SSL certificate verification strategy.
+        use_system_trusted_cas (bool): If True, the SSL context will include the system's trusted Certificate Authorities
+        in addition to any custom certificates. Default is False.
+        to any custom certificates. Default is False.
+
+    Returns:
+        Configured SSL.Context object.
+
+    Raises:
+        SslContextError: If SSL context configuration fails.
+    """
+    ssl_context = SSL.Context(method)
+
+    try:
+        _load_certificate_chain(ssl_context, x509_source)
+        _load_ca_bundles(ssl_context, x509_source)
+
+        def verify_callback(connection, x509, errno, depth, preverify_ok):
+            if not preverify_ok:
+                return False
+            if depth == 0 and authorize_fn:
+                # Perform custom verification at the leaf certificate
+                return authorize_fn(x509)
+
+            return preverify_ok
+
+        ssl_context.set_verify(verify_mode, verify_callback)
+        x509_source.subscribe_for_updates(
+            lambda: _on_source_update(ssl_context, x509_source)
+        )
+
+        if use_system_trusted_cas:
+            ssl_context.set_default_verify_paths()
+
+    except SSL.Error as err:
+        raise SslContextError("Error setting up certificates", err) from err
+    except Exception as err:
+        raise SslContextError("Unexpected error during SSL context setup", err) from err
+
+    return ssl_context
+
+
+def _load_certificate_chain(ssl_context: SSL.Context, x509_source: X509Source):
+    """
+    Loads the certificate chain and private key into the SSL context.
+    """
+    try:
+        svid = x509_source.svid
+        encoding_type = serialization.Encoding.PEM
+        crypto_file_type = crypto.FILETYPE_PEM
+
+        # Load the leaf certificate
+        leaf_cert_pem = svid.leaf.public_bytes(encoding_type)
+        leaf_cert = crypto.load_certificate(crypto_file_type, leaf_cert_pem)
+        ssl_context.use_certificate(leaf_cert)
+
+        # Load the private key
+        private_key_pem = svid.private_key.private_bytes(
+            encoding=encoding_type,
+            format=serialization.PrivateFormat.PKCS8,
+            encryption_algorithm=serialization.NoEncryption(),
+        )
+        private_key = crypto.load_privatekey(crypto_file_type, private_key_pem)
+        ssl_context.use_privatekey(private_key)
+
+        # Ensure the private key and certificate match
+        ssl_context.check_privatekey()
+
+        # Load the rest of certificate chain
+        for cert_pem in svid.cert_chain[1:]:
+            cert = crypto.load_certificate(
+                crypto_file_type, cert_pem.public_bytes(encoding_type)
+            )
+            ssl_context.add_extra_chain_cert(cert)
+    except Exception as e:
+        raise Exception(f'Error loading certificates into SSL Context: {e}') from e
+
+
+def _load_ca_bundles(ssl_context: SSL.Context, x509_source: X509Source):
+    """
+    Loads the trusted CA certificate bundles into the SSL context.
+    """
+    try:
+        # Load trusted CA certificates
+        for bundle in x509_source.bundles:
+            for ca_cert in bundle.x509_authorities:
+                ca_cert_pem = ca_cert.public_bytes(serialization.Encoding.PEM)
+                ca_cert_obj = crypto.load_certificate(crypto.FILETYPE_PEM, ca_cert_pem)
+                ssl_context.get_cert_store().add_cert(ca_cert_obj)
+    except Exception as e:
+        raise Exception(
+            f'Error loading trusted CA certificates into SSL Context: {e}'
+        ) from e
+
+
+def _on_source_update(ssl_context: SSL.Context, x509_source: X509Source):
+    """
+    Callback function to reload certificates.
+    """
+    _load_ca_bundles(ssl_context, x509_source)
+    _load_certificate_chain(ssl_context, x509_source)
+    logger.info("Certificates updated in SSL context.")

spiffe_tls-0.1.0/src/spiffetls/dial.py

@@ -0,0 +1,84 @@
+"""
+(C) Copyright 2021 Hewlett Packard Enterprise Development LP
+
+Licensed under the Apache License, Version 2.0 (the "License"); you may
+not use this file except in compliance with the License. You may obtain
+a copy of the License at
+
+https://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+License for the specific language governing permissions and limitations
+under the License.
+"""
+
+import logging
+import socket
+from typing import Optional, Callable
+
+from OpenSSL import SSL, crypto
+
+from spiffe import X509Source
+from spiffetls.context import create_ssl_context
+from spiffetls.errors import TLSConnectionError
+from spiffetls.mode import ClientTlsMode
+
+logger = logging.getLogger(__name__)
+
+
+def dial(
+    address: str,
+    x509_source: X509Source,
+    tls_mode: ClientTlsMode = ClientTlsMode.TLS,
+    authorize_fn: Optional[Callable[[crypto.X509], bool]] = None,
+) -> SSL.Connection:
+    """
+    Establishes a secure TLS connection to a server at the specified address.
+
+    This function creates a client-side connection using certificates and keys provided by the X509Source.
+    It can optionally perform additional server certificate validations using the provided `authorize_fn`.
+
+    Args:
+        address (str): Target server address in 'host:port' format.
+        tls_mode(ClientTlsMode, optional): Client-side TLS mode. Defaults to ClientTlsMode.TLS.
+        x509_source (X509Source): Provides the client's X.509 certificates and keys.
+        authorize_fn (Callable[[crypto.X509], bool], optional): A callback for additional server
+        certificate validation. If not provided, standard certificate validation is performed.
+
+    Returns:
+        SSL.Connection: A secured connection to the server.
+
+    Raises:
+        Exception: If there's an error establishing the connection or configuring TLS context.
+    """
+
+    host, port = address.split(':')
+
+    # Configures SSL context for the client to verify the server's certificate.
+    # The client always attempts to verify the server's certificate to ensure a secure connection.
+    verify_mode = SSL.VERIFY_PEER
+    use_system_trusted_cas = True if tls_mode == ClientTlsMode.TLS_WEB else False
+
+    ssl_context = create_ssl_context(
+        SSL.TLS_CLIENT_METHOD,
+        x509_source,
+        authorize_fn,
+        verify_mode,
+        use_system_trusted_cas,
+    )
+
+    sock = socket.socket()
+    conn = SSL.Connection(ssl_context, sock)
+
+    try:
+        conn.connect((host, int(port)))
+        conn.do_handshake()
+        return conn
+    except SSL.Error as ssl_error:
+        raise TLSConnectionError(
+            "TLS connection failed", address=address, reason=str(ssl_error)
+        ) from ssl_error
+    except socket.error as sock_error:
+        raise ConnectionError(f"Socket connection failed: {sock_error}") from sock_error

spiffe_tls-0.1.0/src/spiffetls/errors.py

@@ -0,0 +1,57 @@
+"""
+(C) Copyright 2021 Hewlett Packard Enterprise Development LP
+
+Licensed under the Apache License, Version 2.0 (the "License"); you may
+not use this file except in compliance with the License. You may obtain
+a copy of the License at
+
+https://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+License for the specific language governing permissions and limitations
+under the License.
+"""
+
+from typing import Optional
+
+from spiffe.errors import PySpiffeError
+
+
+class SslContextError(PySpiffeError):
+    """
+    Represents errors that occur during SSL context configuration.
+
+    Attributes:
+        detail (str): Detailed error message.
+        cause (Exception, optional): The original exception that caused this error.
+    """
+
+    def __init__(self, detail: str, cause: Optional[Exception] = None) -> None:
+        message = f"SSL context configuration failed: {detail}"
+        if cause:
+            message += f". Cause: {cause}"
+        super().__init__(message)
+        self.cause = cause
+
+
+class TLSConnectionError(PySpiffeError):
+    """Exception raised for errors during TLS connection setup."""
+
+    def __init__(self, message, **context):
+        super().__init__(message)
+        self.context = context
+
+
+class ListenError(Exception):
+    """Exception raised when a listening socket cannot be created."""
+
+    def __init__(self, host, port, original_error):
+        self.host = host
+        self.port = port
+        self.original_error = original_error
+        message = (
+            f"Failed to create listening socket on {host}:{port}: {original_error}"
+        )
+        super().__init__(message)

spiffe_tls-0.1.0/src/spiffetls/listen.py

@@ -0,0 +1,127 @@
+"""
+(C) Copyright 2021 Hewlett Packard Enterprise Development LP
+
+Licensed under the Apache License, Version 2.0 (the "License"); you may
+not use this file except in compliance with the License. You may obtain
+a copy of the License at
+
+https://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+License for the specific language governing permissions and limitations
+under the License.
+"""
+
+import socket
+import logging
+from typing import Callable, Optional
+
+from OpenSSL import SSL, crypto
+
+from spiffe import X509Source
+from spiffetls.context import create_ssl_context
+from spiffetls.errors import ListenError
+from spiffetls.mode import ServerTlsMode
+
+logger = logging.getLogger(__name__)
+
+
+class ListenOptions:
+    """
+    Configuration options for creating a TLS listening socket with the listen function.
+
+    Attributes:
+        tls_mode (ServerTlsMode): Serveer-side TLS mode. Defaults to ServerTlsMode.TLS.
+        authentication only, MTLS for mutual authentication, and MTLS_WEB for mutual authentication with system trusted CAs.
+        authorize_fn (Callable[[crypto.X509], bool], optional): Optional callback function for additional client
+        certificate verification.
+        backlog (int): Maximum number of queued connections. Default is 5.
+        socket_family (int): Socket family. Default is socket.AF_INET.
+        socket_type (int): Socket type. Default is socket.SOCK_STREAM.
+
+    This class allows for customization of the listening socket and SSL context behavior, including SSL mode, authorization function, and socket characteristics.
+    """
+
+    def __init__(
+        self,
+        tls_mode: ServerTlsMode = ServerTlsMode.MTLS,
+        authorize_fn: Optional[Callable[[crypto.X509], bool]] = None,
+        backlog: int = 5,
+        socket_family: int = socket.AF_INET,
+        socket_type: int = socket.SOCK_STREAM,
+    ):
+        self.tls_mode = tls_mode
+        self.authorize_fn = authorize_fn
+        self.backlog = backlog
+        self.socket_family = socket_family
+        self.socket_type = socket_type
+
+
+def listen(
+    address: str, x509_source: X509Source, options: Optional[ListenOptions] = None
+) -> SSL.Connection:
+    """
+    Creates a TLS listening socket bound to the specified address.
+
+    Args:
+        address (str): The address to bind the server to, formatted as 'host:port'.
+        x509_source (X509Source): Source of X.509 certificates and private key for TLS configuration.
+        options (ListenOptions, optional): Optional configuration options for the server. Defaults to None.
+
+    Returns:
+        SSL.Connection: A configured SSL connection wrapped around a listening socket.
+
+    This function sets up a server socket to listen for incoming TLS connections based on the provided X.509 source.
+    """
+
+    if options is None:
+        options = ListenOptions()
+
+    host, port = _parse_address(address)
+
+    # For mTLS, require the client to present a certificate and fail if no certificate is presented.
+    # For TLS, verify the peer's certificate if presented but do not require a client certificate.
+    verify_mode = (
+        SSL.VERIFY_PEER | SSL.VERIFY_FAIL_IF_NO_PEER_CERT
+        if options.tls_mode in (ServerTlsMode.MTLS, ServerTlsMode.MTLS_WEB)
+        else SSL.VERIFY_PEER
+    )
+    use_system_trusted_cas = (
+        True if options.tls_mode == ServerTlsMode.MTLS_WEB else False
+    )
+
+    ssl_context = create_ssl_context(
+        SSL.TLS_SERVER_METHOD,
+        x509_source,
+        options.authorize_fn,
+        verify_mode,
+        use_system_trusted_cas,
+    )
+
+    sock = None
+    try:
+        sock = socket.socket(options.socket_family, options.socket_type)
+        sock.bind((host, int(port)))
+        sock.listen(options.backlog)
+    except socket.error as err:
+        if sock:
+            sock.close()
+        raise ListenError(host, port, err) from err
+
+    ssl_connection = SSL.Connection(ssl_context, sock)
+    ssl_connection.set_accept_state()
+
+    return ssl_connection
+
+
+def _parse_address(address):
+    try:
+        host, port_str = address.split(':')
+        port = int(port_str)
+        return host, port
+    except ValueError:
+        raise ValueError(
+            f"Invalid address format or port number: '{address}'. Format should be 'host:port'."
+        )

spiffe_tls-0.1.0/src/spiffetls/mode.py

@@ -0,0 +1,59 @@
+"""
+(C) Copyright 2021 Hewlett Packard Enterprise Development LP
+
+Licensed under the Apache License, Version 2.0 (the "License"); you may
+not use this file except in compliance with the License. You may obtain
+a copy of the License at
+
+https://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+License for the specific language governing permissions and limitations
+under the License.
+"""
+
+from enum import Enum, auto
+
+
+class ServerTlsMode(Enum):
+    """
+    Represents the TLS modes that can be used for setting up TLS connections on the Server.
+
+    Modes:
+        TLS: The server doesn't require the client to present a TLS certificate. Use this mode for traditional TLS
+             where client authentication is not necessary. Suitable for public-facing services where client identity
+             verification is not required.
+
+        MTLS: The server requires client authentication using certificates provided by the SPIFFE Workload API. Use this
+              mode for mutual TLS (mTLS) where both server and client identities must be verified. Ideal for secure,
+              internal communication between services in a SPIFFE-enabled environment.
+
+        MTLS_WEB: Similar to MTLS, but the server also trusts certificates from the system's trust store. This mode
+                  allows for mutual TLS authentication with clients that may use well-known CA certificates. It's useful
+                  when you need to authenticate SPIFFE identities and also support clients with traditional web PKI
+                  certificates.
+    """
+
+    TLS = auto()
+    MTLS = auto()
+    MTLS_WEB = auto()
+
+
+class ClientTlsMode(Enum):
+    """
+    Represents the TLS modes that can be used for setting up TLS connections on the Client.
+
+    Modes:
+        TLS: The server is authenticated using a certificate provided by the SPIFFE Workload API. This mode ensures that
+             the client can securely communicate with a server that presents a SPIFFE identity.
+
+        TLS_WEB: The server is authenticated using certificates provided by the SPIFFE Workload API and also trusts
+                 certificates from the system's trust store. This mode supports server authentication via both
+                 SPIFFE IDs and traditional web PKI. It's suitable for clients that communicate with both SPIFFE-enabled
+                 services and standard web services.
+    """
+
+    TLS = auto()
+    TLS_WEB = auto()

spiffe_tls-0.1.0/src/spiffetls/tlsconfig/authorize.py

@@ -0,0 +1,118 @@
+"""
+(C) Copyright 2021 Hewlett Packard Enterprise Development LP
+
+Licensed under the Apache License, Version 2.0 (the "License"); you may
+not use this file except in compliance with the License. You may obtain
+a copy of the License at
+
+https://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+License for the specific language governing permissions and limitations
+under the License.
+"""
+
+import logging
+from typing import Callable, Set
+
+from OpenSSL import crypto
+
+from spiffe import SpiffeId, TrustDomain
+from spiffe.spiffe_id.spiffe_id import SCHEME_PREFIX
+from spiffe.utils.errors import X509CertificateError
+
+logger = logging.getLogger(__name__)
+
+
+def authorize_any() -> Callable[[crypto.X509], bool]:
+    """Authorizes any valid SPIFFE ID, rejects if no valid SPIFFE ID is present."""
+
+    def _authorize(cert: crypto.X509) -> bool:
+        try:
+            _spiffe_id_from_cert(cert)
+            return True
+        except X509CertificateError as e:
+            logger.error(
+                f'Failed to authorize certificate due to invalid SPIFFE ID: {e}'
+            )
+
+        return False
+
+    return _authorize
+
+
+def authorize_id(expected_spiffe_id: SpiffeId) -> Callable[[crypto.X509], bool]:
+    """Authorizes a specific SPIFFE ID."""
+
+    def _authorize(cert: crypto.X509) -> bool:
+        try:
+            spiffe_id = _spiffe_id_from_cert(cert)
+            return spiffe_id == expected_spiffe_id
+        except X509CertificateError as e:
+            logger.error(f'Failed to extract SPIFFE ID from certificate: {e}')
+
+        return False
+
+    return _authorize
+
+
+def authorize_one_of(allowed_ids: Set[SpiffeId]) -> Callable[[crypto.X509], bool]:
+    """Authorizes any SPIFFE ID in the given list of IDs."""
+
+    def _authorize(cert: crypto.X509) -> bool:
+        try:
+            spiffe_id = _spiffe_id_from_cert(cert)
+            if spiffe_id in allowed_ids:
+                return True
+            else:
+                logger.error(f"Unauthorized SPIFFE ID: {spiffe_id}")
+        except X509CertificateError as e:
+            logger.error(f"Failed to extract SPIFFE ID from certificate: {e}")
+
+        return False
+
+    return _authorize
+
+
+def authorize_member_of(
+    allowed_trust_domain: TrustDomain,
+) -> Callable[[crypto.X509], bool]:
+    """Authorizes any SPIFFE ID in the given trust domain."""
+
+    def _authorize(cert: crypto.X509) -> bool:
+        try:
+            cert_spiffe_id = _spiffe_id_from_cert(cert)
+            return cert_spiffe_id.trust_domain == allowed_trust_domain
+        except X509CertificateError as e:
+            logger.error(f'Failed to extract SPIFFE ID from certificate: {e}')
+
+        return False
+
+    return _authorize
+
+
+def _spiffe_id_from_cert(cert: crypto.X509) -> SpiffeId:
+    """Returns the SPIFFE ID from a pyOpenSSL certificate"""
+    for i in range(cert.get_extension_count()):
+        ext = cert.get_extension(i)
+        if "subjectAltName" in str(ext.get_short_name()):
+            sans = str(ext)
+            uris = [
+                uri.replace('URI:', '').strip()
+                for uri in sans.split(',')
+                if 'URI:' in uri
+            ]
+            spiffe_ids = [uri for uri in uris if uri.startswith(SCHEME_PREFIX)]
+
+            if spiffe_ids:
+                return SpiffeId(spiffe_ids[0])
+            else:
+                raise X509CertificateError(
+                    'Certificate does not contain a SPIFFE ID in the URI SAN'
+                )
+
+    raise X509CertificateError(
+        'Certificate does not contain a Subject Alternative Name extension'
+    )