tiny-ca 0.1.0__py3-none-any.whl

tiny_ca/models/__init__.py

@@ -0,0 +1,3 @@
+from .certtificate import CAConfig, ClientConfig
+
+__all__ = ["CAConfig", "ClientConfig"]

tiny_ca/models/certtificate.py

@@ -0,0 +1,300 @@
+"""
+certtificate.py
+
+Pydantic data models for certificate configuration and metadata.
+
+These models act as typed, validated data-transfer objects between the
+application layer and the cryptographic factory.  They are intentionally
+free of any cryptographic logic — validation (field constraints, type
+coercion) is Pydantic's responsibility; generation is ``CertificateFactory``'s.
+
+Class hierarchy
+---------------
+::
+
+    BaseModel
+    ├── CommonNameCertificate          — CN field only
+    │   └── BaseCertificateDataModel  — CN + organization + country
+    ├── BaseCertificateConfig          — key_size, days_valid, valid_from
+    │   └── CAConfig                  — full CA bootstrap config (inherits both branches)
+    └── ClientConfig                   — end-entity cert config (CN + crypto params + SANs)
+
+    CertificateInfo                    — read-only metadata extracted from an
+                                         existing CA certificate's Subject field
+"""
+
+from __future__ import annotations
+
+import datetime
+
+from pydantic import BaseModel, ConfigDict, EmailStr, Field, IPvAnyAddress
+
+from tiny_ca.const import CertType
+
+# ---------------------------------------------------------------------------
+# Reusable base fragments
+# ---------------------------------------------------------------------------
+
+
+class CommonNameCertificate(BaseModel):
+    """
+    Minimal certificate identity fragment carrying only the Common Name.
+
+    Used as a mix-in base so that all certificate configuration models share
+    a consistent ``common_name`` field with the same default and description.
+
+    Attributes
+    ----------
+    common_name : str
+        The ``CN`` (Common Name) field of the certificate Subject.
+        Default: ``"Internal CA"``.
+    """
+
+    common_name: str = Field(
+        default="Internal CA",
+        description="Common Name (CN) for the certificate Subject.",
+    )
+
+
+class BaseCertificateDataModel(CommonNameCertificate):
+    """
+    Certificate Subject identity fields shared by all CA configurations.
+
+    Extends ``CommonNameCertificate`` with *organization* and *country* so
+    that all issued end-entity certificates can inherit the issuer's
+    organisational identity.
+
+    Attributes
+    ----------
+    common_name : str
+        Inherited from ``CommonNameCertificate``.
+    organization : str
+        Organization (O) field of the certificate Subject.
+        Default: ``"My Company"``.
+    country : str
+        Two-letter ISO 3166-1 alpha-2 country code (C field).
+        Default: ``"UA"``.
+    """
+
+    organization: str = Field(
+        default="My Company",
+        description="Organization (O) field of the certificate Subject.",
+    )
+    country: str = Field(
+        default="UA",
+        description="Two-letter ISO 3166-1 alpha-2 country code (C field).",
+    )
+
+
+class BaseCertificateConfig(BaseModel):
+    """
+    Cryptographic validity parameters shared by all certificate types.
+
+    Provides the three fields that control the key strength and the validity
+    window of a certificate.  Used as a mix-in base to avoid duplication
+    between ``CAConfig`` and ``ClientConfig``.
+
+    Attributes
+    ----------
+    key_size : int
+        RSA key length in bits.  Use ``2048`` for standard security or
+        ``4096`` for long-lived CA certificates.  Default: ``2048``.
+    days_valid : int
+        Number of calendar days the certificate should remain valid.
+        Default: ``3650`` (≈10 years; appropriate for a root CA).
+    valid_from : datetime.datetime | None
+        Explicit start of the validity period as a timezone-aware
+        ``datetime``.  When ``None``, the cryptographic layer uses the
+        current UTC time at the moment of issuance.  Default: ``None``.
+
+    Notes
+    -----
+    ``model_config = ConfigDict(arbitrary_types_allowed=True)`` is required
+    because ``datetime.datetime`` is not a Pydantic-native field type.
+    """
+
+    key_size: int = Field(
+        default=2048,
+        description="RSA key length in bits (2048 or 4096).",
+    )
+    days_valid: int = Field(
+        default=3650,
+        description="Certificate validity period in calendar days.",
+    )
+    valid_from: datetime.datetime | None = Field(
+        default=None,
+        description=(
+            "Explicit validity start as a timezone-aware datetime. "
+            "None defaults to the current UTC time at issuance."
+        ),
+    )
+
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+
+# ---------------------------------------------------------------------------
+# Concrete configuration models
+# ---------------------------------------------------------------------------
+
+
+class CAConfig(BaseCertificateConfig, BaseCertificateDataModel):
+    """
+    Complete configuration for bootstrapping a self-signed root CA certificate.
+
+    Combines all Subject identity fields (``BaseCertificateDataModel``) with
+    the cryptographic validity parameters (``BaseCertificateConfig``).
+    Passed directly to ``CertificateFactory.build_self_signed_ca`` via
+    ``config.model_dump()``.
+
+    Inherited attributes
+    --------------------
+    common_name : str
+        CN for the CA.  Default: ``"Internal CA"``.
+    organization : str
+        O field.  Default: ``"My Company"``.
+    country : str
+        C field (ISO 3166-1 alpha-2).  Default: ``"UA"``.
+    key_size : int
+        RSA key size in bits.  Default: ``2048``.
+    days_valid : int
+        Validity in days.  Default: ``3650``.
+    valid_from : datetime | None
+        Explicit validity start; ``None`` uses current UTC.  Default: ``None``.
+    """
+
+
+class ClientConfig(CommonNameCertificate, BaseCertificateConfig):
+    """
+    Configuration for issuing an end-entity (client or server) certificate.
+
+    Passed to ``CertificateFactory.issue_certificate`` via
+    ``config.model_dump(exclude={"name"})``.
+
+    Attributes
+    ----------
+    common_name : str
+        CN for the certificate Subject.  Inherited from
+        ``CommonNameCertificate``.  Default: ``"Internal CA"``.
+    key_size : int
+        RSA key size in bits.  Inherited from ``BaseCertificateConfig``.
+        Default: ``2048``.
+    days_valid : int
+        Validity period in calendar days.  Default: ``3650``.
+    valid_from : datetime | None
+        Explicit validity start.  Default: ``None``.
+    serial_type : CertType
+        Certificate category used when encoding the serial number.
+        Default: ``CertType.CA``.
+    is_client_cert : bool
+        When ``True``, ``ClientAuth`` is added to the Extended Key Usage
+        extension.  Default: ``False``.
+    is_server_cert : bool
+        When ``True``, ``ServerAuth`` is added to the Extended Key Usage
+        extension and the CN is included as a DNS Subject Alternative Name
+        (RFC 2818 compliance).  Default: ``True``.
+    san_dns : list[str] | None
+        Additional DNS names for the Subject Alternative Name extension.
+        Default: ``None``.
+    san_ip : list[IPvAnyAddress] | None
+        IP addresses for the Subject Alternative Name extension.  Accepts
+        both IPv4 and IPv6.  Default: ``None``.
+    email : EmailStr | None
+        Optional email address added as an ``emailAddress`` Subject attribute.
+        Must be a valid RFC 5322 address if provided.  Default: ``None``.
+    name : str | None
+        Override for the output file basename used by ``BaseStorage``.
+        When ``None``, the storage layer derives the name from *common_name*.
+        This field is excluded from ``model_dump`` calls to the factory.
+        Default: ``None``.
+    """
+
+    serial_type: CertType = Field(
+        default=CertType.CA,
+        description="Certificate category encoded into the serial number.",
+    )
+    is_client_cert: bool = Field(
+        default=False,
+        description="Add ClientAuth to Extended Key Usage when True.",
+    )
+    is_server_cert: bool = Field(
+        default=True,
+        description=(
+            "Add ServerAuth to Extended Key Usage and include CN as a DNS SAN "
+            "when True (required for TLS server certificates per RFC 2818)."
+        ),
+    )
+    san_dns: list[str] | None = Field(
+        default=None,
+        description="Additional DNS names for the Subject Alternative Name extension.",
+    )
+    san_ip: list[IPvAnyAddress] | None = Field(
+        default=None,
+        description="IP addresses (IPv4 or IPv6) for the Subject Alternative Name extension.",
+    )
+    email: EmailStr | None = Field(
+        default=None,
+        description="Optional email address added as an emailAddress Subject attribute.",
+    )
+    name: str | None = Field(
+        default=None,
+        description=(
+            "Explicit output file basename for storage artefacts. "
+            "Excluded from model_dump calls to the factory. "
+            "None causes the storage layer to derive the name from common_name."
+        ),
+    )
+
+
+# ---------------------------------------------------------------------------
+# Read-only metadata extracted from an existing CA certificate
+# ---------------------------------------------------------------------------
+
+
+class CertificateInfo(BaseModel):
+    """
+    Structured metadata extracted from the Subject field of a CA certificate.
+
+    Populated by ``CAFileLoader._extract_info`` and made available via the
+    ``ICALoader.base_info`` property.  ``CertificateFactory`` uses these
+    values to populate the Subject of every end-entity certificate it issues,
+    ensuring that all leaf certificates share the same organisational identity
+    as the signing CA.
+
+    All fields are optional (``None``) because not every CA certificate
+    includes all Subject attributes.
+
+    Attributes
+    ----------
+    organization : str | None
+        Organization (O) field.  Default: ``"My company"``.
+    organizational_unit : str | None
+        Organizational Unit (OU) field.  Default: ``"server"``.
+    country : str | None
+        Two-letter ISO 3166-1 alpha-2 country code (C field).
+        Default: ``"UA"``.
+    state : str | None
+        State or Province (ST) field.  Default: ``None``.
+    locality : str | None
+        Locality or City (L) field.  Default: ``None``.
+    """
+
+    organization: str | None = Field(
+        default="My company",
+        description="Organization (O) extracted from the CA certificate Subject.",
+    )
+    organizational_unit: str | None = Field(
+        default="server",
+        description="Organizational Unit (OU) extracted from the CA certificate Subject.",
+    )
+    country: str | None = Field(
+        default="UA",
+        description="Country (C) extracted from the CA certificate Subject.",
+    )
+    state: str | None = Field(
+        default=None,
+        description="State or Province (ST) extracted from the CA certificate Subject.",
+    )
+    locality: str | None = Field(
+        default=None,
+        description="Locality / City (L) extracted from the CA certificate Subject.",
+    )

tiny_ca/settings.py

@@ -0,0 +1,9 @@
+from logging import DEBUG, Formatter, StreamHandler, getLogger
+
+DEFAULT_LOGGER = getLogger("TinyCA")
+DEFAULT_LOGGER.setLevel(DEBUG)
+_console_handler = StreamHandler()
+_formatter = Formatter("%(asctime)s - %(name)s - %(levelname)s - %(message)s")
+_console_handler.setFormatter(_formatter)
+DEFAULT_LOGGER.addHandler(_console_handler)
+DT_STR_FORMAT = "%Y-%m-%d %H:%M:%S"

tiny_ca/storage/__init__.py

@@ -0,0 +1,4 @@
+from .base_storage import BaseStorage
+from .local_storage import LocalStorage
+
+__all__ = ["BaseStorage", "LocalStorage"]

tiny_ca/storage/async_local_storage.py

@@ -0,0 +1,218 @@
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Coroutine
+from logging import Logger
+from pathlib import Path
+import shutil
+from typing import Any
+from uuid import uuid4
+import warnings
+
+import aiofiles
+import cryptography
+from cryptography import x509
+from cryptography.hazmat.primitives import serialization
+from cryptography.hazmat.primitives.asymmetric import rsa
+
+from tiny_ca.exc import FileAlreadyExists
+from tiny_ca.settings import DEFAULT_LOGGER
+
+from .base_storage import BaseStorage
+from .const import CryptoObject
+from .local_storage import LocalStorage, _CertSerializer
+
+
+class AsyncLocalStorage(LocalStorage):
+    async def save_certificate(  # type: ignore[override]
+        self,
+        cert: CryptoObject,
+        file_name: str,
+        cert_path: str | Path | None = None,
+        uuid_str: str | None = None,
+        encoding: serialization.Encoding | None = None,
+        private_format: serialization.PrivateFormat | None = None,
+        public_format: serialization.PublicFormat | None = None,
+        encryption_algorithm: serialization.KeySerializationEncryption | None = None,
+        is_add_uuid: bool = True,
+        is_overwrite: bool = False,
+    ) -> tuple[Path, str | None]:
+        """
+        Serialise *cert* and write the result to the local filesystem.
+
+        Assembles the output path as::
+
+            <base_folder> / [cert_path/] / [<uuid>/] / <file_name><ext>
+
+        Where *ext* is determined automatically from the type of *cert*.
+
+        Parameters
+        ----------
+        cert : CryptoObject
+            Cryptographic object to serialise and persist.
+        file_name : str
+            Base filename without extension (e.g. ``"ca"``, ``"nginx"``).
+        cert_path : str | Path | None
+            Optional sub-directory appended after *base_folder*.
+        uuid_str : str | None
+            Reuse an existing UUID directory by passing the value returned by
+            a previous ``save_certificate`` call.  ``None`` auto-generates a
+            new UUID.  Ignored when *is_add_uuid* is ``False``.
+        encoding : serialization.Encoding | None
+            Encoding override.  ``None`` uses *base_encoding*.
+        private_format : serialization.PrivateFormat | None
+            Private-key format override.  ``None`` uses *base_private_format*.
+        public_format : serialization.PublicFormat | None
+            Public-key format override.  ``None`` uses *base_public_format*.
+        encryption_algorithm : serialization.KeySerializationEncryption | None
+            Private-key encryption override.  ``None`` uses
+            *base_encryption_algorithm*.
+        is_add_uuid : bool
+            When ``True`` (default), a UUID subdirectory is inserted.
+            Set to ``False`` for singleton files such as CRL that are
+            regenerated in-place.
+        is_overwrite : bool
+            When ``True``, silently replace an existing file.
+            When ``False`` (default), raise ``FileAlreadyExists``.
+
+        Returns
+        -------
+        tuple[Path, str | None]
+            ``(absolute_path_to_written_file, uuid_used)``.
+            *uuid_used* is ``None`` when *is_add_uuid* is ``False``.
+
+        Raises
+        ------
+        FileAlreadyExists
+            If the computed target path already exists and *is_overwrite*
+            is ``False``.
+        TypeError
+            If *cert* is not a supported cryptographic type.
+        """
+        output_dir, effective_uuid = self._resolve_output_dir(
+            cert_path=cert_path,
+            uuid_str=uuid_str,
+            is_add_uuid=is_add_uuid,
+        )
+
+        cert_data, extension = await asyncio.to_thread(
+            _CertSerializer.serialise,
+            cert=cert,
+            encoding=encoding or self._base_encoding,
+            private_format=private_format or self._base_private_format,
+            public_format=public_format or self._base_public_format,
+            encryption_algorithm=encryption_algorithm
+            or self._base_encryption_algorithm,
+        )
+
+        output_path = output_dir / f"{file_name}{extension}"
+        await self._write_file(
+            path=output_path, data=cert_data, is_overwrite=is_overwrite
+        )
+
+        self._logger.debug(
+            "Saved %s → %s (uuid=%s)", type(cert).__name__, output_path, effective_uuid
+        )
+        return output_path, effective_uuid
+
+    async def _write_file(  # type: ignore[override]
+        self, path: Path, data: bytes, is_overwrite: bool
+    ) -> None:
+        """
+        Write *data* to *path*, creating any missing parent directories.
+
+        Parent directories are created with ``mkdir(parents=True,
+        exist_ok=True)`` so the caller never needs to pre-create the
+        directory tree manually.
+
+        Parameters
+        ----------
+        path : Path
+            Absolute target path for the output file.
+        data : bytes
+            Raw serialised bytes to write.
+        is_overwrite : bool
+            When ``False``, raise ``FileAlreadyExists`` if *path* already
+            exists.  When ``True``, the existing file is silently replaced.
+
+        Raises
+        ------
+        FileAlreadyExists
+            If *path* already exists on disk and *is_overwrite* is ``False``.
+        """
+        if path.exists() and not is_overwrite:
+            raise FileAlreadyExists(path_save_cert=path)
+
+        path.parent.mkdir(parents=True, exist_ok=True)
+
+        async with aiofiles.open(path, "wb") as fh:
+            await fh.write(data)
+
+        self._logger.debug("Written %d bytes → %s", len(data), path)
+
+    async def delete_certificate_folder(  # type: ignore[override]
+        self,
+        uuid_str: str,
+        cert_path: str | Path | None = None,
+    ) -> bool:
+        """
+        Recursively remove the directory identified by *uuid_str*.
+
+        The target path is resolved as::
+
+            <base_folder> / [cert_path/] / <uuid_str>
+
+        The operation is idempotent: if the directory does not exist a
+        ``UserWarning`` is emitted and ``True`` is returned (no action needed).
+        If the path exists but is a regular file rather than a directory, a
+        ``UserWarning`` is emitted and ``True`` is returned (not our directory).
+        Only a genuine ``OSError`` during ``shutil.rmtree`` causes ``False``.
+
+        Parameters
+        ----------
+        uuid_str : str
+            UUID sub-directory name to remove.
+        cert_path : str | Path | None
+            Optional sub-path under *base_folder* containing *uuid_str*.
+
+        Returns
+        -------
+        bool
+            ``True``  — directory removed, or path was already absent.
+            ``False`` — ``OSError`` occurred; check logs for details.
+
+        Warns
+        -----
+        UserWarning
+            If the target path does not exist or is not a directory.
+        """
+        target = self._base_folder
+        if cert_path:
+            target = target / cert_path
+        target = target / uuid_str
+
+        if not target.exists():
+            warnings.warn(
+                f"Certificate folder not deleted — path does not exist: {target}",
+                UserWarning,
+                stacklevel=2,
+            )
+            return True
+
+        if not target.is_dir():
+            warnings.warn(
+                f"Certificate folder not deleted — path is not a directory: {target}",
+                UserWarning,
+                stacklevel=2,
+            )
+            return True
+
+        try:
+            await asyncio.to_thread(shutil.rmtree, path=target)
+            self._logger.info("Deleted certificate folder: %s", target)
+            return True
+        except OSError as exc:
+            self._logger.error(
+                "Failed to delete certificate folder %s: %s", target, exc
+            )
+            return False