otdf-python 0.10.2__py3-none-any.whl → 0.12.0__py3-none-any.whl

otdf_python/__init__.py

@@ -0,0 +1,24 @@
+"""OpenTDF Python SDK.
+
+A Python implementation of the OpenTDF SDK for working with Trusted Data Format (TDF) files.
+Provides both programmatic APIs and command-line interface for encryption and decryption.
+"""
+
+from .cli import main as cli_main
+from .config import KASInfo, NanoTDFConfig, TDFConfig
+from .sdk import SDK
+from .sdk_builder import SDKBuilder
+
+__all__ = [
+    "SDK",
+    "KASInfo",
+    "NanoTDFConfig",
+    "SDKBuilder",
+    "TDFConfig",
+    "cli_main",
+]
+
+
+def main() -> None:
+    """Entry point for the CLI."""
+    cli_main()

otdf_python/__main__.py

@@ -0,0 +1,11 @@
+#!/usr/bin/env python3
+"""Main entry point for running otdf_python as a module.
+
+This allows the package to be run with `python -m otdf_python` and properly
+handles the CLI interface without import conflicts.
+"""
+
+from .cli import main
+
+if __name__ == "__main__":
+    main()

otdf_python/address_normalizer.py

@@ -0,0 +1,82 @@
+"""Address normalization utilities for OpenTDF."""
+
+import logging
+import re
+from urllib.parse import urlparse
+
+from .sdk_exceptions import SDKException
+
+logger = logging.getLogger(__name__)
+
+
+def normalize_address(url_string: str, use_plaintext: bool) -> str:
+    """Normalize a URL address to ensure it has the correct scheme and port.
+
+    Args:
+        url_string: The URL string to normalize
+        use_plaintext: If True, use http scheme, otherwise use https
+
+    Returns:
+        The normalized URL string
+
+    Raises:
+        SDKException: If there's an error parsing or creating the URL
+
+    """
+    scheme = "http" if use_plaintext else "https"
+
+    # Check if we have a host:port format without scheme (with non-digit port)
+    host_port_pattern = re.match(r"^([^/:]+):([^/]+)$", url_string)
+    if host_port_pattern:
+        host = host_port_pattern.group(1)
+        port_str = host_port_pattern.group(2)
+        try:
+            port = int(port_str)
+        except ValueError as err:
+            raise SDKException(f"Invalid port in URL [{url_string}]") from err
+
+        normalized_url = f"{scheme}://{host}:{port}"
+        logger.debug(f"normalized url [{url_string}] to [{normalized_url}]")
+        return normalized_url
+
+    try:
+        # Check if we just have a hostname without scheme and port
+        if "://" not in url_string and "/" not in url_string and ":" not in url_string:
+            port = 80 if use_plaintext else 443
+            normalized_url = f"{scheme}://{url_string}:{port}"
+            logger.debug(f"normalized url [{url_string}] to [{normalized_url}]")
+            return normalized_url
+
+        # Parse the URL
+        parsed_url = urlparse(url_string)
+
+        # If no scheme, add one
+        if not parsed_url.scheme:
+            url_string = f"{scheme}://{url_string}"
+            parsed_url = urlparse(url_string)
+
+        # Extract host and port
+        host = parsed_url.netloc.split(":")[0] if parsed_url.netloc else parsed_url.path
+
+        # If there's a port in the URL, try to extract it
+        port = None
+        if ":" in parsed_url.netloc:
+            _, port_str = parsed_url.netloc.split(":", 1)
+            try:
+                port = int(port_str)
+            except ValueError as err:
+                raise SDKException(f"Invalid port in URL [{url_string}]") from err
+
+        # If no port was found or extracted, use the default
+        if port is None:
+            port = 80 if use_plaintext else 443
+
+        # Reconstruct the URL with the desired scheme
+        normalized_url = f"{scheme}://{host}:{port}"
+        logger.debug(f"normalized url [{url_string}] to [{normalized_url}]")
+        return normalized_url
+
+    except Exception as e:
+        if isinstance(e, SDKException):
+            raise e
+        raise SDKException(f"Error normalizing URL [{url_string}]: {e}") from e

otdf_python/aesgcm.py

@@ -0,0 +1,70 @@
+"""AES-GCM encryption and decryption functionality."""
+
+import os
+
+from cryptography.hazmat.primitives.ciphers.aead import AESGCM
+
+
+class AesGcm:
+    """AES-GCM encryption and decryption operations."""
+
+    GCM_NONCE_LENGTH = 12
+    GCM_TAG_LENGTH = 16
+
+    def __init__(self, key: bytes):
+        """Initialize AES-GCM cipher with key."""
+        if not key or len(key) not in (16, 24, 32):
+            raise ValueError("Invalid key size for GCM encryption")
+        self.key = key
+        self.aesgcm = AESGCM(key)
+
+    def get_key(self) -> bytes:
+        return self.key
+
+    class Encrypted:
+        """Encrypted data with initialization vector and ciphertext."""
+
+        def __init__(self, iv: bytes, ciphertext: bytes):
+            """Initialize encrypted data."""
+            self.iv = iv
+            self.ciphertext = ciphertext
+
+        def as_bytes(self) -> bytes:
+            return self.iv + self.ciphertext
+
+    def encrypt(
+        self, plaintext: bytes, offset: int = 0, length: int | None = None
+    ) -> "AesGcm.Encrypted":
+        if length is None:
+            length = len(plaintext) - offset
+        iv = os.urandom(self.GCM_NONCE_LENGTH)
+        ct = self.aesgcm.encrypt(iv, plaintext[offset : offset + length], None)
+        return self.Encrypted(iv, ct)
+
+    def encrypt_with_iv(
+        self,
+        iv: bytes,
+        # Kept for signature parity with the Java SDK; the cryptography lib
+        # derives the tag length itself.
+        auth_tag_len: int,  # noqa: ARG002
+        plaintext: bytes,
+        offset: int = 0,
+        length: int | None = None,
+    ) -> bytes:
+        if length is None:
+            length = len(plaintext) - offset
+        ct = self.aesgcm.encrypt(iv, plaintext[offset : offset + length], None)
+        return iv + ct
+
+    def decrypt(self, encrypted: "AesGcm.Encrypted") -> bytes:
+        return self.aesgcm.decrypt(encrypted.iv, encrypted.ciphertext, None)
+
+    def decrypt_with_iv(
+        self,
+        iv: bytes,
+        # Kept for signature parity with the Java SDK; the cryptography lib
+        # derives the tag length itself.
+        auth_tag_len: int,  # noqa: ARG002
+        cipher_data: bytes,
+    ) -> bytes:
+        return self.aesgcm.decrypt(iv, cipher_data, None)

otdf_python/assertion_config.py

@@ -0,0 +1,105 @@
+"""Assertion configuration for TDF."""
+
+from enum import Enum, auto
+from typing import Any
+
+
+class Type(Enum):
+    """Assertion type enumeration."""
+
+    HANDLING_ASSERTION = "handling"
+    BASE_ASSERTION = "base"
+
+    def __str__(self):
+        return self.value
+
+
+class Scope(Enum):
+    """Assertion scope enumeration."""
+
+    TRUSTED_DATA_OBJ = "tdo"
+    PAYLOAD = "payload"
+
+    def __str__(self):
+        return self.value
+
+
+class AssertionKeyAlg(Enum):
+    """Assertion key algorithm enumeration."""
+
+    RS256 = auto()
+    HS256 = auto()
+    NOT_DEFINED = auto()
+
+
+class AppliesToState(Enum):
+    """Assertion applies-to state enumeration."""
+
+    ENCRYPTED = "encrypted"
+    UNENCRYPTED = "unencrypted"
+
+    def __str__(self):
+        return self.value
+
+
+class BindingMethod(Enum):
+    """Assertion binding method enumeration."""
+
+    JWS = "jws"
+
+    def __str__(self):
+        return self.value
+
+
+class AssertionKey:
+    """Assertion signing key configuration."""
+
+    def __init__(self, alg: AssertionKeyAlg, key: Any):
+        """Initialize assertion key."""
+        self.alg = alg
+        self.key = key
+
+    def is_defined(self):
+        return self.alg != AssertionKeyAlg.NOT_DEFINED
+
+
+class Statement:
+    """Assertion statement with format, schema, and value."""
+
+    def __init__(self, format: str, schema: str, value: str):
+        """Initialize assertion statement."""
+        self.format = format
+        self.schema = schema
+        self.value = value
+
+    def __eq__(self, other):
+        return (
+            isinstance(other, Statement)
+            and self.format == other.format
+            and self.schema == other.schema
+            and self.value == other.value
+        )
+
+    def __hash__(self):
+        return hash((self.format, self.schema, self.value))
+
+
+class AssertionConfig:
+    """TDF assertion configuration."""
+
+    def __init__(
+        self,
+        id: str,
+        type: Type,
+        scope: Scope,
+        applies_to_state: AppliesToState,
+        statement: Statement,
+        signing_key: AssertionKey | None = None,
+    ):
+        """Initialize assertion configuration."""
+        self.id = id
+        self.type = type
+        self.scope = scope
+        self.applies_to_state = applies_to_state
+        self.statement = statement
+        self.signing_key = signing_key

otdf_python/asym_crypto.py

@@ -0,0 +1,194 @@
+"""Asymmetric encryption and decryption utilities for RSA keys in PEM format."""
+
+import base64
+import re
+
+from cryptography.hazmat.backends import default_backend
+from cryptography.hazmat.primitives import hashes, serialization
+from cryptography.hazmat.primitives.asymmetric import padding, rsa
+from cryptography.x509 import load_pem_x509_certificate
+
+from .sdk_exceptions import SDKException
+
+
+class AsymDecryption:
+    """Provides functionality for asymmetric decryption using an RSA private key.
+
+    Supports both PEM string and key object initialization for flexibility.
+    """
+
+    CIPHER_TRANSFORM = "RSA/ECB/OAEPWithSHA-1AndMGF1Padding"
+    PRIVATE_KEY_HEADER = "-----BEGIN PRIVATE KEY-----"
+    PRIVATE_KEY_FOOTER = "-----END PRIVATE KEY-----"
+
+    def __init__(self, private_key_pem: str | None = None, private_key_obj=None):
+        """Initialize with either a PEM string or a key object.
+
+        Args:
+            private_key_pem: Private key in PEM format (with or without headers)
+            private_key_obj: Pre-loaded private key object from cryptography library
+
+        Raises:
+            SDKException: If key loading fails
+
+        """
+        if private_key_obj is not None:
+            self.private_key = private_key_obj
+        elif private_key_pem is not None:
+            try:
+                # Try direct PEM loading first (most common case)
+                try:
+                    self.private_key = serialization.load_pem_private_key(
+                        private_key_pem.encode(),
+                        password=None,
+                        backend=default_backend(),
+                    )
+                except Exception:
+                    # Fallback: strip headers and load as DER (for base64-only keys)
+                    private_key_pem = (
+                        private_key_pem.replace(self.PRIVATE_KEY_HEADER, "")
+                        .replace(self.PRIVATE_KEY_FOOTER, "")
+                        .replace("\n", "")
+                        .replace("\r", "")
+                        .replace(" ", "")
+                    )
+                    decoded = base64.b64decode(private_key_pem)
+                    self.private_key = serialization.load_der_private_key(
+                        decoded, password=None, backend=default_backend()
+                    )
+            except Exception as e:
+                raise SDKException(f"Failed to load private key: {e}") from e
+        else:
+            self.private_key = None
+
+    def decrypt(self, data: bytes) -> bytes:
+        """Decrypt data using RSA OAEP with SHA-1.
+
+        Args:
+            data: Encrypted bytes to decrypt
+
+        Returns:
+            Decrypted bytes
+
+        Raises:
+            SDKException: If decryption fails or key is not set
+
+        """
+        if self.private_key is None:
+            raise SDKException("Failed to decrypt, private key is empty")
+        try:
+            return self.private_key.decrypt(
+                data,
+                padding.OAEP(
+                    mgf=padding.MGF1(algorithm=hashes.SHA1()),
+                    algorithm=hashes.SHA1(),
+                    label=None,
+                ),
+            )
+        except Exception as e:
+            raise SDKException(f"Error performing decryption: {e}") from e
+
+
+class AsymEncryption:
+    """Provides functionality for asymmetric encryption using an RSA public key or certificate in PEM format.
+
+    Supports PEM public keys, X.509 certificates, and pre-loaded key objects.
+    Also handles base64-encoded keys without PEM headers.
+    """
+
+    PUBLIC_KEY_HEADER = "-----BEGIN PUBLIC KEY-----"
+    PUBLIC_KEY_FOOTER = "-----END PUBLIC KEY-----"
+    CIPHER_TRANSFORM = "RSA/ECB/OAEPWithSHA-1AndMGF1Padding"
+
+    def __init__(self, public_key_pem: str | None = None, public_key_obj=None):
+        """Initialize with either a PEM string or a key object.
+
+        Args:
+            public_key_pem: Public key in PEM format, X.509 certificate, or base64 string
+            public_key_obj: Pre-loaded public key object from cryptography library
+
+        Raises:
+            SDKException: If key loading fails or key is not RSA
+
+        """
+        if public_key_obj is not None:
+            self.public_key = public_key_obj
+        elif public_key_pem is not None:
+            try:
+                if "BEGIN CERTIFICATE" in public_key_pem:
+                    # Load from X.509 certificate
+                    cert = load_pem_x509_certificate(
+                        public_key_pem.encode(), default_backend()
+                    )
+                    self.public_key = cert.public_key()
+                else:
+                    # Try direct PEM loading first (most common case)
+                    try:
+                        self.public_key = serialization.load_pem_public_key(
+                            public_key_pem.encode(), backend=default_backend()
+                        )
+                    except Exception:
+                        # Fallback: strip headers and load as DER (for base64-only keys)
+                        pem_body = re.sub(r"-----BEGIN (.*)-----", "", public_key_pem)
+                        pem_body = re.sub(r"-----END (.*)-----", "", pem_body)
+                        pem_body = re.sub(r"\s", "", pem_body)
+                        decoded = base64.b64decode(pem_body)
+                        self.public_key = serialization.load_der_public_key(
+                            decoded, backend=default_backend()
+                        )
+            except Exception as e:
+                raise SDKException(f"Failed to load public key: {e}") from e
+        else:
+            self.public_key = None
+
+        # Validate that it's an RSA key
+        if self.public_key is not None and not isinstance(
+            self.public_key, rsa.RSAPublicKey
+        ):
+            raise SDKException("Not an RSA PEM formatted public key")
+
+    def encrypt(self, data: bytes) -> bytes:
+        """Encrypt data using RSA OAEP with SHA-1.
+
+        Args:
+            data: Plaintext bytes to encrypt
+
+        Returns:
+            Encrypted bytes
+
+        Raises:
+            SDKException: If encryption fails or key is not set
+
+        """
+        if self.public_key is None:
+            raise SDKException("Failed to encrypt, public key is empty")
+        try:
+            return self.public_key.encrypt(
+                data,
+                padding.OAEP(
+                    mgf=padding.MGF1(algorithm=hashes.SHA1()),
+                    algorithm=hashes.SHA1(),
+                    label=None,
+                ),
+            )
+        except Exception as e:
+            raise SDKException(f"Error performing encryption: {e}") from e
+
+    def public_key_in_pem_format(self) -> str:
+        """Export the public key to PEM format.
+
+        Returns:
+            Public key as PEM-encoded string
+
+        Raises:
+            SDKException: If export fails
+
+        """
+        try:
+            pem = self.public_key.public_bytes(
+                encoding=serialization.Encoding.PEM,
+                format=serialization.PublicFormat.SubjectPublicKeyInfo,
+            )
+            return pem.decode()
+        except Exception as e:
+            raise SDKException(f"Error exporting public key to PEM: {e}") from e

otdf_python/auth_headers.py

@@ -0,0 +1,35 @@
+"""Authentication header management."""
+
+from dataclasses import dataclass
+
+
+@dataclass
+class AuthHeaders:
+    """Represents authentication headers used in token-based authorization.
+
+    This class holds authorization and DPoP (Demonstrating Proof of Possession) headers
+    that are used in token-based API requests.
+    """
+
+    auth_header: str
+    dpop_header: str = ""
+
+    def get_auth_header(self) -> str:
+        """Get the authorization header."""
+        return self.auth_header
+
+    def get_dpop_header(self) -> str:
+        """Get the DPoP header."""
+        return self.dpop_header
+
+    def to_dict(self) -> dict[str, str]:
+        """Convert authentication headers to a dictionary for use with HTTP clients.
+
+        Returns:
+            Dictionary with 'Authorization' header and optionally 'DPoP' header
+
+        """
+        headers = {"Authorization": self.auth_header}
+        if self.dpop_header:
+            headers["DPoP"] = self.dpop_header
+        return headers

otdf_python/autoconfigure_utils.py

@@ -0,0 +1,127 @@
+"""Utilities for automatic SDK configuration."""
+
+import re
+import urllib.parse
+from dataclasses import dataclass
+from typing import Any
+
+
+# RuleType constants
+class RuleType:
+    """Rule type constants for attribute hierarchy."""
+
+    HIERARCHY = "hierarchy"
+    ALL_OF = "allOf"
+    ANY_OF = "anyOf"
+    UNSPECIFIED = "unspecified"
+    EMPTY_TERM = "DEFAULT"
+
+
+@dataclass(frozen=True)
+class KeySplitStep:
+    """Key split step information."""
+
+    kas: str
+    splitID: str
+
+    def __str__(self):
+        return f"KeySplitStep{{kas={self.kas}, splitID={self.splitID}}}"
+
+    def __eq__(self, other: Any) -> bool:
+        if not isinstance(other, KeySplitStep):
+            return False
+        return self.kas == other.kas and self.splitID == other.splitID
+
+    def __hash__(self):
+        return hash((self.kas, self.splitID))
+
+
+class AutoConfigureException(Exception):
+    """Exception for auto-configuration errors."""
+
+
+class AttributeNameFQN:
+    """Fully qualified attribute name."""
+
+    def __init__(self, url: str):
+        """Initialize attribute name from URL."""
+        pattern = re.compile(r"^(https?://[\w./-]+)/attr/([^/\s]*)$")
+        matcher = pattern.match(url)
+        if not matcher or not matcher.group(1) or not matcher.group(2):
+            raise AutoConfigureException("invalid type: attribute regex fail")
+        try:
+            urllib.parse.unquote(matcher.group(2))
+        except Exception as err:
+            raise AutoConfigureException(
+                f"invalid type: error in attribute name [{matcher.group(2)}]"
+            ) from err
+        self.url = url
+        self.key = url.lower()
+
+    def __str__(self):
+        return self.url
+
+    def select(self, value: str):
+        new_url = f"{self.url}/value/{urllib.parse.quote(value)}"
+        return AttributeValueFQN(new_url)
+
+    def prefix(self):
+        return self.url
+
+    def get_key(self):
+        return self.key
+
+    def authority(self):
+        pattern = re.compile(r"^(https?://[\w./-]+)/attr/[^/\s]*$")
+        matcher = pattern.match(self.url)
+        if not matcher:
+            raise AutoConfigureException("invalid type")
+        return matcher.group(1)
+
+    def name(self):
+        pattern = re.compile(r"^https?://[\w./-]+/attr/([^/\s]*)$")
+        matcher = pattern.match(self.url)
+        if not matcher:
+            raise AutoConfigureException("invalid attribute")
+        try:
+            return urllib.parse.unquote(matcher.group(1))
+        except Exception as err:
+            raise AutoConfigureException("invalid type") from err
+
+
+class AttributeValueFQN:
+    """Fully qualified attribute value."""
+
+    def __init__(self, url: str):
+        """Initialize attribute value from URL."""
+        pattern = re.compile(r"^(https?://[\w./-]+)/attr/(\S*)/value/(\S*)$")
+        matcher = pattern.match(url)
+        if (
+            not matcher
+            or not matcher.group(1)
+            or not matcher.group(2)
+            or not matcher.group(3)
+        ):
+            raise AutoConfigureException(
+                f"invalid type: attribute regex fail for [{url}]"
+            )
+        try:
+            urllib.parse.unquote(matcher.group(2))
+            urllib.parse.unquote(matcher.group(3))
+        except Exception as err:
+            raise AutoConfigureException(
+                "invalid type: error in attribute or value"
+            ) from err
+        self.url = url
+        self.key = url.lower()
+
+    def __str__(self):
+        return self.url
+
+    def __eq__(self, other: Any) -> bool:
+        if not isinstance(other, AttributeValueFQN):
+            return False
+        return self.key == other.key
+
+    def __hash__(self):
+        return hash(self.key)