nitlsconfig 1.0.0a1__py3-none-any.whl

nitlsconfig/__init__.py

@@ -0,0 +1,97 @@
+"""Python package to read settings from nitlsconfig and build connections from them.
+
+Reading configuration is pure Python and has no third-party dependencies. The
+gRPC channel factory needs grpcio, which is an optional extra::
+
+    pip install nitlsconfig[grpc]
+
+The gRPC names below are therefore resolved lazily: importing this package never
+imports grpcio, so a caller that only reads NI-TLS configuration does not pay
+for a binary dependency it will not use. Additional transports can be added the
+same way without changing what a bare install requires.
+"""
+
+from importlib.metadata import version
+from importlib.util import find_spec
+from typing import TYPE_CHECKING, Any
+
+from nitlsconfig.cli import (
+    CertificateLocation,
+    ClientCertMode,
+    ClientConfig,
+    ClientServerMode,
+    CommandFailedError,
+    ExecutableNotFoundError,
+    InvalidOutputError,
+    LocationScheme,
+    NitlsconfigCliError,
+    ServerCertMode,
+    ServerClientMode,
+    ServerConfig,
+    TrustedCertificateData,
+    KnownServerData,
+)
+
+if TYPE_CHECKING:
+    # Imported eagerly for type checkers and editors, which do not run __getattr__.
+    from nitlsconfig.grpc_channel import (
+        DEFAULT_SERVICE_NAME,
+        RetryPolicy,
+        TlsConfigurationError,
+        create_grpc_client_channel,
+    )
+
+__version__ = version("nitlsconfig")
+
+# Names re-exported from nitlsconfig.grpc_channel, which requires grpcio.
+# A plain list literal, because pyright only tracks __all__ through a small set
+# of literal forms; anything computed makes it give up on the export list.
+_GRPC_EXPORTS = [
+    "DEFAULT_SERVICE_NAME",
+    "RetryPolicy",
+    "TlsConfigurationError",
+    "create_grpc_client_channel",
+]
+
+__all__ = [
+    "__version__",
+    "CertificateLocation",
+    "ClientCertMode",
+    "ClientConfig",
+    "ClientServerMode",
+    "LocationScheme",
+    "ServerCertMode",
+    "ServerClientMode",
+    "ServerConfig",
+    "NitlsconfigCliError",
+    "ExecutableNotFoundError",
+    "CommandFailedError",
+    "InvalidOutputError",
+    "TrustedCertificateData",
+    "KnownServerData",
+]
+
+# The gRPC names are public API, but only on an install that can supply them.
+# Listing them unconditionally would make `from nitlsconfig import *` raise
+# ImportError without the grpc extra, since star-import resolves every name in
+# __all__. find_spec only locates grpcio; it does not import it, so the lazy
+# __getattr__ below still decides when grpcio is actually loaded.
+if find_spec("grpc") is not None:
+    # pyright only tracks __all__ through inline literals, so it cannot follow
+    # this and warns that the export list may be incomplete. The TYPE_CHECKING
+    # block above already declares these names for static consumers.
+    __all__ += _GRPC_EXPORTS  # pyright: ignore[reportUnsupportedDunderAll]
+
+
+def __getattr__(name: str) -> Any:
+    """Resolve gRPC exports on first use, so importing this package does not need grpcio."""
+    if name in _GRPC_EXPORTS:
+        try:
+            from nitlsconfig import grpc_channel
+        except ImportError as exc:  # pragma: no cover - requires an install without the extra
+            raise ImportError(
+                f"nitlsconfig.{name} requires grpcio, which is not installed. "
+                "Install it with: pip install nitlsconfig[grpc]"
+            ) from exc
+        return getattr(grpc_channel, name)
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

nitlsconfig/cli.py

@@ -0,0 +1,653 @@
+"""Read-only configuration from nitlsconfig."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import pathlib
+import platform
+import subprocess  # nosec B404 - required to invoke the trusted nitlsconfig CLI
+import sys
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any, Optional, Tuple, TypeVar
+
+ALLOWED_SCOPES: Tuple[str, ...] = ("client", "server")
+
+NITLSCONFIG_CLI_ENV_VAR = "NITLSCONFIG_CLI"
+
+# Expected JSON root keys from nitlsconfig output.
+ROLE_TO_JSON_ROOT_KEY = {
+    "client": "client",
+    "server": "server",
+}
+
+
+# Command templates are based on nitlsconfigcli README and fixture scripts.
+LIST_COMMAND_TEMPLATE: Tuple[str, ...] = ("{role}", "list")
+
+CLIENT_BATCH_READ_COMMAND_TEMPLATE: Tuple[str, ...] = (
+    "--output-format=json",
+    "client",
+    "batch-read",
+    "conf",
+    "version",
+    "raw",
+    "display_name_en",
+    "conf",
+    "certificate_mode",
+    "conf",
+    "certificate_chain_location",
+    "conf",
+    "certificate_chain_contents",
+    "conf",
+    "certificate_key_location",
+    "conf",
+    "certificate_key_contents",
+    "conf",
+    "server_mode",
+    "conf",
+    "server_name",
+    "conf",
+    "trusted_certificates_location",
+    "conf",
+    "trusted_certificates_contents",
+)
+
+SERVER_BATCH_READ_COMMAND_TEMPLATE: Tuple[str, ...] = (
+    "--output-format=json",
+    "server",
+    "batch-read",
+    "conf",
+    "version",
+    "raw",
+    "display_name_en",
+    "conf",
+    "certificate_mode",
+    "conf",
+    "certificate_chain_location",
+    "conf",
+    "certificate_chain_contents",
+    "conf",
+    "certificate_key_location",
+    "conf",
+    "certificate_key_contents",
+    "conf",
+    "client_mode",
+    "conf",
+    "trusted_certificates_location",
+    "conf",
+    "trusted_certificates_contents",
+    "raw",
+    "trusted_certificate_location",
+    "raw",
+    "trusted_certificate_contents",
+)
+
+
+class NitlsconfigCliError(RuntimeError):
+    """Base error for nitlsconfig command invocation failures."""
+
+
+class ExecutableNotFoundError(NitlsconfigCliError):
+    """Raised when a usable nitlsconfig executable cannot be found."""
+
+
+class CommandFailedError(NitlsconfigCliError):
+    """Raised when nitlsconfig exits with a non-zero return code."""
+
+
+class InvalidOutputError(NitlsconfigCliError):
+    """Raised when command output cannot be parsed as expected."""
+
+
+class ServerCertMode(str, Enum):
+    "Server TLS certificate mode."
+
+    Disabled = "Disabled"
+    Unmanaged = "Unmanaged"
+    ManagedSelfSigned = "ManagedSelfSigned"
+    Unknown = "Unknown"
+
+
+class ServerClientMode(str, Enum):
+    "Server TLS client mode."
+
+    Disabled = "Disabled"
+    Unmanaged = "Unmanaged"
+    ManagedSelfSigned = "ManagedSelfSigned"
+    Unknown = "Unknown"
+
+
+class ClientCertMode(str, Enum):
+    "Client TLS certificate mode."
+
+    Disabled = "Disabled"
+    Unmanaged = "Unmanaged"
+    Managed = "Managed"
+    Unknown = "Unknown"
+
+
+class ClientServerMode(str, Enum):
+    "Client TLS server mode."
+
+    Disabled = "Disabled"
+    TrustedCertificates = "TrustedCertificates"
+    SkipHostnameValidation = "SkipHostnameValidation"
+    TrustAlways = "TrustAlways"
+    Unknown = "Unknown"
+
+
+class LocationScheme(str, Enum):
+    "Location scheme for certificate and key locations."
+
+    File = "File"
+    Directory = "Directory"
+    SystemDefault = "SystemDefault"
+    Unknown = "Unknown"
+
+
+@dataclass(frozen=True)
+class CertificateLocation:
+    "Typed wrapper for certificate and key locations."
+
+    scheme: LocationScheme
+    path: str = ""
+
+    @classmethod
+    def from_string(cls, value: str) -> "CertificateLocation":
+        "Parse a location string into a typed CertificateLocation object."
+        if value.startswith("File://"):
+            return cls(LocationScheme.File, value[len("File://") :])
+        if value.startswith("Directory://"):
+            return cls(LocationScheme.Directory, value[len("Directory://") :])
+        if value == "SystemDefault":
+            return cls(LocationScheme.SystemDefault, "")
+        return cls(LocationScheme.Unknown, value)
+
+    def to_string(self) -> str:
+        "Output string representation."
+        if self.scheme == LocationScheme.File:
+            return f"File://{self.path}"
+        if self.scheme == LocationScheme.Directory:
+            return f"Directory://{self.path}"
+        if self.scheme == LocationScheme.SystemDefault:
+            return "SystemDefault"
+        return self.path
+
+    def __str__(self) -> str:
+        "Auto string conversion."
+        return self.to_string()
+
+
+EnumT = TypeVar("EnumT", bound=Enum)
+
+
+def _parse_enum(value: str, enum_cls: type[EnumT], unknown_member: EnumT) -> EnumT:
+    "Parse a string value into an Enum member, returning unknown_member if not found."
+    try:
+        return enum_cls(value)
+    except ValueError:
+        return unknown_member
+
+
+@dataclass(frozen=True)
+class KnownServerData:
+    """Typed wrapper for known server objects from CLI JSON."""
+
+    raw: dict[str, Any]
+    display_name: str = field()
+    certificate_mode: ClientCertMode = field()
+    certificate_chain_location: CertificateLocation = field()
+    certificate_chain_contents: str = field()
+    certificate_key_location: CertificateLocation = field()
+    certificate_key_contents: str = field()
+    server_mode: ClientServerMode = field()
+    server_name: str = field()
+    trusted_certificates_location: CertificateLocation = field()
+    trusted_certificates_contents: str = field()
+
+    @classmethod
+    def from_json_obj(cls, obj: dict[str, Any]) -> "KnownServerData":
+        "Parse a known server object from CLI JSON into KnownServerData."
+        return cls(
+            raw=obj,
+            display_name=obj.get("display_name_en", ""),
+            certificate_mode=_parse_enum(
+                obj.get("certificate_mode", ""),
+                ClientCertMode,
+                ClientCertMode.Unknown,
+            ),
+            certificate_chain_location=CertificateLocation.from_string(
+                obj.get("certificate_chain_location", "")
+            ),
+            certificate_chain_contents=obj.get("certificate_chain_contents", ""),
+            certificate_key_location=CertificateLocation.from_string(
+                obj.get("certificate_key_location", "")
+            ),
+            certificate_key_contents=obj.get("certificate_key_contents", ""),
+            server_mode=_parse_enum(
+                obj.get("server_mode", ""),
+                ClientServerMode,
+                ClientServerMode.Unknown,
+            ),
+            server_name=obj.get("server_name", ""),
+            trusted_certificates_location=CertificateLocation.from_string(
+                obj.get("trusted_certificates_location", "")
+            ),
+            trusted_certificates_contents=obj.get("trusted_certificates_contents", ""),
+        )
+
+
+@dataclass(frozen=True)
+class TrustedCertificateData:
+    """Typed wrapper for trusted certificate objects from CLI JSON."""
+
+    raw: dict[str, Any]
+    display_name: str = field()
+    trusted_certificate_location: CertificateLocation = field()
+    trusted_certificate_contents: str = field()
+
+    @classmethod
+    def from_json_obj(cls, obj: dict[str, Any]) -> "TrustedCertificateData":
+        "Parse a trusted certificate object from CLI JSON into TrustedCertificateData."
+        return cls(
+            raw=obj,
+            display_name=obj.get("display_name_en", ""),
+            trusted_certificate_location=CertificateLocation.from_string(
+                obj.get("trusted_certificate_location", "")
+            ),
+            trusted_certificate_contents=obj.get("trusted_certificate_contents", ""),
+        )
+
+
+@dataclass(frozen=True)
+class ServiceData:
+    """Typed wrapper for service objects from CLI JSON."""
+
+    raw: dict[str, Any]
+    known_servers: list[KnownServerData] = field(default_factory=list)
+    trusted_certificates: list[TrustedCertificateData] = field(default_factory=list)
+
+    @classmethod
+    def from_json_obj(cls, obj: dict[str, Any]) -> "ServiceData":
+        "Parse a service object from CLI JSON into a typed ServiceData object."
+        known_servers_raw = obj.get("known_servers", [])
+        known_servers: list[KnownServerData] = []
+        if isinstance(known_servers_raw, list):
+            for item in known_servers_raw:
+                if isinstance(item, dict):
+                    known_servers.append(KnownServerData.from_json_obj(item))
+
+        trusted_certificates_raw = obj.get("trusted_certificates", [])
+        trusted_certificates: list[TrustedCertificateData] = []
+        if isinstance(trusted_certificates_raw, list):
+            for item in trusted_certificates_raw:
+                if isinstance(item, dict):
+                    trusted_certificates.append(TrustedCertificateData.from_json_obj(item))
+
+        return cls(raw=obj, known_servers=known_servers, trusted_certificates=trusted_certificates)
+
+    def value(self, key: str, default: str = "") -> str:
+        "Fetch value from dict with default, ensuring it is a string."
+        value = self.raw.get(key, default)
+        if isinstance(value, str):
+            return value
+        return default
+
+
+def build_list_command(role: str) -> Tuple[str, ...]:
+    """Build argv for list mode only.
+
+    This function does not include executable resolution.
+    """
+    return tuple(part.format(role=role) for part in LIST_COMMAND_TEMPLATE)
+
+
+def build_batch_read_command(role: str) -> Tuple[str, ...]:
+    """Build argv template for batch-read mode only.
+
+    The template mirrors existing fixture-generation scripts.
+    """
+    if role == "client":
+        return CLIENT_BATCH_READ_COMMAND_TEMPLATE
+    return SERVER_BATCH_READ_COMMAND_TEMPLATE
+
+
+def run_nitlsconfig_command(
+    command_args: Tuple[str, ...],
+) -> str:
+    """Run nitlsconfig command and return stdout.
+
+    This helper always invokes subprocess in shell-free argv mode.
+    """
+    executable = "nitlsconfig"
+    argv = [executable, *command_args]
+
+    try:
+        completed = subprocess.run(
+            argv,
+            capture_output=True,
+            text=True,
+            check=False,
+            timeout=30,
+        )  # nosec B603 - argv is passed shell-free and executable selection is controlled
+    except FileNotFoundError as ex:
+        fallback_root = os.environ.get(NITLSCONFIG_CLI_ENV_VAR)
+        if fallback_root and fallback_root != executable:
+            suffix = ".exe" if platform.system().lower() == "windows" else ""
+            fallback_executable = pathlib.Path(fallback_root) / f"nitlsconfig{suffix}"
+            fallback_executable_str = str(fallback_executable)
+            fallback_argv = [fallback_executable_str, *command_args]
+            try:
+                completed = subprocess.run(
+                    fallback_argv,
+                    capture_output=True,
+                    text=True,
+                    check=False,
+                    timeout=30,
+                )  # nosec B603 - argv is passed shell-free and fallback executable is explicit
+                argv = fallback_argv
+            except FileNotFoundError as fallback_ex:
+                raise ExecutableNotFoundError(
+                    "Unable to find nitlsconfig executable. "
+                    f"Tried {executable!r} and {NITLSCONFIG_CLI_ENV_VAR}={fallback_root!r}."
+                ) from fallback_ex
+        else:
+            raise ExecutableNotFoundError(
+                "Unable to find nitlsconfig executable. " f"Tried {executable!r}."
+            ) from ex
+
+    if completed.returncode != 0:
+        command_display = " ".join(argv)
+        stderr = completed.stderr.strip()
+        stdout = completed.stdout.strip()
+        details = stderr if stderr else stdout
+        raise CommandFailedError(
+            "nitlsconfig command failed "
+            f"(exit={completed.returncode}): {command_display}. "
+            f"Output: {details}"
+        )
+
+    return completed.stdout
+
+
+def run_nitlsconfig_json_command(
+    command_args: Tuple[str, ...],
+) -> Any:
+    """Run nitlsconfig command and parse stdout as JSON."""
+    stdout = run_nitlsconfig_command(
+        command_args=command_args,
+    )
+
+    try:
+        return json.loads(stdout)
+    except json.JSONDecodeError as ex:
+        snippet = stdout[:240].replace("\n", "\\n")
+        raise InvalidOutputError(
+            "Failed to parse nitlsconfig JSON output. " f"Command output starts with: {snippet!r}"
+        ) from ex
+
+
+def _list_services(scope: str) -> list[str]:
+    """List configured services for the requested scope.
+
+    Output is parsed line-by-line and normalized by stripping whitespace and
+    dropping empty lines.
+    """
+    stdout = run_nitlsconfig_command(command_args=build_list_command(scope))
+    return [line.strip() for line in stdout.splitlines() if line.strip()]
+
+
+def _read_services(scope: str) -> list[ServiceData]:
+    """Read full service configurations for the requested scope.
+
+    Parsed output preserves the original key casing and values from the CLI JSON.
+    """
+    payload = run_nitlsconfig_json_command(command_args=build_batch_read_command(scope))
+
+    if not isinstance(payload, dict):
+        raise InvalidOutputError("nitlsconfig JSON output root must be an object")
+
+    if scope not in ROLE_TO_JSON_ROOT_KEY:
+        raise InvalidOutputError(f"Unsupported scope for nitlsconfig JSON output: {scope!r}")
+
+    root_key = ROLE_TO_JSON_ROOT_KEY[scope]
+    if root_key not in payload:
+        raise InvalidOutputError(f"nitlsconfig JSON output missing expected root key: {root_key!r}")
+
+    services = payload[root_key]
+    if not isinstance(services, list):
+        raise InvalidOutputError(f"nitlsconfig JSON root key {root_key!r} must contain a list")
+
+    normalized: list[ServiceData] = []
+    for item in services:
+        if isinstance(item, dict):
+            normalized.append(ServiceData.from_json_obj(item))
+        else:
+            raise InvalidOutputError("nitlsconfig service entries must be objects")
+    return normalized
+
+
+class _BaseConfig:
+    """Shared read-only behavior for service configuration wrappers."""
+
+    _scope = ""
+
+    def __init__(self, service_name: str) -> None:
+        self.service_name = service_name
+        self._data = self._find_service_data(service_name)
+
+    @classmethod
+    def list_services(cls) -> list[str]:
+        return _list_services(cls._scope)
+
+    @classmethod
+    def _read_all(cls) -> list[ServiceData]:
+        return _read_services(cls._scope)
+
+    @classmethod
+    def _find_service_data(cls, service_name: str) -> ServiceData:
+        for item in cls._read_all():
+            if item.value("service_name") == service_name:
+                return item
+
+        # Keep behavior compatible with minimal list-only service entries.
+        if service_name in cls.list_services():
+            return ServiceData(raw={"service_name": service_name})
+
+        raise InvalidOutputError(f"Service not found: {service_name!r}")
+
+    def _value(self, key: str, default: str = "") -> str:
+        return self._data.value(key, default)
+
+    def _location(self, key: str) -> CertificateLocation:
+        return CertificateLocation.from_string(self._value(key))
+
+    @property
+    def certificate_mode_raw(self) -> str:
+        return self._value("certificate_mode")
+
+    @property
+    def certificate_chain_location_raw(self) -> str:
+        return self._value("certificate_chain_location")
+
+    @property
+    def certificate_chain_contents_raw(self) -> str:
+        return self._value("certificate_chain_contents")
+
+
+class ServerConfig(_BaseConfig):
+    """Read-only view for server-side TLS configuration."""
+
+    _scope = "server"
+
+    @property
+    def certificate_mode(self) -> ServerCertMode:
+        "Parse certificate_mode string into ServerCertMode enum, defaulting to Unknown."
+        return _parse_enum(
+            self.certificate_mode_raw,
+            ServerCertMode,
+            ServerCertMode.Unknown,
+        )
+
+    @property
+    def certificate_chain_location(self) -> CertificateLocation:
+        "Return the parsed certificate_chain_location from the service configuration."
+        return self._location("certificate_chain_location")
+
+    @property
+    def certificate_chain_contents(self) -> str:
+        "Return the raw certificate_chain_contents string from the service configuration."
+        return self._value("certificate_chain_contents")
+
+    @property
+    def certificate_key_location(self) -> CertificateLocation:
+        "Return the parsed certificate_key_location from the service configuration."
+        return self._location("certificate_key_location")
+
+    @property
+    def certificate_key_contents(self) -> str:
+        "Return the raw certificate_key_contents string from the service configuration."
+        return self._value("certificate_key_contents")
+
+    @property
+    def client_mode(self) -> ServerClientMode:
+        "Parse client_mode string into ServerClientMode enum, defaulting to Unknown."
+        return _parse_enum(
+            self._value("client_mode"),
+            ServerClientMode,
+            ServerClientMode.Unknown,
+        )
+
+    @property
+    def trusted_certificates_location(self) -> CertificateLocation:
+        "Return the parsed trusted_certificates_location from the service configuration."
+        return self._location("trusted_certificates_location")
+
+    @property
+    def trusted_certificates_contents(self) -> str:
+        "Return the raw trusted_certificates_contents string from the service configuration."
+        return self._value("trusted_certificates_contents")
+
+    @property
+    def trusted_certificates(self) -> list[TrustedCertificateData]:
+        "Return the list of TrustedCertificateData from the service configuration."
+        return self._data.trusted_certificates
+
+    def __str__(self) -> str:
+        "Auto string conversion for debugging and display."
+        return f"ServerConfig(name={self.service_name}, certificate_mode={self.certificate_mode}, client_mode={self.client_mode})"
+
+
+class ClientConfig(_BaseConfig):
+    """Read-only view for client-side TLS configuration."""
+
+    _scope = "client"
+
+    def __init__(self, service_name: str, server_address: Optional[str] = None) -> None:
+        """Read client configuration, optionally resolved for a server address.
+
+        When ``server_address`` matches a known server, its configuration is used.
+        Otherwise, the generic service configuration remains in effect.
+        """
+        self.service_name = service_name
+        self.server_address = server_address
+        self._data = self._find_service_data(service_name)
+        # _data always contains the default service data. When server_address
+        # matches a known_servers entry, _resolved_data uses that configuration;
+        # otherwise, it retains the default service data. Client settings are read
+        # from _resolved_data.
+        self._resolved_data = self._data
+        if server_address is not None:
+            known_server = next(
+                (item for item in self._data.known_servers if item.server_name == server_address),
+                None,
+            )
+            if known_server is not None:
+                self._resolved_data = ServiceData(raw=known_server.raw)
+
+    def _value(self, key: str, default: str = "") -> str:
+        return self._resolved_data.value(key, default)
+
+    @property
+    def certificate_mode(self) -> ClientCertMode:
+        "Parse certificate_mode string into ClientCertMode enum, defaulting to Unknown."
+        return _parse_enum(
+            self.certificate_mode_raw,
+            ClientCertMode,
+            ClientCertMode.Unknown,
+        )
+
+    @property
+    def server_mode(self) -> ClientServerMode:
+        "Parse server_mode string into ClientServerMode enum, defaulting to Unknown."
+        return _parse_enum(
+            self._value("server_mode"),
+            ClientServerMode,
+            ClientServerMode.Unknown,
+        )
+
+    @property
+    def certificate_key_location(self) -> CertificateLocation:
+        "Return the parsed certificate_key_location from the service configuration."
+        return self._location("certificate_key_location")
+
+    @property
+    def certificate_key_contents(self) -> str:
+        "Return the raw certificate_key_contents string from the service configuration."
+        return self._value("certificate_key_contents")
+
+    @property
+    def known_servers(self) -> list[KnownServerData]:
+        "Return the typed known-server configurations from the service configuration."
+        return self._data.known_servers
+
+    @property
+    def certificate_chain_contents(self) -> str:
+        "Return the raw certificate_chain_contents string from the service configuration."
+        return self._value("certificate_chain_contents")
+
+    @property
+    def certificate_chain_location(self) -> CertificateLocation:
+        "Return the parsed certificate_chain_location from the service configuration."
+        return self._location("certificate_chain_location")
+
+    @property
+    def trusted_certificates_contents(self) -> str:
+        "Return the raw trusted_certificates_contents string from the service configuration."
+        return self._value("trusted_certificates_contents")
+
+    @property
+    def trusted_certificates_location(self) -> CertificateLocation:
+        "Return the parsed trusted_certificates_location from the service configuration."
+        return self._location("trusted_certificates_location")
+
+    def __str__(self) -> str:
+        "Auto string conversion for debugging and display."
+        return f"ClientConfig(name={self.service_name}, certificate_mode={self.certificate_mode})"
+
+
+def nitlsconfig_main(argv: Optional[list[str]] = None) -> int:
+    """Console entry point for read-only service listing."""
+    parser = argparse.ArgumentParser(prog="nitlsconfig-read")
+    parser.add_argument("scope", choices=ALLOWED_SCOPES)
+    parser.add_argument("command", choices=["list"], nargs="?", default="list")
+    args = parser.parse_args(argv)
+
+    try:
+        if args.command == "list":
+            config_cls = ClientConfig if args.scope == "client" else ServerConfig
+            for service in config_cls.list_services():
+                print(service)
+            return 0
+    except NitlsconfigCliError as ex:
+        print(str(ex), file=sys.stderr)
+        return 1
+
+    return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(nitlsconfig_main())

nitlsconfig/grpc_channel.py

@@ -0,0 +1,374 @@
+"""Create gRPC client channels from NI-TLS (nitlsconfig) client configuration.
+
+Reads the local NI-TLS client configuration for a service and produces a
+:class:`grpc.Channel` that is either secured with TLS/mTLS or, when TLS is not
+configured, a plain insecure channel.
+
+The resulting channel is a normal ``grpc.Channel``. It can be handed directly to
+any NI gRPC Python API, for example::
+
+    from nitlsconfig.grpc_channel import create_grpc_client_channel
+
+    channel = create_grpc_client_channel("localhost", 31763)
+    options = nidcpower.GrpcSessionOptions(channel, "")
+    with nidcpower.Session("Dev1", grpc_options=options) as session:
+        ...
+
+Channel ownership stays with the caller, matching the NI Python driver APIs,
+which never close the channel themselves. ``grpc.Channel`` is already a context
+manager, so ``with create_grpc_client_channel(...) as channel:`` works as expected.
+
+The name carries the ``grpc`` prefix because this package also re-exports the
+factory from its root, alongside any potential future non-gRPC transports.
+
+A client ``server_mode`` of ``TrustAlways`` is not currently supported and raises
+:class:`TlsConfigurationError`.
+
+A client ``server_mode`` of ``SkipHostnameValidation`` is treated exactly like
+``TrustedCertificates``: the server certificate chain is verified *and* the
+hostname is checked. gRPC's Python API exposes no way to skip only the hostname
+check: doing so requires a custom certificate verifier, which grpcio does not
+bind in Python, where the TLS surface is limited to
+``grpc.ssl_channel_credentials``. Verifying when asked not to fails closed, so
+this is safe, but a caller who sets the mode gets no relaxation of the hostname
+check.
+
+When the server certificate's CN/SAN does not match the dialed host, pass
+``grpc.ssl_target_name_override`` via ``options`` instead. That substitutes the
+name gRPC matches against the certificate; it does not disable verification.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from typing import Any, Optional, Sequence, Tuple
+
+import grpc
+
+from nitlsconfig.cli import (
+    CertificateLocation,
+    ClientCertMode,
+    ClientConfig,
+    ClientServerMode,
+    LocationScheme,
+    NitlsconfigCliError,
+)
+
+__all__ = [
+    "DEFAULT_SERVICE_NAME",
+    "RetryPolicy",
+    "TlsConfigurationError",
+    "create_grpc_client_channel",
+]
+
+# The nitlsconfig service name registered by the NI gRPC Device Server. It is
+# the file stem of ni-grpc-device.client.caps.yml, which grpc-device installs
+# into the nitlsconfig client.d directory.
+DEFAULT_SERVICE_NAME = "ni-grpc-device"
+
+# gRPC channel argument that carries a service config JSON document.
+_SERVICE_CONFIG_ARG = "grpc.service_config"
+
+ChannelOptions = Sequence[Tuple[str, Any]]
+
+
+def _format_target(server_address: str, server_port: int) -> str:
+    """Join an address and port into a gRPC target, bracketing IPv6 literals.
+
+    gRPC requires IPv6 literals in brackets: ``::1:31763`` never connects,
+    while ``[::1]:31763`` does. An unbracketed address containing a colon can
+    only be an IPv6 literal, since neither host names nor IPv4 addresses may
+    contain one.
+    """
+    if ":" in server_address and not server_address.startswith("["):
+        return f"[{server_address}]:{server_port}"
+    return f"{server_address}:{server_port}"
+
+
+class TlsConfigurationError(NitlsconfigCliError):
+    """Raised when the NI-TLS configuration was read successfully but is invalid."""
+
+    #: Shared remedy text appended to messages whose fix is to provision
+    #: certificates. Kept in one place so the guidance stays consistent with the
+    #: wording used elsewhere in the product.
+    _REMEDY = (
+        "Use NI Hardware Manager to verify that certificates are configured and "
+        "matching on both the host and remote target. Check that the remote target "
+        "has a compatible TLS enabled configuration with the host."
+    )
+
+
+@dataclass(frozen=True)
+class RetryPolicy:
+    """Client retry behavior, realized as a gRPC service config.
+
+    The mechanism and backoff algorithm are defined by gRFC A6 (gRPC Retry
+    Design); the values below are this package's defaults. Retries are opt-in:
+    gRPC configures no retry policy unless one is supplied.
+
+    The policy applies to every method, including non-idempotent ones.
+    ``UNAVAILABLE`` does not guarantee the server never processed the request,
+    so a retried operation can be applied twice. It also covers TLS handshake
+    failures, which gRPC reports as ``UNAVAILABLE``.
+    """
+
+    max_attempts: int = 5
+    initial_delay_ms: int = 100
+    max_delay_ms: int = 1000
+    backoff_multiplier: float = 2.0
+
+
+@dataclass(frozen=True)
+class _ClientTlsSettings:
+    """Validated client TLS settings, ready to be turned into channel credentials.
+
+    The trust anchor *scheme* is deliberately not carried here. gRPC consumes
+    only the in-memory PEM, and SystemDefault is already represented by empty
+    ``trusted_contents``, which :func:`_pem_bytes` maps to None. Add the scheme
+    back if a future caller needs to distinguish the two.
+    """
+
+    present_client_cert: bool
+    certificate_chain_contents: str
+    private_key_contents: str
+    trusted_contents: str
+
+
+def _milliseconds_to_duration(milliseconds: int) -> str:
+    """Format milliseconds as a gRPC duration string, e.g. 100 -> '0.100s'."""
+    milliseconds = max(milliseconds, 0)
+    return f"{milliseconds // 1000}.{milliseconds % 1000:03d}s"
+
+
+def _build_retry_service_config(policy: RetryPolicy) -> Optional[str]:
+    """Build a gRPC service config JSON document that enables retries.
+
+    Returns None when the policy asks for no retries. gRPC requires
+    maxAttempts >= 2, strictly positive backoffs, and a strictly positive
+    backoff multiplier, so anything less means "do not configure retries"
+    rather than an error.
+    """
+    if (
+        policy.max_attempts < 2
+        or policy.initial_delay_ms <= 0
+        or policy.max_delay_ms <= 0
+        or policy.backoff_multiplier <= 0
+    ):
+        return None
+
+    return json.dumps(
+        {
+            "methodConfig": [
+                {
+                    # An empty method name applies the policy to every method.
+                    "name": [{}],
+                    "retryPolicy": {
+                        "maxAttempts": policy.max_attempts,
+                        "initialBackoff": _milliseconds_to_duration(policy.initial_delay_ms),
+                        "maxBackoff": _milliseconds_to_duration(policy.max_delay_ms),
+                        "backoffMultiplier": policy.backoff_multiplier,
+                        "retryableStatusCodes": ["UNAVAILABLE"],
+                    },
+                }
+            ]
+        }
+    )
+
+
+def _apply_retry_policy(
+    options: ChannelOptions, policy: Optional[RetryPolicy]
+) -> list[Tuple[str, Any]]:
+    """Return channel options with the retry service config appended, if applicable."""
+    channel_options = list(options)
+    if policy is None:
+        return channel_options
+
+    # gRPC resolves duplicate entries by taking the first, so a caller-supplied
+    # service config already takes effect and must not be overridden.
+    if any(key == _SERVICE_CONFIG_ARG for key, _ in channel_options):
+        return channel_options
+
+    service_config = _build_retry_service_config(policy)
+    if service_config is not None:
+        channel_options.append((_SERVICE_CONFIG_ARG, service_config))
+    return channel_options
+
+
+def _require_file_scheme(
+    location: CertificateLocation, description: str, service_name: str
+) -> None:
+    """Validate that a certificate or key location is a usable File:// path.
+
+    The ni-grpc-device client capabilities declare support for the File scheme
+    only, so any other scheme is rejected rather than silently ignored.
+    """
+    if location.scheme != LocationScheme.File:
+        raise TlsConfigurationError(
+            f"Client {description} must use the File scheme for service "
+            f"{service_name!r}, got {location.scheme.value!r}."
+        )
+    if not location.path:
+        raise TlsConfigurationError(
+            f"TLS is enabled but the client {description} path is missing for "
+            f"service {service_name!r}."
+        )
+
+
+def _require_contents(contents: str, description: str, service_name: str) -> str:
+    """Validate that configured certificate material is actually present.
+
+    Empty contents mean the material could not be produced (missing, unreadable,
+    or not yet provisioned), never that the client opted out. Opting out is
+    expressed by the configuration itself: ``certificate_mode`` Disabled for the
+    client identity, and the SystemDefault scheme for trust anchors. Neither
+    reaches this check.
+    """
+    if not contents:
+        raise TlsConfigurationError(
+            f"TLS is configured for service {service_name!r} but the client "
+            f"{description} is missing on this system. {TlsConfigurationError._REMEDY}"
+        )
+    return contents
+
+
+def _load_client_tls_settings(config: ClientConfig) -> Optional[_ClientTlsSettings]:
+    """Read and validate client TLS settings, or None when TLS is not in use.
+
+    ``server_mode`` is the master switch: when it is Disabled the client uses a
+    plain connection and ``certificate_mode`` is not consulted at all.
+    """
+    service_name = config.service_name
+
+    server_mode = config.server_mode
+    if server_mode == ClientServerMode.Disabled:
+        return None
+    if server_mode == ClientServerMode.TrustAlways:
+        # ni-grpc-device.client.caps.yml declares supports_server_mode_trust_always: false,
+        # so this mode is not offered for this service.
+        raise TlsConfigurationError(
+            f"Client server_mode TrustAlways is not supported for service {service_name!r}."
+        )
+    if server_mode == ClientServerMode.Unknown:
+        raise TlsConfigurationError(f"Unsupported client server_mode for service {service_name!r}.")
+
+    # certificate_mode only decides mTLS versus one-way TLS.
+    if config.certificate_mode == ClientCertMode.Unknown:
+        raise TlsConfigurationError(
+            f"Unsupported client certificate_mode for service {service_name!r}."
+        )
+    present_client_cert = config.certificate_mode != ClientCertMode.Disabled
+
+    certificate_chain_contents = ""
+    private_key_contents = ""
+    if present_client_cert:
+        _require_file_scheme(config.certificate_chain_location, "certificate chain", service_name)
+        _require_file_scheme(config.certificate_key_location, "certificate key", service_name)
+        certificate_chain_contents = _require_contents(
+            config.certificate_chain_contents, "certificate chain", service_name
+        )
+        private_key_contents = _require_contents(
+            config.certificate_key_contents, "certificate key", service_name
+        )
+
+    # Trust anchors are always required: the client must verify the server.
+    # SystemDefault means "use the platform certificate store" and carries no
+    # contents. Every other usable scheme (File, Directory) is resolved by
+    # nitlsconfig into a single PEM bundle, so the scheme itself does not need
+    # to be special-cased here; only Unknown is rejected.
+    trusted_location = config.trusted_certificates_location
+    if trusted_location.scheme == LocationScheme.Unknown:
+        raise TlsConfigurationError(
+            f"TLS is configured for service {service_name!r} but the client trusted "
+            f"certificates location is missing or unrecognized. {TlsConfigurationError._REMEDY}"
+        )
+
+    trusted_contents = ""
+    if trusted_location.scheme != LocationScheme.SystemDefault:
+        # Any scheme other than SystemDefault names specific anchors, so they
+        # must actually be present.
+        trusted_contents = _require_contents(
+            config.trusted_certificates_contents, "trusted certificate bundle", service_name
+        )
+
+    return _ClientTlsSettings(
+        present_client_cert=present_client_cert,
+        certificate_chain_contents=certificate_chain_contents,
+        private_key_contents=private_key_contents,
+        trusted_contents=trusted_contents,
+    )
+
+
+def _pem_bytes(contents: str) -> Optional[bytes]:
+    """Encode PEM text for gRPC, mapping empty contents to None.
+
+    nitlsconfig represents the SystemDefault trust scheme as empty contents,
+    meaning "use the platform default certificate store". Python requires None
+    for that behavior: passing empty bytes would instead configure an empty
+    trust store and fail every connection.
+    """
+    return contents.encode("utf-8") if contents else None
+
+
+def _make_client_credentials(settings: _ClientTlsSettings) -> grpc.ChannelCredentials:
+    """Build channel credentials from validated client TLS settings."""
+    certificate_chain = None
+    private_key = None
+    if settings.present_client_cert:
+        certificate_chain = _pem_bytes(settings.certificate_chain_contents)
+        private_key = _pem_bytes(settings.private_key_contents)
+
+    return grpc.ssl_channel_credentials(
+        root_certificates=_pem_bytes(settings.trusted_contents),
+        private_key=private_key,
+        certificate_chain=certificate_chain,
+    )
+
+
+def create_grpc_client_channel(
+    server_address: str,
+    server_port: int,
+    service_name: str = DEFAULT_SERVICE_NAME,
+    options: ChannelOptions = (),
+    retry_policy: Optional[RetryPolicy] = None,
+) -> grpc.Channel:
+    """Create a gRPC channel to ``server_address:server_port`` using NI-TLS configuration.
+
+    Reads the NI-TLS client configuration for ``service_name`` and builds a
+    channel that verifies the server certificate and, when the configuration
+    calls for mutual TLS, also presents the client certificate. Falls back to an
+    insecure channel when the client's ``server_mode`` is Disabled, which is the
+    default until the machine is configured.
+
+    Args:
+        server_address: Host name or address of the NI gRPC Device Server. Also used
+            to resolve NI-TLS settings specific to this target. IPv6 literals may be
+            passed with or without brackets.
+        server_port: Port of the NI gRPC Device Server.
+        service_name: nitlsconfig service name to read configuration from.
+        options: gRPC channel arguments, as ``(key, value)`` pairs. Use this to
+            tune the channel, for example to raise message size limits or to set
+            ``grpc.ssl_target_name_override`` when the server certificate's
+            CN/SAN differs from the dialed host. Channel arguments cannot be
+            changed after the channel is built, so they must be supplied here.
+        retry_policy: Optional client retry configuration. When None (the
+            default) no retry service config is added and gRPC's built-in
+            behavior applies. Pass ``RetryPolicy()`` for the defaults described
+            on that class.
+
+    Returns:
+        A ``grpc.Channel`` owned by the caller. Close it when the last session
+        using it is done.
+
+    Raises:
+        TlsConfigurationError: TLS is enabled but the configuration is invalid.
+        NitlsconfigCliError: The nitlsconfig CLI could not be run or parsed.
+    """
+    target = _format_target(server_address, server_port)
+    channel_options = _apply_retry_policy(options, retry_policy)
+
+    settings = _load_client_tls_settings(ClientConfig(service_name, server_address))
+    if settings is None:
+        return grpc.insecure_channel(target, options=channel_options)
+
+    return grpc.secure_channel(target, _make_client_credentials(settings), options=channel_options)

nitlsconfig-1.0.0a1.dist-info/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2022, National Instruments Corp.
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be included
+in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

nitlsconfig-1.0.0a1.dist-info/METADATA

@@ -0,0 +1,127 @@
+Metadata-Version: 2.3
+Name: nitlsconfig
+Version: 1.0.0a1
+Summary: Python API for reading nitlsconfig configurations and creating gRPC client channels from them
+License: MIT
+Keywords: nitlsconfig,tls,mtls,grpc,configuration
+Author: NI
+Author-email: opensource@ni.com
+Maintainer: Philip Thong
+Maintainer-email: philip.thong@emerson.com
+Requires-Python: >=3.9
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX
+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
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Provides-Extra: grpc
+Requires-Dist: grpcio (>=1.49.0,<2.0) ; extra == "grpc"
+Project-URL: Repository, https://github.com/ni/nitlsconfig-python
+Description-Content-Type: text/markdown
+
+# nitlsconfig
+
+Python API that reads nitlsconfig configurations through the `nitlsconfig` command line,
+and builds gRPC client channels from them.
+
+Installed and imported as `nitlsconfig`; developed at
+[ni/nitlsconfig-python](https://github.com/ni/nitlsconfig-python).
+
+## Runtime dependencies
+
+- nitlsconfig executable, discoverable, or explicit path to NITLSCONFIG_CLI
+
+## Install
+
+Reading NI-TLS configuration is pure Python and has no third-party dependencies:
+
+- `pip install nitlsconfig`
+
+The gRPC channel factory additionally needs grpcio, which is an optional extra:
+
+- `pip install nitlsconfig[grpc]`
+
+## Creating a gRPC channel
+
+`create_grpc_client_channel` reads the local NI-TLS client configuration and returns a
+`grpc.Channel` secured accordingly. The `server_address` hostname or address is used to
+select matching target-specific NI-TLS settings. Pass the channel straight to any NI
+gRPC Python API:
+
+```python
+import nidcpower
+import nitlsconfig
+
+with nitlsconfig.create_grpc_client_channel("localhost", 31763) as channel:
+    options = nidcpower.GrpcSessionOptions(channel, "")
+    with nidcpower.Session("Dev1", grpc_options=options) as session:
+        ...
+```
+
+The channel is mutually authenticated, one-way TLS, or insecure depending on how
+the machine is configured; no code change is needed to move between them. The
+channel is owned by the caller - NI driver APIs never close it.
+
+Retries are opt-in:
+
+```python
+channel = nitlsconfig.create_grpc_client_channel(
+    "localhost", 31763, retry_policy=nitlsconfig.RetryPolicy()
+)
+```
+
+`TlsConfigurationError` is raised when TLS is enabled but the configuration is
+unusable. Accessing any of these names without the `grpc` extra installed raises
+`ImportError` telling you which extra to install.
+
+## Reading configurations
+```python
+import nitlsconfig
+
+# List configured services
+clients = nitlsconfig.ClientConfig.list_services()
+servers = nitlsconfig.ServerConfig.list_services()
+
+if clients:
+    # Read one client configuration
+    client_info = nitlsconfig.ClientConfig(clients[0])
+    print(client_info.service_name)
+    print(client_info.certificate_mode)
+    print(client_info.certificate_chain_location.scheme)
+    print(client_info.certificate_chain_location.path)
+    print(client_info.certificate_chain_contents)
+
+    # Inspect target-specific configurations
+    for known_server in client_info.known_servers:
+        print(known_server.server_name)
+        print(known_server.server_mode)
+        print(known_server.trusted_certificates_location)
+
+if servers:
+    # Read one server configuration
+    server_info = nitlsconfig.ServerConfig(servers[0])
+    print(server_info.service_name)
+    print(server_info.certificate_mode)
+    print(server_info.client_mode)
+    print(server_info.certificate_chain_location.scheme)
+    print(server_info.certificate_key_location.scheme)
+    print(server_info.trusted_certificates_location.scheme)
+    print(server_info.trusted_certificates_contents)
+    print(server_info.certificate_key_contents)
+
+    # Enumerate trusted certificates
+    for cert in server_info.trusted_certificates:
+        print(cert.display_name)
+        print(cert.trusted_certificate_location.path)
+        print(cert.trusted_certificate_contents)
+```
+
+
+

nitlsconfig-1.0.0a1.dist-info/RECORD

@@ -0,0 +1,8 @@
+nitlsconfig/__init__.py,sha256=FqybeZ-cjCILSAD8kDmUgO0XPsysodQD3YzuxB4vPko,3421
+nitlsconfig/cli.py,sha256=BEgK6cSuV_G8uKvA_4po0uGCj7X9wvbA3TIX9_hVFfY,22382
+nitlsconfig/grpc_channel.py,sha256=Lz2LEz2URM0qBd8zDiJ6_G-lsR7e_LXwhi1p51qWn20,15598
+nitlsconfig-1.0.0a1.dist-info/LICENSE,sha256=uX8bias4aiQ4jqwYI4rxj3C5l_Bqj4ZSoucMrYksQUc,1071
+nitlsconfig-1.0.0a1.dist-info/METADATA,sha256=t_oKog_zWKdqC9WFvYIqYwsaAT9cm79fupBUxji0Xr8,4373
+nitlsconfig-1.0.0a1.dist-info/WHEEL,sha256=b4K_helf-jlQoXBBETfwnf4B04YC67LOev0jo4fX5m8,88
+nitlsconfig-1.0.0a1.dist-info/entry_points.txt,sha256=ECS9TCbetbL-PDOVI_M6nErEV634U5HDhGPHilc3S_I,69
+nitlsconfig-1.0.0a1.dist-info/RECORD,,

nitlsconfig-1.0.0a1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: poetry-core 2.1.3
+Root-Is-Purelib: true
+Tag: py3-none-any

nitlsconfig-1.0.0a1.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+nitlsconfig-read=nitlsconfig.cli:nitlsconfig_main
+