feat: secure grpc connection

Author: RobPasMue

.gitignore

@@ -167,4 +167,7 @@ docker/*-binaries.zip
 # Ignore scripts folder
 scripts
 
+# Ignore certs folder
+certs
+
 # End of https://www.toptal.com/developers/gitignore/api/python

pyproject.toml

@@ -27,7 +27,7 @@ classifiers = [
 
 dependencies = [
   "ansys-api-discovery==1.0.9",
-  "ansys-tools-common>=0.2,<1",
+  "ansys-tools-common>=0.3,<1",
   "beartype>=0.11.0,<0.23",
   "geomdl>=5,<6",
   "grpcio>=1.35.0,<2",
@@ -97,7 +97,7 @@ tests = [
 ]
 general-all = [
   "ansys-platform-instancemanagement==1.1.2",
-  "ansys-tools-common==0.2.1",
+  "ansys-tools-common==0.3.0",
   "ansys-tools-visualization-interface==0.12.1",
   "beartype==0.22.5",
   "docker==7.1.0",

src/ansys/geometry/core/connection/client.py

@@ -48,14 +48,35 @@
     pass
 
 
-def _create_geometry_channel(target: str) -> grpc.Channel:
+def _create_geometry_channel(
+    target: str,
+    transport_mode: str | None = None,
+    uds_dir: Path | str | None = None,
+    uds_id: str | None = None,
+    certs_dir: Path | str | None = None,
+) -> grpc.Channel:
     """Create a Geometry service gRPC channel.
 
     Parameters
     ----------
     target : str
         Target of the channel. This is usually a string in the form of
         ``host:port``.
+    transport_mode : str | None
+        Transport mode selected, by default `None` and thus it will be selected
+        for you based on the connection criteria. Options are: "insecure", "uds", "wnua", "mtls"
+    uds_dir : Path | str | None
+        Directory to use for Unix Domain Sockets (UDS) transport mode.
+        By default `None` and thus it will use the "~/.conn" folder.
+    uds_id : str | None
+        Optional ID to use for the UDS socket filename.
+        By default `None` and thus it will use "aposdas_socket.sock".
+        Otherwise, the socket filename will be "aposdas_socket-<uds_id>.sock".
+    certs_dir : Path | str | None
+        Directory to use for TLS certificates.
+        By default `None` and thus search for the "ANSYS_GRPC_CERTIFICATES" environment variable.
+        If not found, it will use the "certs" folder assuming it is in the current working
+        directory.
 
     Returns
     -------
@@ -66,16 +87,38 @@ def _create_geometry_channel(target: str) -> grpc.Channel:
     -----
     Contains specific options for the Geometry service.
     """
-    return grpc.insecure_channel(
-        target,
-        options=[
-            ("grpc.max_receive_message_length", pygeom_defaults.MAX_MESSAGE_LENGTH),
-            ("grpc.max_send_message_length", pygeom_defaults.MAX_MESSAGE_LENGTH),
-        ],
+    from ansys.tools.common.cyberchannel import create_channel
+
+    # Split target into host and port
+    host, port = target.split(":")
+
+    # Add specific gRPC options for the Geometry service
+    grpc_options = [
+        ("grpc.max_receive_message_length", pygeom_defaults.MAX_MESSAGE_LENGTH),
+        ("grpc.max_send_message_length", pygeom_defaults.MAX_MESSAGE_LENGTH),
+    ]
+
+    # Create the channel accordingly
+    return create_channel(
+        host=host,
+        port=port,
+        transport_mode=transport_mode,
+        uds_service="aposdas_socket",
+        uds_dir=uds_dir,
+        uds_id=uds_id,
+        certs_dir=certs_dir,
+        grpc_options=grpc_options,
     )
 
 
-def wait_until_healthy(channel: grpc.Channel | str, timeout: float) -> grpc.Channel:
+def wait_until_healthy(
+    channel: grpc.Channel | str,
+    timeout: float,
+    transport_mode: str | None = None,
+    uds_dir: Path | str | None = None,
+    uds_id: str | None = None,
+    certs_dir: Path | str | None = None,
+) -> grpc.Channel:
     """Wait until a channel is healthy before returning.
 
     Parameters
@@ -93,6 +136,21 @@ def wait_until_healthy(channel: grpc.Channel | str, timeout: float) -> grpc.Chan
           is made with the remaining time.
         * If the total elapsed time exceeds the value for the ``timeout`` parameter,
           a ``TimeoutError`` is raised.
+    transport_mode : str | None
+        Transport mode selected, by default `None` and thus it will be selected
+        for you based on the connection criteria. Options are: "insecure", "uds", "wnua", "mtls"
+    uds_dir : Path | str | None
+        Directory to use for Unix Domain Sockets (UDS) transport mode.
+        By default `None` and thus it will use the "~/.conn" folder.
+    uds_id : str | None
+        Optional ID to use for the UDS socket filename.
+        By default `None` and thus it will use "aposdas_socket.sock".
+        Otherwise, the socket filename will be "aposdas_socket-<uds_id>.sock".
+    certs_dir : Path | str | None
+        Directory to use for TLS certificates.
+        By default `None` and thus search for the "ANSYS_GRPC_CERTIFICATES" environment variable.
+        If not found, it will use the "certs" folder assuming it is in the current working
+        directory.
 
     Returns
     -------
@@ -115,7 +173,15 @@ def wait_until_healthy(channel: grpc.Channel | str, timeout: float) -> grpc.Chan
     while time.time() < t_max:
         try:
             tmp_channel = (
-                _create_geometry_channel(channel) if channel_creation_required else channel
+                _create_geometry_channel(
+                    channel,
+                    transport_mode=transport_mode,
+                    uds_dir=uds_dir,
+                    uds_id=uds_id,
+                    certs_dir=certs_dir,
+                )
+                if channel_creation_required
+                else channel
             )
             health_stub = health_pb2_grpc.HealthStub(tmp_channel)
             request = health_pb2.HealthCheckRequest(service="")
@@ -179,6 +245,21 @@ class GrpcClient:
     proto_version : str | None, default: None
         Protocol version to use for communication with the server. If None, v0 is used.
         Available versions are "v0", "v1", etc.
+    transport_mode : str | None
+        Transport mode selected, by default `None` and thus it will be selected
+        for you based on the connection criteria. Options are: "insecure", "uds", "wnua", "mtls"
+    uds_dir : Path | str | None
+        Directory to use for Unix Domain Sockets (UDS) transport mode.
+        By default `None` and thus it will use the "~/.conn" folder.
+    uds_id : str | None
+        Optional ID to use for the UDS socket filename.
+        By default `None` and thus it will use "aposdas_socket.sock".
+        Otherwise, the socket filename will be "aposdas_socket-<uds_id>.sock".
+    certs_dir : Path | str | None
+        Directory to use for TLS certificates.
+        By default `None` and thus search for the "ANSYS_GRPC_CERTIFICATES" environment variable.
+        If not found, it will use the "certs" folder assuming it is in the current working
+        directory.
     """
 
     @check_input_types
@@ -194,6 +275,10 @@ def __init__(
         logging_level: int = logging.INFO,
         logging_file: Path | str | None = None,
         proto_version: str | None = None,
+        transport_mode: str | None = None,
+        uds_dir: Path | str | None = None,
+        uds_id: str | None = None,
+        certs_dir: Path | str | None = None,
     ):
         """Initialize the ``GrpcClient`` object."""
         self._closed = False
@@ -208,7 +293,19 @@ def __init__(
             self._channel = wait_until_healthy(channel, self._grpc_health_timeout)
         else:
             self._target = f"{host}:{port}"
-            self._channel = wait_until_healthy(self._target, self._grpc_health_timeout)
+            self._channel = wait_until_healthy(
+                self._target,
+                self._grpc_health_timeout,
+                transport_mode=transport_mode,
+                uds_dir=uds_dir,
+                uds_id=uds_id,
+                certs_dir=certs_dir,
+            )
+
+            # HACK: If we are using UDS, the target needs to be updated to reflect
+            # the actual socket file being used.
+            if transport_mode == "uds":
+                self._target = self._channel._channel.target().decode()
 
         # Initialize the gRPC services
         self._services = _GRPCServices(self._channel, version=proto_version)

src/ansys/geometry/core/connection/docker_instance.py

@@ -24,6 +24,7 @@
 from enum import Enum
 from functools import wraps
 import os
+from pathlib import Path
 from typing import Optional
 
 from beartype import beartype as check_input_types
@@ -37,6 +38,7 @@
 except ModuleNotFoundError:  # pragma: no cover
     _HAS_DOCKER = False
 
+from ansys.tools.common.cyberchannel import verify_transport_mode
 import ansys.geometry.core.connection.defaults as pygeom_defaults
 from ansys.geometry.core.logger import LOG
 
@@ -106,6 +108,14 @@ class LocalDockerInstance:
         in which case the ``LocalDockerInstance`` class identifies the OS of your
         Docker engine and deploys the latest version of the Geometry service for that
         OS.
+    transport_mode : str | None
+        Transport mode selected, by default `None` and thus it will be selected
+        for you based on the connection criteria. Options are: "insecure", "mtls"
+    certs_dir : Path | str | None
+        Directory to use for TLS certificates.
+        By default `None` and thus search for the "ANSYS_GRPC_CERTIFICATES" environment variable.
+        If not found, it will use the "certs" folder assuming it is in the current working
+        directory.
     """
 
     __DOCKER_CLIENT__: "DockerClient" = None
@@ -164,6 +174,8 @@ def __init__(
         restart_if_existing_service: bool = False,
         name: str | None = None,
         image: GeometryContainers | None = None,
+        transport_mode: str | None = None,
+        certs_dir: Path | str | None = None,
     ) -> None:
         """``LocalDockerInstance`` constructor."""
         # Initialize instance variables
@@ -190,7 +202,13 @@ def __init__(
         #
         # First, check if the port is available... otherwise raise error
         if port_available:
-            self._deploy_container(port=port, name=name, image=image)
+            self._deploy_container(
+                port=port,
+                name=name,
+                image=image,
+                transport_mode=transport_mode,
+                certs_dir=certs_dir,
+            )
         else:
             raise RuntimeError(f"Geometry service cannot be deployed on port {port}")
 
@@ -245,7 +263,14 @@ def _is_cont_geom_service(self, cont: "Container") -> bool:
         # If you have reached this point, the image is not a Geometry service
         return False  # pragma: no cover
 
-    def _deploy_container(self, port: int, name: str | None, image: GeometryContainers | None):
+    def _deploy_container(
+        self,
+        port: int,
+        name: str | None,
+        image: GeometryContainers | None,
+        transport_mode: str | None,
+        certs_dir: Path | str | None,
+    ) -> None:
         """Handle the deployment of a Geometry service.
 
         Parameters
@@ -258,6 +283,14 @@ def _deploy_container(self, port: int, name: str | None, image: GeometryContaine
         image : GeometryContainers or None
             Geometry service Docker container image to be used. If ``None``, the
             latest container version matching
+        transport_mode : str | None
+            Transport mode selected, by default `None` and thus it will be selected
+            for you based on the connection criteria. Options are: "insecure", "mtls"
+        certs_dir : Path | str | None
+            Directory to use for TLS certificates.
+            By default `None` and thus search for the "ANSYS_GRPC_CERTIFICATES" environment
+            variable. If not found, it will use the "certs" folder assuming it is in the
+            current working directory.
 
         Raises
         ------
@@ -292,6 +325,37 @@ def _deploy_container(self, port: int, name: str | None, image: GeometryContaine
                 "No license server provided... Store its value under the following env variable: ANSRV_GEO_LICENSE_SERVER."  # noqa: E501
             )
 
+        # Verify the transport mode
+        if transport_mode:
+            verify_transport_mode(transport_mode, "remote")
+        else:
+            # Default to "mtls" if possible
+            transport_mode = "mtls"
+            LOG.info(f"No transport mode provided. Defaulting to '{transport_mode}'")
+
+        # Create the shared volume if mtls is selected
+        volumes = None
+        if transport_mode == "mtls":
+            # Share the certificates directory if needed
+            if certs_dir is None:
+                certs_dir_env = os.getenv("ANSYS_GRPC_CERTIFICATES", None)
+                if certs_dir_env is not None:
+                    certs_dir = certs_dir_env
+                else:
+                    certs_dir = Path.cwd() / "certs"
+
+            if not Path(certs_dir).is_dir():  # pragma: no cover
+                raise RuntimeError(
+                    "Transport mode 'mtls' was selected, but the expected"
+                    f" certificates directory does not exist: {certs_dir}"
+                )
+            volumes = {
+                str(Path(certs_dir).resolve()): {
+                    "bind": "/certs" if image.value[1] == "linux" else "C:/certs",
+                    "mode": "ro",
+                }
+            }
+
         # Try to deploy it
         try:
             container: Container = self.docker_client().containers.run(
@@ -300,12 +364,17 @@ def _deploy_container(self, port: int, name: str | None, image: GeometryContaine
                 auto_remove=True,
                 name=name,
                 ports={"50051/tcp": port},
+                volumes=volumes,
                 environment={
                     "LICENSE_SERVER": license_server,
                     "LOG_LEVEL": os.getenv("ANSRV_GEO_LOG_LEVEL", 2),
                     "ENABLE_TRACE": os.getenv("ANSRV_GEO_ENABLE_TRACE", 0),
                     "USE_DEBUG_MODE": os.getenv("ANSRV_GEO_USE_DEBUG_MODE", 0),
+                    "ANSYS_GRPC_CERTIFICATES": "/certs"
+                    if image.value[1] == "linux"
+                    else "C:/certs",
                 },
+                command=f"--transport-mode={transport_mode}",
             )
         except ImageNotFound:  # pragma: no cover
             raise RuntimeError(