tiny-ca 0.1.0__py3-none-any.whl

tiny_ca/ca_factory/utils/afile_loader.py

@@ -0,0 +1,157 @@
+from __future__ import annotations
+
+import asyncio
+from logging import Logger
+from pathlib import Path
+from typing import Protocol, cast, runtime_checkable
+
+from cryptography import x509
+from cryptography.hazmat._oid import NameOID
+from cryptography.hazmat.backends import default_backend
+from cryptography.hazmat.bindings._rust import ObjectIdentifier
+from cryptography.hazmat.primitives import serialization
+from cryptography.hazmat.primitives.asymmetric import rsa
+
+from tiny_ca.const import ALLOWED_CERT_EXTENSIONS
+from tiny_ca.exc import ErrorLoadCert, IsNotFile, NotExistCertFile, WrongType
+from tiny_ca.models.certtificate import CertificateInfo
+from tiny_ca.settings import DEFAULT_LOGGER
+
+from .file_loader import CAFileLoader
+
+
+class AsyncCAFileLoader:
+    """
+    Loads a CA certificate and private key from PEM files on the local filesystem.
+
+    Responsibility: file reading and PEM deserialisation *only*.
+    Does not generate certificates, manage sessions, or perform any
+    cryptographic operations beyond deserialisation.
+
+    On construction the loader:
+    1. Validates that both paths point to existing, regular files with
+       permitted extensions (see ``ALLOWED_CERT_EXTENSIONS``).
+    2. Deserialises the CA certificate and private key from PEM.
+    3. Extracts ``CertificateInfo`` from the CA certificate's Subject.
+
+    After successful construction all three ``ICALoader`` properties are
+    available and will not change for the lifetime of the instance.
+
+    Parameters
+    ----------
+    ca_cert_path : str | Path
+        Path to the PEM-encoded CA certificate file.
+    ca_key_path : str | Path
+        Path to the PEM-encoded CA private key file.
+    ca_key_password : str | bytes | None
+        Optional password protecting the private key.  A ``str`` value is
+        encoded to ``bytes`` using UTF-8 before being passed to the
+        cryptography library.  ``None`` means the key is unencrypted.
+    logger : Logger | None
+        Logger instance for diagnostic messages.  Falls back to
+        ``DEFAULT_LOGGER`` when ``None``.
+    """
+
+    def __init__(
+        self,
+        ca_cert_path: str | Path,
+        ca_key_path: str | Path,
+        ca_key_password: str | bytes | None = None,
+        logger: Logger | None = None,
+    ) -> None:
+        self._logger = logger or DEFAULT_LOGGER
+        self._ca_cert_path = CAFileLoader._validate_file(Path(ca_cert_path))
+        self._ca_key_path = CAFileLoader._validate_file(Path(ca_key_path))
+
+        self._password_bytes: bytes | None = None
+        if ca_key_password is not None:
+            self._password_bytes = (
+                ca_key_password.encode("utf-8")
+                if isinstance(ca_key_password, str)
+                else ca_key_password
+            )
+
+        self._ca_cert: x509.Certificate | None = None
+        self._ca_key: rsa.RSAPrivateKey | None = None
+        self._base_info: CertificateInfo | None = None
+
+    @classmethod
+    async def create(
+        cls,
+        ca_cert_path: str | Path,
+        ca_key_path: str | Path,
+        ca_key_password: str | bytes | None = None,
+        logger: Logger | None = None,
+    ) -> AsyncCAFileLoader:
+
+        instance = cls(ca_cert_path, ca_key_path, ca_key_password, logger)
+        await instance.load()
+        return instance
+
+    # ------------------------------------------------------------------
+    # ICALoader properties
+    # ------------------------------------------------------------------
+
+    @property
+    def ca_cert(self) -> x509.Certificate:
+        if self._ca_cert is None:
+            raise RuntimeError("Call 'await loader.load()' before accessing ca_cert.")
+        return self._ca_cert
+
+    @property
+    def ca_key(self) -> rsa.RSAPrivateKey:
+        if self._ca_key is None:
+            raise RuntimeError("Call 'await loader.load()' before accessing ca_key.")
+        return self._ca_key
+
+    @property
+    def base_info(self) -> CertificateInfo:
+        if self._base_info is None:
+            raise RuntimeError("Call 'await loader.load()' before accessing base_info.")
+        return self._base_info
+
+    async def load(self) -> None:
+        loop = asyncio.get_event_loop()
+        ca_cert, ca_key = await loop.run_in_executor(
+            None,
+            self._load_sync,
+        )
+        self._ca_cert = ca_cert
+        self._ca_key = ca_key
+        self._base_info = self._extract_info()
+
+    def _load_sync(self) -> tuple[x509.Certificate, rsa.RSAPrivateKey]:
+
+        try:
+            with open(self._ca_cert_path, "rb") as fh:
+                ca_cert = x509.load_pem_x509_certificate(fh.read(), default_backend())
+        except Exception as exc:
+            raise ErrorLoadCert(path_to_file=self._ca_cert_path, exc=str(exc)) from exc
+
+        try:
+            with open(self._ca_key_path, "rb") as fh:
+                ca_key = serialization.load_pem_private_key(
+                    fh.read(), password=self._password_bytes, backend=default_backend()
+                )
+        except Exception as exc:
+            raise ErrorLoadCert(path_to_file=self._ca_key_path, exc=str(exc)) from exc
+
+        self._logger.info("CA loaded successfully from %s", self._ca_cert_path)
+        if not isinstance(ca_key, rsa.RSAPrivateKey):
+            raise TypeError("CA key must be RSA")
+        return ca_cert, ca_key
+
+    def _extract_info(self) -> CertificateInfo:
+        # assert self._ca_cert is not None
+
+        def _attr(oid: ObjectIdentifier) -> str | None:
+            attrs = self._ca_cert.subject.get_attributes_for_oid(oid)  # type: ignore[union-attr]
+            return cast(str, attrs[0].value) if attrs else None
+
+        return CertificateInfo(
+            organization=_attr(NameOID.ORGANIZATION_NAME),
+            organizational_unit=_attr(NameOID.ORGANIZATIONAL_UNIT_NAME),
+            country=_attr(NameOID.COUNTRY_NAME),
+            state=_attr(NameOID.STATE_OR_PROVINCE_NAME),
+            locality=_attr(NameOID.LOCALITY_NAME),
+        )

tiny_ca/ca_factory/utils/file_loader.py

@@ -0,0 +1,290 @@
+"""
+CA material loading: Protocol definition and PEM-file-backed implementation.
+
+This module provides two public symbols:
+
+- ``ICALoader``    — a ``@runtime_checkable`` Protocol that defines the minimum
+                     interface any CA-material provider must satisfy.  Consumers
+                     (e.g. ``CertificateFactory``) depend only on this Protocol,
+                     never on a concrete loader class (DIP).
+
+- ``CAFileLoader`` — reads a CA certificate and private key from PEM files on
+                     the local filesystem and exposes them through ``ICALoader``.
+"""
+
+from __future__ import annotations
+
+from logging import Logger
+from pathlib import Path
+from typing import Protocol, cast, runtime_checkable
+
+from cryptography import x509
+from cryptography.hazmat._oid import NameOID
+from cryptography.hazmat.backends import default_backend
+from cryptography.hazmat.bindings._rust import ObjectIdentifier
+from cryptography.hazmat.primitives import serialization
+from cryptography.hazmat.primitives.asymmetric import rsa
+
+from tiny_ca.const import ALLOWED_CERT_EXTENSIONS
+from tiny_ca.exc import ErrorLoadCert, IsNotFile, NotExistCertFile, WrongType
+from tiny_ca.models.certtificate import CertificateInfo
+from tiny_ca.settings import DEFAULT_LOGGER
+
+# ---------------------------------------------------------------------------
+# ISP / DIP: minimal interface for CA-material providers
+# ---------------------------------------------------------------------------
+
+
+@runtime_checkable
+class ICALoader(Protocol):
+    """
+    Protocol that defines the minimum contract for CA-material providers.
+
+    Any object that exposes the three properties below satisfies this Protocol
+    and can be injected into ``CertificateFactory`` without any inheritance.
+    This makes it trivial to substitute the real filesystem loader with an
+    in-memory stub, an HSM-backed loader, or a mock in unit tests.
+
+    Properties
+    ----------
+    ca_cert : x509.Certificate
+        The loaded CA certificate object.
+    ca_key : rsa.RSAPrivateKey
+        The loaded CA private key used for signing.
+    base_info : CertificateInfo
+        Structured metadata extracted from the CA certificate's Subject field
+        (organization, country, state, locality, organizational unit).
+    """
+
+    @property
+    def ca_cert(self) -> x509.Certificate: ...
+
+    @property
+    def ca_key(self) -> rsa.RSAPrivateKey: ...
+
+    @property
+    def base_info(self) -> CertificateInfo: ...
+
+
+# ---------------------------------------------------------------------------
+# SRP: PEM-file-backed CA loader
+# ---------------------------------------------------------------------------
+
+
+class CAFileLoader:
+    """
+    Loads a CA certificate and private key from PEM files on the local filesystem.
+
+    Responsibility: file reading and PEM deserialisation *only*.
+    Does not generate certificates, manage sessions, or perform any
+    cryptographic operations beyond deserialisation.
+
+    On construction the loader:
+    1. Validates that both paths point to existing, regular files with
+       permitted extensions (see ``ALLOWED_CERT_EXTENSIONS``).
+    2. Deserialises the CA certificate and private key from PEM.
+    3. Extracts ``CertificateInfo`` from the CA certificate's Subject.
+
+    After successful construction all three ``ICALoader`` properties are
+    available and will not change for the lifetime of the instance.
+
+    Parameters
+    ----------
+    ca_cert_path : str | Path
+        Path to the PEM-encoded CA certificate file.
+    ca_key_path : str | Path
+        Path to the PEM-encoded CA private key file.
+    ca_key_password : str | bytes | None
+        Optional password protecting the private key.  A ``str`` value is
+        encoded to ``bytes`` using UTF-8 before being passed to the
+        cryptography library.  ``None`` means the key is unencrypted.
+    logger : Logger | None
+        Logger instance for diagnostic messages.  Falls back to
+        ``DEFAULT_LOGGER`` when ``None``.
+    """
+
+    # ------------------------------------------------------------------
+    # ICALoader properties
+    # ------------------------------------------------------------------
+
+    @property
+    def ca_cert(self) -> x509.Certificate:
+        """
+        The deserialized CA certificate.
+
+        Returns
+        -------
+        x509.Certificate
+            The CA certificate loaded from *ca_cert_path*.
+        """
+        return self._ca_cert
+
+    @property
+    def ca_key(self) -> rsa.RSAPrivateKey:
+        """
+        The deserialized CA private key.
+
+        Returns
+        -------
+        rsa.RSAPrivateKey
+            The private key loaded from *ca_key_path*.
+        """
+        return self._ca_key
+
+    @property
+    def base_info(self) -> CertificateInfo:
+        """
+        Structured metadata extracted from the CA certificate Subject.
+
+        Returns
+        -------
+        CertificateInfo
+            Contains *organization*, *organizational_unit*, *country*,
+            *state*, and *locality* fields; any absent attribute is ``None``.
+        """
+        return self._base_info
+
+    # ------------------------------------------------------------------
+    # Construction
+    # ------------------------------------------------------------------
+
+    def __init__(
+        self,
+        ca_cert_path: str | Path,
+        ca_key_path: str | Path,
+        ca_key_password: str | bytes | None = None,
+        logger: Logger | None = None,
+    ) -> None:
+        self._logger = logger or DEFAULT_LOGGER
+
+        self._ca_cert_path = self._validate_file(Path(ca_cert_path))
+        self._ca_key_path = self._validate_file(Path(ca_key_path))
+
+        # Normalise password to bytes so the cryptography library always
+        # receives the expected type.
+        password_bytes: bytes | None = None
+        if ca_key_password is not None:
+            password_bytes = (
+                ca_key_password.encode("utf-8")
+                if isinstance(ca_key_password, str)
+                else ca_key_password
+            )
+
+        self._ca_cert, self._ca_key = self._load(password_bytes)
+        self._base_info = self._extract_info()
+
+    # ------------------------------------------------------------------
+    # Private helpers
+    # ------------------------------------------------------------------
+
+    @staticmethod
+    def _validate_file(
+        path: Path,
+        allowed: tuple[str, ...] = ALLOWED_CERT_EXTENSIONS,
+    ) -> Path:
+        """
+        Verify that *path* points to an existing regular file with a
+        permitted extension.
+
+        Parameters
+        ----------
+        path : Path
+            Filesystem path to validate.
+        allowed : tuple[str, ...]
+            Whitelist of accepted file extensions (including the leading dot,
+            e.g. ``".pem"``).  Defaults to ``ALLOWED_CERT_EXTENSIONS``.
+
+        Returns
+        -------
+        Path
+            The validated *path*, unchanged.
+
+        Raises
+        ------
+        NotExistCertFile
+            If *path* does not exist on the filesystem.
+        IsNotFile
+            If *path* exists but is a directory or other non-regular file.
+        WrongType
+            If the file extension is not listed in *allowed*.
+        """
+        if not path.exists():
+            raise NotExistCertFile(path_to_file=path)
+        if not path.is_file():
+            raise IsNotFile(path_to_file=path)
+        if path.suffix not in allowed:
+            raise WrongType(wrong_type=path.suffix, allowed_types=allowed)
+        return path
+
+    def _load(
+        self,
+        password: bytes | None,
+    ) -> tuple[x509.Certificate, rsa.RSAPrivateKey]:
+        """
+        Read and deserialise the CA certificate and private key from PEM files.
+
+        The certificate and key are loaded independently; a separate
+        ``try/except`` block wraps each operation so that the failure message
+        identifies exactly which file could not be read.
+
+        Parameters
+        ----------
+        password : bytes | None
+            Password for the private key, or ``None`` for unencrypted keys.
+
+        Returns
+        -------
+        tuple[x509.Certificate, rsa.RSAPrivateKey]
+            ``(ca_cert, ca_key)`` ready for use.
+
+        Raises
+        ------
+        ErrorLoadCert
+            Wraps any underlying exception thrown during file I/O or PEM
+            deserialisation, annotated with the offending file path.
+        """
+        try:
+            with open(self._ca_cert_path, "rb") as fh:
+                ca_cert = x509.load_pem_x509_certificate(fh.read(), default_backend())
+        except Exception as exc:
+            raise ErrorLoadCert(path_to_file=self._ca_cert_path, exc=str(exc)) from exc
+
+        try:
+            with open(self._ca_key_path, "rb") as fh:
+                ca_key = serialization.load_pem_private_key(
+                    fh.read(), password=password, backend=default_backend()
+                )
+        except Exception as exc:
+            raise ErrorLoadCert(path_to_file=self._ca_key_path, exc=str(exc)) from exc
+
+        self._logger.info("CA loaded successfully from %s", self._ca_cert_path)
+        if not isinstance(ca_key, rsa.RSAPrivateKey):
+            raise TypeError("CA key must be RSA")
+        return ca_cert, ca_key
+
+    def _extract_info(self) -> CertificateInfo:
+        """
+        Parse the CA certificate's Subject and return a structured info object.
+
+        Iterates over well-known OIDs (organization, organizational unit,
+        country, state, locality) and reads the first matching attribute value
+        for each.  Missing attributes are stored as ``None``.
+
+        Returns
+        -------
+        CertificateInfo
+            Dataclass populated with Subject attribute values extracted from
+            ``self._ca_cert``.
+        """
+
+        def _attr(oid: ObjectIdentifier) -> str | None:
+            attrs = self._ca_cert.subject.get_attributes_for_oid(oid)
+            return cast(str, attrs[0].value) if attrs else None
+
+        return CertificateInfo(
+            organization=_attr(NameOID.ORGANIZATION_NAME),
+            organizational_unit=_attr(NameOID.ORGANIZATIONAL_UNIT_NAME),
+            country=_attr(NameOID.COUNTRY_NAME),
+            state=_attr(NameOID.STATE_OR_PROVINCE_NAME),
+            locality=_attr(NameOID.LOCALITY_NAME),
+        )

tiny_ca/ca_factory/utils/life_time.py

@@ -0,0 +1,199 @@
+"""
+Stateless utilities for computing and inspecting X.509 certificate validity
+periods.
+
+All methods are ``@staticmethod``; the class carries no instance state and
+exists purely as a logical namespace.  It can be used from any module without
+instantiation.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from datetime import UTC, datetime, timedelta
+from typing import cast
+
+from cryptography import x509
+
+from tiny_ca.exc import InvalidRangeTimeCertificate
+
+
+class CertLifetime:
+    """
+    Stateless helper that computes and inspects X.509 certificate validity windows.
+
+    All operations are pure functions (no side effects, no shared state) and are
+    therefore safe to call from multiple threads simultaneously.
+
+    Use this class to:
+    - Compute a ``(not_before, not_after)`` pair for a new certificate.
+    - Extract the ``not_valid_after`` / ``not_valid_before`` timestamps from an
+      existing certificate as timezone-aware UTC ``datetime`` objects.
+    """
+
+    @staticmethod
+    def compute(
+        valid_from: datetime | None = None,
+        days_valid: int = 365,
+    ) -> tuple[datetime, datetime]:
+        """
+        Calculate the ``(not_before, not_after)`` validity interval for a new
+        certificate.
+
+        If *valid_from* is ``None`` the current UTC time is used as the start
+        of the interval.  The end of the interval is *valid_from* plus
+        *days_valid* calendar days.
+
+        The result is validated to ensure the computed end date has not already
+        passed (which would produce an immediately-invalid certificate).
+
+        Parameters
+        ----------
+        valid_from : datetime | None
+            Start of the validity period as a timezone-aware ``datetime``.
+            Pass ``None`` to use ``datetime.now(timezone.utc)`` automatically.
+        days_valid : int
+            Number of calendar days the certificate should remain valid.
+            Default: ``365`` (one year).
+
+        Returns
+        -------
+        tuple[datetime, datetime]
+            ``(not_before, not_after)`` both expressed in UTC with
+            ``tzinfo=timezone.utc``.
+
+        Raises
+        ------
+        InvalidRangeTimeCertificate
+            If the computed *not_after* is earlier than the current UTC time,
+            meaning the certificate would be expired immediately upon issuance.
+
+        Examples
+        --------
+        >>> start, end = CertLifetime.compute(days_valid=90)
+        >>> assert (end - start).days == 90
+        """
+        now = datetime.now(UTC)
+        start = valid_from or now
+        end = start + timedelta(days=days_valid)
+        if end < now:
+            raise InvalidRangeTimeCertificate(valid_from=start, valid_to=end, now=now)
+        return start, end
+
+    @staticmethod
+    def valid_to(cert: x509.Certificate) -> datetime:
+        """
+        Return the expiry timestamp of *cert* as a timezone-aware UTC datetime.
+
+        Wraps ``cert.not_valid_after_utc`` and ensures the returned value
+        always carries ``tzinfo=timezone.utc`` for safe comparison with other
+        aware datetimes.
+
+        Parameters
+        ----------
+        cert : x509.Certificate
+            The certificate whose expiry date should be read.
+
+        Returns
+        -------
+        datetime
+            ``cert.not_valid_after_utc`` with ``tzinfo`` explicitly set to
+            ``timezone.utc``.
+        """
+        return cert.not_valid_after_utc.replace(tzinfo=UTC)
+
+    @staticmethod
+    def valid_from(cert: x509.Certificate) -> datetime:
+        """
+        Return the activation timestamp of *cert* as a timezone-aware UTC datetime.
+
+        Wraps ``cert.not_valid_before_utc`` and ensures the returned value
+        always carries ``tzinfo=timezone.utc`` for safe comparison with other
+        aware datetimes.
+
+        Parameters
+        ----------
+        cert : x509.Certificate
+            The certificate whose activation date should be read.
+
+        Returns
+        -------
+        datetime
+            ``cert.not_valid_before_utc`` with ``tzinfo`` explicitly set to
+            ``timezone.utc``.
+        """
+        return cert.not_valid_after_utc.replace(tzinfo=UTC)
+
+    @staticmethod
+    async def compute_async(
+        valid_from: datetime | None = None,
+        days_valid: int = 365,
+    ) -> tuple[datetime, datetime]:
+        """
+        Async-версія :meth:`compute`.
+
+        Виконує обчислення в пулі потоків, щоб не блокувати event loop.
+
+        Parameters
+        ----------
+        valid_from : datetime | None
+            Початок вікна дійсності (UTC). ``None`` → поточний UTC-час.
+        days_valid : int
+            Тривалість у календарних днях. За замовчуванням: ``365``.
+
+        Returns
+        -------
+        tuple[datetime, datetime]
+            ``(not_before, not_after)`` в UTC.
+
+        Raises
+        ------
+        InvalidRangeTimeCertificate
+            Якщо обчислена дата закінчення вже в минулому.
+
+        Examples
+        --------
+        #>>> start, end = await CertLifetime.compute_async(days_valid=90)
+        #>>> assert (end - start).days == 90
+        """
+        loop = asyncio.get_event_loop()
+        return await loop.run_in_executor(
+            None,
+            lambda: CertLifetime.compute(valid_from, days_valid),
+        )
+
+    @staticmethod
+    async def valid_to_async(cert: x509.Certificate) -> datetime:
+        """
+        Async-версія :meth:`valid_to`.
+
+        Parameters
+        ----------
+        cert : x509.Certificate
+            Сертифікат, дату закінчення якого потрібно прочитати.
+
+        Returns
+        -------
+        datetime
+            ``cert.not_valid_after_utc`` з ``tzinfo=UTC``.
+        """
+        loop = asyncio.get_event_loop()
+        return await loop.run_in_executor(None, CertLifetime.valid_to, cert)
+
+    @staticmethod
+    async def valid_from_async(cert: x509.Certificate) -> datetime:
+        """
+        Async-версія :meth:`valid_from`.
+
+        Parameters
+        ----------
+        cert : x509.Certificate
+            Сертифікат, дату початку дії якого потрібно прочитати.
+
+        Returns
+        -------
+        datetime
+            ``cert.not_valid_before_utc`` з ``tzinfo=UTC``.
+        """
+        loop = asyncio.get_event_loop()
+        return await loop.run_in_executor(None, CertLifetime.valid_from, cert)