nitlsconfig 1.0.0__tar.gz

nitlsconfig-1.0.0/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.0/PKG-INFO

@@ -0,0 +1,146 @@
+Metadata-Version: 2.3
+Name: nitlsconfig
+Version: 1.0.0
+Summary: Python API for reading nitlsconfig configurations and creating NI gRPC Device 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 :: 5 - Production/Stable
+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"
+Requires-Dist: pywin32 (>=306) ; (sys_platform == "win32") and (extra == "grpc")
+Project-URL: Documentation, https://nitlsconfig-python.readthedocs.io
+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 NI gRPC Device 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.
+
+## 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]`
+
+Neither install provides the `nitlsconfig` runtime itself. This package reads
+configuration by invoking the `nitlsconfig` command line interface, which ships with NI
+driver software products that support NI TLS. Install a driver that provides it before using
+this package; without it, calls raise `ExecutableNotFoundError`.
+
+## Creating a gRPC channel
+
+`create_grpc_device_channel` reads the local NI TLS client configuration for the NI
+gRPC Device Server 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_device_channel("localhost", 31763) as channel:
+    options = nidcpower.GrpcSessionOptions(channel, "")
+    with nidcpower.Session("Dev1", grpc_options=options) as session:
+        ...
+```
+
+NI driver software provides the NI TLS configuration. Using `create_grpc_device_channel`
+opts into mTLS.
+
+Before `create_grpc_device_channel` can succeed, use NI Hardware Manager to perform a
+certificate exchange with the remote system. See
+[Managing mTLS](https://www.ni.com/docs/en-US/bundle/hardwaremanager/page/mtls-manage.html)
+for details.
+
+Weakening the security posture to one-way TLS or to an insecure connection
+requires explicitly changing that configuration in NI Hardware Manager. Either way, no
+code change is needed.
+
+The channel is owned by the caller - NI driver APIs never close it.
+
+Retries are opt-in:
+
+```python
+channel = nitlsconfig.create_grpc_device_channel(
+    "localhost", 31763, retry_policy=nitlsconfig.RetryPolicy()
+)
+```
+
+`TlsConfigurationError` is raised when TLS is enabled but the configuration is
+unusable. It is always importable, since handling it does not require grpcio.
+
+`create_grpc_device_channel` and `RetryPolicy` do require grpcio; accessing them
+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)
+
+    # 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.0/README.md

@@ -0,0 +1,115 @@
+# nitlsconfig
+
+Python API that reads nitlsconfig configurations through the `nitlsconfig` command line,
+and builds NI gRPC Device 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.
+
+## 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]`
+
+Neither install provides the `nitlsconfig` runtime itself. This package reads
+configuration by invoking the `nitlsconfig` command line interface, which ships with NI
+driver software products that support NI TLS. Install a driver that provides it before using
+this package; without it, calls raise `ExecutableNotFoundError`.
+
+## Creating a gRPC channel
+
+`create_grpc_device_channel` reads the local NI TLS client configuration for the NI
+gRPC Device Server 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_device_channel("localhost", 31763) as channel:
+    options = nidcpower.GrpcSessionOptions(channel, "")
+    with nidcpower.Session("Dev1", grpc_options=options) as session:
+        ...
+```
+
+NI driver software provides the NI TLS configuration. Using `create_grpc_device_channel`
+opts into mTLS.
+
+Before `create_grpc_device_channel` can succeed, use NI Hardware Manager to perform a
+certificate exchange with the remote system. See
+[Managing mTLS](https://www.ni.com/docs/en-US/bundle/hardwaremanager/page/mtls-manage.html)
+for details.
+
+Weakening the security posture to one-way TLS or to an insecure connection
+requires explicitly changing that configuration in NI Hardware Manager. Either way, no
+code change is needed.
+
+The channel is owned by the caller - NI driver APIs never close it.
+
+Retries are opt-in:
+
+```python
+channel = nitlsconfig.create_grpc_device_channel(
+    "localhost", 31763, retry_policy=nitlsconfig.RetryPolicy()
+)
+```
+
+`TlsConfigurationError` is raised when TLS is enabled but the configuration is
+unusable. It is always importable, since handling it does not require grpcio.
+
+`create_grpc_device_channel` and `RetryPolicy` do require grpcio; accessing them
+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)
+
+    # 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.0/pyproject.toml

@@ -0,0 +1,116 @@
+[project]
+name = "nitlsconfig"
+version = "1.0.0"
+license = "MIT"
+description = "Python API for reading nitlsconfig configurations and creating NI gRPC Device client channels from them"
+authors = [{name = "NI", email = "opensource@ni.com"}]
+maintainers = [
+  {name = "Philip Thong", email = "philip.thong@emerson.com"},
+]
+readme = "README.md"
+keywords = ["nitlsconfig", "tls", "mtls", "grpc", "configuration"]
+classifiers = [
+	"Development Status :: 5 - Production/Stable",
+	"Intended Audience :: Developers",
+	"License :: OSI Approved :: MIT License",
+	"Operating System :: Microsoft :: Windows",
+	"Operating System :: POSIX",
+	"Programming Language :: Python :: 3",
+	"Programming Language :: Python :: 3.9",
+	"Programming Language :: Python :: 3.10",
+	"Programming Language :: Python :: 3.11",
+	"Programming Language :: Python :: 3.12",
+	"Programming Language :: Python :: 3.13",
+	"Programming Language :: Python :: 3.14",
+]
+requires-python = ">=3.9"
+dynamic = ["dependencies"]
+
+# Reading NI TLS configuration is pure Python. Only nitlsconfig.grpc_channel
+# needs grpcio, so the binary wheel is opt-in. pywin32 rides along with it
+# because audit records are only produced when a channel is created, and the
+# Windows Event Log logging handler cannot be written to without it.
+[project.optional-dependencies]
+grpc = ["grpcio>=1.49.0,<2.0", "pywin32>=306; sys_platform == 'win32'"]
+
+[project.urls]
+repository = "https://github.com/ni/nitlsconfig-python"
+documentation = "https://nitlsconfig-python.readthedocs.io"
+
+[project.scripts]
+nitlsconfig-read = "nitlsconfig.cli:nitlsconfig_main"
+
+[build-system]
+requires = ["poetry-core>=1.9.0"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.poetry]
+packages = [{ include = "nitlsconfig", from = "src" }]
+requires-poetry = '>=2.1,<3.0'
+
+[tool.poetry.dependencies]
+python = ">=3.9,<4.0"
+
+
+[tool.poetry.group.lint.dependencies]
+bandit = { version = ">=1.7", extras = ["toml"] }
+ni-python-styleguide = ">=0.4.1"
+mypy = ">=1.0"
+pyright = { version = ">=1.1.400", extras = ["nodejs"] }
+
+[tool.poetry.group.test.dependencies]
+pytest = [
+  { version = ">=7.2", python = "<3.10" },
+  { version = ">=9.1.1", python = ">=3.10" },
+]
+pytest-cov = ">=4.0"
+pytest-mock = ">=3.0"
+pytest-env = ">=1.0,<2.0"
+cryptography = ">=41.0"
+
+[tool.poetry.group.docs]
+optional = true
+
+[tool.poetry.group.docs.dependencies]
+# The latest Sphinx requires a recent Python version.
+Sphinx = [
+  { version = ">=8.1", python = ">=3.10,<3.11" },
+  { version = ">=8.2", python = "^3.11" },
+]
+sphinx-rtd-theme = ">=1.0.0"
+sphinx-autoapi = ">=1.8.4"
+m2r2 = ">=0.3.2"
+toml = ">=0.10.2"
+
+[tool.pytest_env]
+env_files = [".env"]
+
+[tool.ni-python-styleguide]
+extend_exclude = ".tox,docs"
+application-import-names = "nitlsconfig,tests"
+
+[tool.black]
+extend-exclude = '\.tox/|docs/'
+line-length = 100
+
+[tool.mypy]
+files = "src/nitlsconfig/,tests/"
+namespace_packages = true
+strict = true
+
+[[tool.mypy.overrides]]
+# grpcio does not ship a py.typed marker.
+module = "grpc.*"
+ignore_missing_imports = true
+
+[tool.bandit]
+skips = [
+	"B101", # assert_used
+]
+
+[tool.pytest.ini_options]
+addopts = "--doctest-modules --strict-markers"
+testpaths = ["src/nitlsconfig", "tests"]
+
+[tool.pyright]
+include = ["src/", "tests/"]

nitlsconfig-1.0.0/src/nitlsconfig/__init__.py

@@ -0,0 +1,99 @@
+"""Python package to read settings from nitlsconfig and build NI gRPC Device channels from them.
+
+The gRPC names below are 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. See the project README for install options.
+"""
+
+from importlib.metadata import version
+from importlib.util import find_spec
+from typing import TYPE_CHECKING, Any
+
+from nitlsconfig.audit import audit_session_connect
+from nitlsconfig.cli import (
+    CertificateLocation,
+    ClientCertMode,
+    ClientConfig,
+    ClientServerMode,
+    LocationScheme,
+    ServerCertMode,
+    ServerClientMode,
+    ServerConfig,
+    TrustedCertificateData,
+    KnownServerData,
+)
+from nitlsconfig.errors import (
+    CommandFailedError,
+    CommandTimeoutError,
+    ExecutableNotFoundError,
+    InvalidOutputError,
+    NitlsconfigCliError,
+    NitlsconfigError,
+    TlsConfigurationError,
+    get_tls_connection_error_elaboration,
+)
+
+if TYPE_CHECKING:
+    # Imported eagerly for type checkers and editors, which do not run __getattr__.
+    from nitlsconfig.grpc_channel import (
+        RetryPolicy,
+        create_grpc_device_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 = [
+    "RetryPolicy",
+    "create_grpc_device_channel",
+]
+
+__all__ = [
+    "__version__",
+    "audit_session_connect",
+    "CertificateLocation",
+    "ClientCertMode",
+    "ClientConfig",
+    "ClientServerMode",
+    "LocationScheme",
+    "ServerCertMode",
+    "ServerClientMode",
+    "ServerConfig",
+    "NitlsconfigError",
+    "NitlsconfigCliError",
+    "ExecutableNotFoundError",
+    "CommandFailedError",
+    "CommandTimeoutError",
+    "InvalidOutputError",
+    "TlsConfigurationError",
+    "TrustedCertificateData",
+    "KnownServerData",
+    "get_tls_connection_error_elaboration",
+]
+
+# 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-1.0.0/src/nitlsconfig/_service.py

@@ -0,0 +1,12 @@
+"""The NI TLS services this package builds transports for.
+
+Only the NI gRPC Device Server is supported today. Anything else can still be
+read through :class:`~nitlsconfig.cli.ClientConfig`, but has no channel factory.
+"""
+
+from __future__ import annotations
+
+# The NI TLS registered service name for the NI gRPC Device Server: the file stem of
+# ni-grpc-device.client.caps.yml, the Event Log source, and the record tag are all this
+# one name, so records can be tied back to the configuration they describe.
+SERVICE_NAME = "ni-grpc-device"