rndc-python 0.1.0__py3-none-any.whl

rndc_python/__init__.py

@@ -0,0 +1,36 @@
+"""
+rndc-python - A Python client library for ISC BIND's RNDC
+
+This library provides a Python interface to ISC BIND's Remote Name Daemon Control (RNDC).
+"""
+
+__version__ = "0.1.0"
+__author__ = "David Groves"
+__email__ = "dave@fibrecat.org"
+
+# Import main classes and enums
+
+from .enums import RNDCDataType, TSIGAlgorithm
+from .exceptions import (
+    RNDCAuthenticationError,
+    RNDCConnectionError,
+    RNDCError,
+    RNDCZoneAlreadyExistsError,
+    RNDCZoneNotFoundError,
+)
+from .rndc_client import RNDCClient
+from .rndc_config import RNDCConfig, rndc_config
+
+__all__ = [
+    "__version__",
+    "RNDCClient",
+    "TSIGAlgorithm",
+    "RNDCDataType",
+    "RNDCError",
+    "RNDCAuthenticationError",
+    "RNDCConnectionError",
+    "RNDCZoneNotFoundError",
+    "RNDCZoneAlreadyExistsError",
+    "RNDCConfig",
+    "rndc_config",
+]

rndc_python/cli.py

@@ -0,0 +1,142 @@
+"""
+Command-line interface for rndc-python.
+
+Usage:
+    rndc-python-cli [options] <command>
+
+Examples:
+    rndc-python-cli status
+    rndc-python-cli reload
+    rndc-python-cli zonestatus example.com
+    rndc-python-cli --host 127.0.0.1 --port 953 status
+"""
+
+from __future__ import annotations
+
+import sys
+
+import click
+
+ALGORITHM_CHOICES = [
+    "md5",
+    "sha1",
+    "sha224",
+    "sha256",
+    "sha384",
+    "sha512",
+    "hmac-md5",
+    "hmac-sha1",
+    "hmac-sha224",
+    "hmac-sha256",
+    "hmac-sha384",
+    "hmac-sha512",
+]
+
+
+@click.command()
+@click.option(
+    "-s",
+    "--host",
+    envvar="ZPAPI_RNDC_HOST",
+    help="RNDC server hostname or IP",
+)
+@click.option(
+    "-p",
+    "--port",
+    type=int,
+    envvar="ZPAPI_RNDC_PORT",
+    help="RNDC server port",
+)
+@click.option(
+    "-a",
+    "--algorithm",
+    type=click.Choice(ALGORITHM_CHOICES, case_sensitive=False),
+    envvar="ZPAPI_RNDC_ALGORITHM",
+    help="TSIG algorithm",
+)
+@click.option(
+    "-k",
+    "--secret",
+    envvar="ZPAPI_RNDC_SECRET",
+    help="Base64-encoded RNDC secret key",
+)
+@click.option(
+    "-t",
+    "--timeout",
+    type=int,
+    envvar="ZPAPI_RNDC_TIMEOUT",
+    default=10,
+    help="Connection timeout in seconds",
+)
+@click.argument("command", nargs=-1, required=True)
+def main(
+    host: str | None,
+    port: int | None,
+    algorithm: str | None,
+    secret: str | None,
+    timeout: int,
+    command: tuple[str, ...],
+) -> None:
+    """Python client for ISC BIND's RNDC.
+
+    COMMAND is the RNDC command to execute (e.g., status, reload, zonestatus example.com).
+    """
+    # Lazy imports to avoid triggering global config at import time
+    from .rndc_client import RNDCClient
+    from .rndc_config import _parse_algorithm
+
+    # Validate required options
+    if not host:
+        raise click.ClickException("Missing --host or ZPAPI_RNDC_HOST environment variable")
+    if not port:
+        raise click.ClickException("Missing --port or ZPAPI_RNDC_PORT environment variable")
+    if not algorithm:
+        raise click.ClickException(
+            "Missing --algorithm or ZPAPI_RNDC_ALGORITHM environment variable"
+        )
+    if not secret:
+        raise click.ClickException("Missing --secret or ZPAPI_RNDC_SECRET environment variable")
+
+    # Build client kwargs
+    client_kwargs: dict = {
+        "host": host,
+        "port": port,
+        "algorithm": _parse_algorithm(algorithm),
+        "secret": secret,
+        "timeout": timeout,
+    }
+
+    # Join command parts into a single RNDC command string
+    rndc_command = " ".join(command)
+
+    try:
+        with RNDCClient(**client_kwargs) as client:
+            result = client.call(rndc_command)
+
+            # Print the response
+            if "text" in result:
+                click.echo(result["text"])
+            elif "err" in result and result["err"]:
+                raise click.ClickException(result["err"])
+            elif result:
+                # Print any other response data
+                for key, value in result.items():
+                    if key not in ("type", "result"):
+                        click.echo(f"{key}: {value}")
+
+            # Check result code if present
+            if result.get("result") and result["result"] != "0":
+                sys.exit(int(result["result"]))
+
+    except click.ClickException:
+        raise
+    except ValueError as e:
+        raise click.ClickException(f"Configuration error: {e}") from None
+    except ConnectionError as e:
+        raise click.ClickException(f"Connection error: {e}") from None
+    except Exception as e:
+        raise click.ClickException(str(e)) from None
+
+
+if __name__ == "__main__":
+    main()

rndc_python/config.py

@@ -0,0 +1,72 @@
+"""
+Configuration utilities.
+
+This module contains shared configuration functions and utilities used by both
+RNDC and DDNS configuration modules.
+"""
+
+import os
+
+from dotenv import load_dotenv
+
+
+def _load_env_file() -> None:
+    """Load environment variables from .env file if it exists."""
+    if os.path.exists(".env"):
+        load_dotenv(".env")
+
+
+def _get_required_env_var(key: str) -> str:
+    """Get required environment variable."""
+    value = os.getenv(key)
+    if value is None:
+        raise ValueError(f"Required environment variable {key} is not set")
+    return value
+
+
+def _parse_port(port_str: str) -> int:
+    """Parse port string to integer."""
+    try:
+        port = int(port_str)
+        if not (1 <= port <= 65535):
+            raise ValueError(f"Port must be between 1 and 65535, got {port}")
+        return port
+    except ValueError as e:
+        if isinstance(e, ValueError) and "Port must be between" in str(e):
+            raise
+        raise ValueError(f"Invalid port number: {port_str}") from e
+
+
+def _parse_timeout(timeout_str: str) -> int:
+    """Parse timeout string to integer."""
+    try:
+        timeout = int(timeout_str)
+        if timeout <= 0:
+            raise ValueError(f"Timeout must be positive, got {timeout}")
+        return timeout
+    except ValueError as e:
+        if isinstance(e, ValueError) and "Timeout must be positive" in str(e):
+            raise
+        raise ValueError(f"Invalid timeout value: {timeout_str}") from e
+
+
+def _parse_int_env_var(key: str, default: int) -> int:
+    """Parse integer environment variable with default value."""
+    value = os.getenv(key)
+    if value is None:
+        return default
+    try:
+        return int(value)
+    except ValueError:
+        raise ValueError(f"Invalid integer value for {key}: {value}") from None
+
+
+def _parse_float_env_var(key: str, default: float) -> float:
+    """Parse float environment variable with default value."""
+    value = os.getenv(key)
+    if value is None:
+        return default
+    try:
+        return float(value)
+    except ValueError:
+        raise ValueError(f"Invalid float value for {key}: {value}") from None

rndc_python/enums.py

@@ -0,0 +1,26 @@
+"""
+RNDC enums and constants.
+
+This module contains the enumeration classes and constants used by the RNDC protocol.
+"""
+
+import enum
+
+
+class TSIGAlgorithm(enum.IntEnum):
+    """TSIG authentication algorithms."""
+
+    MD5 = 157
+    SHA1 = 161
+    SHA224 = 162
+    SHA256 = 163
+    SHA384 = 164
+    SHA512 = 165
+
+
+class RNDCDataType(enum.IntEnum):
+    """RNDC data types for message serialization."""
+
+    RAW = 1
+    DICT = 2
+    LIST = 3

rndc_python/exceptions.py

@@ -0,0 +1,35 @@
+"""
+RNDC exceptions.
+
+This module contains custom exceptions used by the RNDC client.
+"""
+
+
+class RNDCError(Exception):
+    """Base exception for RNDC-related errors."""
+
+    pass
+
+
+class RNDCAuthenticationError(RNDCError):
+    """Raised when authentication fails."""
+
+    pass
+
+
+class RNDCConnectionError(RNDCError):
+    """Raised when connection or communication fails."""
+
+    pass
+
+
+class RNDCZoneNotFoundError(RNDCError):
+    """Raised when a zone is not found."""
+
+    pass
+
+
+class RNDCZoneAlreadyExistsError(RNDCError):
+    """Raised when a zone already exists."""
+
+    pass

rndc_python/rndc_client.py

@@ -0,0 +1,328 @@
+"""
+RNDC client implementation.
+
+This module contains the main RNDC client class for communicating with BIND DNS servers.
+"""
+
+import base64
+import ipaddress
+import logging
+import random
+import socket
+import struct
+import time
+import typing
+
+import dns
+import dns.rdataclass
+
+from . import rndc_protocol
+from .enums import TSIGAlgorithm
+from .exceptions import (
+    RNDCAuthenticationError,
+    RNDCConnectionError,
+    RNDCZoneAlreadyExistsError,
+    RNDCZoneNotFoundError,
+)
+
+logger = logging.getLogger(__name__)
+logger.setLevel(logging.DEBUG)
+
+
+class RNDCClient:
+    """RNDC client for communicating with BIND DNS servers."""
+
+    def __init__(
+        self,
+        host: str | ipaddress.IPv4Address | ipaddress.IPv6Address | None = None,
+        port: int | None = None,
+        algorithm: TSIGAlgorithm | None = None,
+        secret: str | None = None,
+        timeout: int | None = None,
+        max_retries: int | None = None,
+        retry_delay: float | None = None,
+    ) -> None:
+        """Initialize RNDC client."""
+
+        # Import here to avoid circular imports
+        from .rndc_config import rndc_config
+
+        # Use provided values or fall back to environment configuration (if available)
+        # rndc_config may be None if env vars are not set
+        if host is not None:
+            self.host = host
+        elif rndc_config is not None:
+            self.host = rndc_config.host
+        else:
+            raise ValueError("host is required (provide it or set ZPAPI_RNDC_HOST)")
+
+        if port is not None:
+            self.port = port
+        elif rndc_config is not None:
+            self.port = rndc_config.port
+        else:
+            raise ValueError("port is required (provide it or set ZPAPI_RNDC_PORT)")
+
+        if algorithm is not None:
+            self.algorithm = algorithm
+        elif rndc_config is not None:
+            self.algorithm = rndc_config.algorithm
+        else:
+            raise ValueError("algorithm is required (provide it or set ZPAPI_RNDC_ALGORITHM)")
+
+        if secret is not None:
+            self.secret = base64.b64decode(secret)
+        elif rndc_config is not None:
+            self.secret = base64.b64decode(rndc_config.secret)
+        else:
+            raise ValueError("secret is required (provide it or set ZPAPI_RNDC_SECRET)")
+
+        if timeout is not None:
+            self.timeout = timeout
+        elif rndc_config is not None:
+            self.timeout = rndc_config.timeout
+        else:
+            self.timeout = 10  # Default timeout
+
+        if max_retries is not None:
+            self.max_retries = max_retries
+        elif rndc_config is not None:
+            self.max_retries = rndc_config.max_retries
+        else:
+            self.max_retries = 3  # Default max retries
+
+        if retry_delay is not None:
+            self.retry_delay = retry_delay
+        elif rndc_config is not None:
+            self.retry_delay = rndc_config.retry_delay
+        else:
+            self.retry_delay = 1.0  # Default retry delay
+
+        # Internal state
+        self._serial = random.randint(0, 1 << 24)
+        self._nonce: str | None = None
+        self._socket: socket.socket | None = None
+
+        # Establish connection
+        self._connect()
+
+    def _connect(self) -> None:
+        """Establish connection to RNDC server and perform initial handshake."""
+        logger.info(f"Connecting to RNDC server at {self.host}:{self.port}")
+        try:
+            self._socket = socket.create_connection(
+                (str(self.host), self.port), timeout=self.timeout
+            )
+            self._nonce = None
+
+            # Perform null command to get nonce
+            response = self._command(type="null")
+            self._nonce = response["_ctrl"]["_nonce"]
+
+        except OSError as e:
+            raise RNDCConnectionError(f"Failed to connect to {self.host}:{self.port}: {e}") from e
+
+    def _ensure_connected(self) -> None:
+        """Ensure we have a valid connection, reconnecting if necessary."""
+        if self._socket is None:
+            logger.info("No socket connection, reconnecting...")
+            self._connect()
+            return
+
+        # Test if the connection is still alive by trying to get socket info
+        try:
+            # This will raise an exception if the socket is closed
+            self._socket.getpeername()
+        except OSError:
+            logger.info("Socket connection lost, reconnecting...")
+            self._socket.close()
+            self._socket = None
+            self._nonce = None
+            self._connect()
+
+    def _prepare_message(self, **kwargs: typing.Any) -> bytes:
+        """Prepare RNDC message with authentication."""
+        self._serial += 1
+        now = int(time.time())
+
+        # Build message structure
+        message = {
+            "_auth": {},
+            "_ctrl": {
+                "_ser": str(self._serial),
+                "_tim": str(now),
+                "_exp": str(now + 60),
+            },
+            "_data": kwargs,
+        }
+
+        if self._nonce is not None:
+            message["_ctrl"]["_nonce"] = self._nonce
+
+        # Serialize without auth for hashing
+        serialized = rndc_protocol.serialize_dict(message, ignore_auth=True)
+
+        # Create HMAC
+        hash_digest = rndc_protocol.create_hmac(self.secret, serialized, self.algorithm)
+        b64_hash = base64.b64encode(hash_digest)
+
+        # Add authentication
+        if self.algorithm == TSIGAlgorithm.MD5:
+            message["_auth"]["hmd5"] = struct.pack("22s", b64_hash)
+        else:
+            message["_auth"]["hsha"] = struct.pack("B88s", self.algorithm, b64_hash)
+
+        # Final serialization
+        final_msg = rndc_protocol.serialize_dict(message)
+        return struct.pack(">II", len(final_msg) + 4, 1) + final_msg
+
+    def _verify_message(self, message: dict) -> bool:
+        """Verify message authentication."""
+        if self._nonce is not None and message["_ctrl"]["_nonce"] != self._nonce:
+            return False
+
+        # Extract hash
+        auth_key = "hmd5" if self.algorithm == TSIGAlgorithm.MD5 else "hsha"
+        hash_data = message["_auth"][auth_key]
+
+        # For SHA algorithms, the first byte is the algorithm ID, followed by base64 hash
+        if self.algorithm != TSIGAlgorithm.MD5:
+            # Skip the algorithm ID byte and extract the base64 hash
+            b64_hash = hash_data[1:].rstrip(b"\x00").decode("ascii")
+        else:
+            # For MD5, it's just the base64 hash
+            b64_hash = hash_data.rstrip(b"\x00").decode("ascii")
+
+        # Pad base64 if needed
+        b64_hash += "=" * (4 - (len(b64_hash) % 4))
+
+        try:
+            remote_hash = base64.b64decode(b64_hash)
+        except Exception:
+            return False
+
+        # Verify hash
+        my_msg = rndc_protocol.serialize_dict(message, ignore_auth=True)
+        return rndc_protocol.verify_hmac(self.secret, my_msg, self.algorithm, remote_hash)
+
+    def _command(self, **kwargs: typing.Any) -> dict:
+        """Send command to RNDC server and receive response."""
+        # Ensure we have a valid connection before proceeding
+        self._ensure_connected()
+
+        if self._socket is None:
+            raise RNDCConnectionError("Not connected to RNDC server")
+
+        # Prepare and send message
+        message = self._prepare_message(**kwargs)
+        sent = self._socket.send(message)
+        if sent != len(message):
+            raise RNDCConnectionError("Failed to send complete message")
+
+        # Receive header
+        header = self._socket.recv(8)
+        if len(header) != 8:
+            raise RNDCAuthenticationError("Failed to read response header")
+
+        # Parse header
+        msg_len, version = struct.unpack(">II", header)
+        if version != 1:
+            raise NotImplementedError(f"Unsupported message version: {version}")
+
+        # Receive message body
+        msg_len -= 4  # Remove header size
+        data = self._socket.recv(msg_len, socket.MSG_WAITALL)
+        if len(data) != msg_len:
+            raise RNDCConnectionError("Failed to read complete response")
+
+        # Parse and verify message
+        parsed_msg = rndc_protocol.parse_message(data)
+        if not self._verify_message(parsed_msg):
+            raise RNDCAuthenticationError("Message authentication failed")
+
+        return parsed_msg
+
+    def call(self, command: str) -> dict[str, str]:
+        """
+        Execute RNDC command.
+
+        Args:
+            command: RNDC command string (e.g., 'status', 'reload zone example.com')
+
+        Returns:
+            Command response data with values decoded from ASCII bytes to strings
+        """
+        logger.info(f"Running command {command}")
+        response = self._command(type=command)
+        logger.info(f"Response: {response}")
+
+        # Decode response as ASCII if appropriate.
+        return {
+            k: v.decode("ascii") if isinstance(v, bytes) else v
+            for k, v in response["_data"].items()
+        }
+
+    def close(self) -> None:
+        """Close the RNDC connection."""
+        if self._socket:
+            self._socket.close()
+            self._socket = None
+
+    def __enter__(self) -> "RNDCClient":
+        """Context manager entry."""
+        return self
+
+    def __exit__(self, exc_type: typing.Any, exc_val: typing.Any, exc_tb: typing.Any) -> None:
+        """Context manager exit."""
+        self.close()
+
+    def add_zone(
+        self,
+        name: str,
+        dnsclass: dns.rdataclass.RdataClass = dns.rdataclass.IN,
+        view: str | None = None,
+        template: str | None = "primary",
+    ) -> None:
+        """Add a zone to the RNDC server."""
+        cmd = f"addzone {name} {dnsclass.name} {view or ''} {{template {template};}};"
+        result = self.call(cmd)
+
+        # Safely check if result exists and has the expected structure
+        if result.get("result") == "16" and result.get("err") == "already exists":
+            raise RNDCZoneAlreadyExistsError(f"Zone {name} already exists")
+
+    def del_zone(
+        self,
+        name: str,
+        clean: bool = False,
+        dnsclass: dns.rdataclass.RdataClass = dns.rdataclass.IN,
+        view: str | None = None,
+    ) -> None:
+        """Delete a zone from the RNDC server."""
+        suffix = f"{name} {dnsclass.name} {view or ''}"
+
+        if clean:
+            result = self.call(f"delzone -clean {suffix}")
+        else:
+            result = self.call(f"delzone {suffix}")
+
+        if result.get("result") == "20" and result.get("err") == "not found":
+            raise RNDCZoneNotFoundError(f"Zone {name} not found")
+
+    def set_trace_level(self, level: int) -> None:
+        if level < 0 or level > 99:
+            raise ValueError("Trace level must be an integer between 0 and 99")
+
+        """Set the trace level for the RNDC server."""
+        self.call(f"trace {level}")
+
+    def send_notify(
+        self,
+        zone: str,
+        view: str | None = None,
+        dnsclass: dns.rdataclass.RdataClass = dns.rdataclass.IN,
+    ) -> None:
+        """Forces server to send a notify for a zone."""
+        result = self.call(f"notify {zone} {view or ''} {dnsclass.name}")
+        if result.get("result") == "20" and result.get("err") == "not found":
+            raise RNDCZoneNotFoundError(f"Zone {zone} not found")

rndc_python/rndc_config.py

@@ -0,0 +1,91 @@
+"""
+RNDC configuration management.
+
+This module handles loading RNDC configuration from environment variables.
+Assumes .env file contains all required defaults if they aren't set in the environment.
+"""
+
+from typing import Any
+
+from .config import (
+    _get_required_env_var,
+    _load_env_file,
+    _parse_float_env_var,
+    _parse_int_env_var,
+    _parse_port,
+    _parse_timeout,
+)
+from .enums import TSIGAlgorithm
+
+
+def _parse_algorithm(algorithm_str: str) -> TSIGAlgorithm:
+    """Parse algorithm string to RNDCAlgorithm enum."""
+    algorithm_map = {
+        "md5": TSIGAlgorithm.MD5,
+        "sha1": TSIGAlgorithm.SHA1,
+        "sha224": TSIGAlgorithm.SHA224,
+        "sha256": TSIGAlgorithm.SHA256,
+        "sha384": TSIGAlgorithm.SHA384,
+        "sha512": TSIGAlgorithm.SHA512,
+    }
+    algorithm_lower_and_stripped = algorithm_str.lower().removeprefix("hmac-")
+    if algorithm_lower_and_stripped not in algorithm_map:
+        raise ValueError(f"Unsupported algorithm: {algorithm_str}")
+    return algorithm_map[algorithm_lower_and_stripped]
+
+
+class RNDCConfig:
+    """RNDC configuration loaded from environment variables."""
+
+    def __init__(
+        self,
+        host: str | None = None,
+        port: int | None = None,
+        algorithm: TSIGAlgorithm | None = None,
+        secret: str | None = None,
+        timeout: int | None = None,
+        max_retries: int | None = None,
+        retry_delay: float | None = None,
+    ) -> None:
+        _load_env_file()
+        self.host = host or _get_required_env_var("ZPAPI_RNDC_HOST")
+        self.port = port or _parse_port(_get_required_env_var("ZPAPI_RNDC_PORT"))
+        self.algorithm = algorithm or _parse_algorithm(
+            _get_required_env_var("ZPAPI_RNDC_ALGORITHM")
+        )
+        self.secret = secret or _get_required_env_var("ZPAPI_RNDC_SECRET")
+        self.timeout = timeout or _parse_timeout(_get_required_env_var("ZPAPI_RNDC_TIMEOUT"))
+        self.max_retries = max_retries or _parse_int_env_var("ZPAPI_RNDC_MAX_RETRIES", 3)
+        self.retry_delay = retry_delay or _parse_float_env_var("ZPAPI_RNDC_RETRY_DELAY", 1.0)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "host": self.host,
+            "port": self.port,
+            "algorithm": self.algorithm,
+            "secret": self.secret,
+            "timeout": self.timeout,
+            "max_retries": self.max_retries,
+            "retry_delay": self.retry_delay,
+        }
+
+    def __repr__(self) -> str:
+        return (
+            f"RNDCConfig(host='{self.host}', port={self.port}, "
+            f"algorithm={self.algorithm.name}, timeout={self.timeout}, "
+            f"max_retries={self.max_retries}, retry_delay={self.retry_delay})"
+        )
+
+
+# Global RNDC config instance (lazy - only created when env vars are available)
+def _create_default_config() -> RNDCConfig | None:
+    """Create a default config if environment variables are set."""
+    try:
+        return RNDCConfig()
+    except ValueError:
+        # Environment variables not set - return None
+        # Users should create RNDCConfig explicitly with parameters
+        return None
+
+
+rndc_config: RNDCConfig | None = _create_default_config()

rndc_python/rndc_protocol.py

@@ -0,0 +1,98 @@
+"""
+RNDC protocol implementation.
+
+This module handles the low-level RNDC protocol message serialization and deserialization.
+"""
+
+import hashlib
+import hmac
+import struct
+
+from .enums import RNDCDataType, TSIGAlgorithm
+from .exceptions import RNDCConnectionError
+
+
+def serialize_dict(data: dict, ignore_auth: bool = False) -> bytes:
+    """Serialize dictionary to RNDC message format."""
+    result = []
+
+    for key, value in data.items():
+        if ignore_auth and key == "_auth":
+            continue
+
+        result.append(chr(len(key)).encode())
+        result.append(key.encode())
+
+        if isinstance(value, str):
+            result.append(struct.pack(">BI", RNDCDataType.RAW, len(value)))
+            result.append(value.encode())
+        elif isinstance(value, bytes):
+            result.append(struct.pack(">BI", RNDCDataType.RAW, len(value)))
+            result.append(value)
+        elif isinstance(value, dict):
+            serialized = serialize_dict(value)
+            result.append(struct.pack(">BI", RNDCDataType.DICT, len(serialized)))
+            result.append(serialized)
+        else:
+            raise ValueError(f"Cannot serialize type {type(value)}")
+
+    return b"".join(result)
+
+
+def parse_element(data: bytes) -> tuple[str, bytes | dict, bytes]:
+    """Parse a single element from RNDC message."""
+    if len(data) < 2:
+        raise RNDCConnectionError("Incomplete message data")
+
+    # Parse label
+    label_len = data[0]
+    if len(data) < 1 + label_len + 5:
+        raise RNDCConnectionError("Incomplete message data")
+
+    label = data[1 : 1 + label_len].decode("utf-8")
+    pos = 1 + label_len
+
+    # Parse type and length
+    data_type = data[pos]
+    pos += 1
+    data_len = struct.unpack(">I", data[pos : pos + 4])[0]
+    pos += 4
+
+    if len(data) < pos + data_len:
+        raise RNDCConnectionError("Incomplete message data")
+
+    element_data = data[pos : pos + data_len]
+    remaining = data[pos + data_len :]
+
+    # Parse based on type
+    if data_type == RNDCDataType.RAW:
+        return label, element_data, remaining
+    elif data_type == RNDCDataType.DICT:
+        result = {}
+        while element_data:
+            sub_label, sub_value, element_data = parse_element(element_data)
+            result[sub_label] = sub_value
+        return label, result, remaining
+    else:
+        raise NotImplementedError(f"Unsupported data type: {data_type}")
+
+
+def parse_message(data: bytes) -> dict:
+    """Parse complete RNDC message."""
+    result = {}
+    while data:
+        label, value, data = parse_element(data)
+        result[label] = value
+    return result
+
+
+def create_hmac(secret: bytes, data: bytes, algorithm: TSIGAlgorithm) -> bytes:
+    """Create HMAC for message authentication."""
+    hash_algorithm = getattr(hashlib, algorithm.name.lower())
+    return hmac.new(secret, data, hash_algorithm).digest()
+
+
+def verify_hmac(secret: bytes, data: bytes, algorithm: TSIGAlgorithm, remote_hash: bytes) -> bool:
+    """Verify HMAC for message authentication."""
+    expected_hash = create_hmac(secret, data, algorithm)
+    return hmac.compare_digest(expected_hash, remote_hash)

rndc_python-0.1.0.dist-info/METADATA

@@ -0,0 +1,123 @@
+Metadata-Version: 2.4
+Name: rndc-python
+Version: 0.1.0
+Summary: Python client for ISC BIND's RNDC
+Project-URL: Homepage, https://github.com/davidgroves/rndc-python
+Project-URL: Repository, https://github.com/davidgroves/rndc-python
+Project-URL: Issues, https://github.com/davidgroves/rndc-python/issues
+Author-email: David Groves <dave@fibrecat.org>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: bind,dns,named,rndc,tsig
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+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
+Classifier: Topic :: Internet :: Name Service (DNS)
+Classifier: Topic :: System :: Systems Administration
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: click>=8.1.0
+Requires-Dist: dnspython>=2.6.1
+Requires-Dist: python-dotenv>=1.0.1
+Provides-Extra: dev
+Requires-Dist: pre-commit>=4.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.8.0; extra == 'dev'
+Requires-Dist: ty>=0.0.3; extra == 'dev'
+Provides-Extra: test
+Requires-Dist: pytest-cov>=6.0.0; extra == 'test'
+Requires-Dist: pytest-mock>=3.14.0; extra == 'test'
+Requires-Dist: pytest>=8.3.0; extra == 'test'
+Requires-Dist: testcontainers>=4.9.0; extra == 'test'
+Description-Content-Type: text/markdown
+
+# rndc-python
+
+Python client library for talking to ISC BIND's RNDC service.
+
+## Requirements
+
+- Python 3.10+
+
+## Installation
+
+```bash
+pip install rndc-python
+```
+
+Or using uv:
+
+```bash
+uv add rndc-python
+```
+
+### Command-line Interface
+
+The package includes a CLI tool `rndc-python-cli`:
+
+```bash
+# Using CLI options
+rndc-python-cli -s 127.0.0.1 -p 953 -a sha256 -k <base64-secret> status
+
+# Using environment variables
+export ZPAPI_RNDC_HOST=127.0.0.1
+export ZPAPI_RNDC_PORT=953
+export ZPAPI_RNDC_ALGORITHM=sha256
+export ZPAPI_RNDC_SECRET=<base64-secret>
+rndc-python-cli status
+
+# Mix of both (CLI options override env vars)
+rndc-python-cli --port 954 reload
+```
+
+## Configuration
+
+The client can read its settings from environment variables (or a `.env` file):
+
+- `ZPAPI_RNDC_HOST`
+- `ZPAPI_RNDC_PORT`
+- `ZPAPI_RNDC_ALGORITHM` (e.g. `hmac-sha256`)
+- `ZPAPI_RNDC_SECRET`
+- `ZPAPI_RNDC_TIMEOUT`
+- `ZPAPI_RNDC_MAX_RETRIES`
+- `ZPAPI_RNDC_RETRY_DELAY`
+
+You can also configure the client directly in Python:
+
+```python
+from rndc_python import RNDCClient, TSIGAlgorithm
+
+client = RNDCClient(
+    host="127.0.0.1",
+    port=953,
+    algorithm=TSIGAlgorithm.SHA256,
+    secret="your-base64-secret-here",
+    timeout=10,
+    max_retries=3,
+    retry_delay=2,
+)
+```
+
+All parameters are optional if you have configured environment variables or a `.env` file.
+
+## Usage
+
+### Python API
+
+```python
+from rndc_python import RNDCClient
+
+with RNDCClient() as rndc_client:
+    print(rndc_client.call("status"))
+```
+
+## Development
+
+See [DEVELOPMENT.md](DEVELOPMENT.md) for development setup, building, and testing instructions.

rndc_python-0.1.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+rndc_python/__init__.py,sha256=VC_g3KHJK1bznl6zNXZhDmhldx6yRJWC_NKMh69t2_w,830
+rndc_python/cli.py,sha256=wo6x9o5uxEwZPNy5TamFYhcn6KLVIv1eROxhzpSn1ns,3641
+rndc_python/config.py,sha256=-r4e2TWJmDib2H7SspDO_3BVnVg2yv6VVR70btZfeEw,2147
+rndc_python/enums.py,sha256=Vpo6Tled-iJXaVOIYf-1SUTk2hTO8LXRMjo0nizh7Og,439
+rndc_python/exceptions.py,sha256=JwBFkxR2Mys7m377ziT0O751V76uIFTr7g7rIlcodI0,582
+rndc_python/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+rndc_python/rndc_client.py,sha256=OKZMHa_w3SAjYAC9YTYAb6dOE1W-cZ4NLa6pL1I1Oic,11271
+rndc_python/rndc_config.py,sha256=Nwx4KeW9OdPkq0sS7N7cQk2MhJ5ompOXVYvGnWSz1zc,3179
+rndc_python/rndc_protocol.py,sha256=8A8wlQgrVgwjGIVHksY8ckejL6FV9BX2u4BjW8XiPsE,3126
+rndc_python-0.1.0.dist-info/METADATA,sha256=VTNDYqXbowcDOg1-ewfGee62l4SdNj6hTBUEdBOsY4w,3258
+rndc_python-0.1.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+rndc_python-0.1.0.dist-info/entry_points.txt,sha256=1OR-uWgBtXxPcdXqCEgQhH_5rLH1d8dVvMFV-cAwe5A,57
+rndc_python-0.1.0.dist-info/licenses/LICENSE,sha256=z_Yb9eEaKhZqB25-54B5ulb8OrLsTPE_LGsObcEMXIs,1070
+rndc_python-0.1.0.dist-info/RECORD,,

rndc_python-0.1.0.dist-info/WHEEL

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

rndc_python-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+rndc-python-cli = rndc_python.cli:main

rndc_python-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2025 David Groves
+
+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.
+