tiny_ca.storage.local_storage module

local_storage.py

Local filesystem implementation of BaseStorage.

Module-level contents

_CertSerializer — stateless helper that converts a cryptographic object

to raw bytes and determines the correct file extension. Private to this module; not part of the public API.

LocalStorage — concrete BaseStorage that writes artefacts to

a configurable directory tree on the local filesystem.

SOLID notes

SRP_CertSerializer is responsible for serialisation only.

LocalStorage is responsible for path resolution and file I/O only. Neither class performs cryptographic operations or database access.

OCPNew crypto object types are handled by adding a branch in

_CertSerializer.serialise without modifying LocalStorage.

LSPLocalStorage fully honours the BaseStorage contract, including

the idempotent-delete and FileAlreadyExists raise semantics.

DIPConsumers depend on BaseStorage; LocalStorage is injected

at construction time.

class tiny_ca.storage.local_storage.LocalStorage(base_folder='./certs', base_encoding=Encoding.PEM, base_private_format=PrivateFormat.TraditionalOpenSSL, base_public_format=PublicFormat.SubjectPublicKeyInfo, base_encryption_algorithm=<cryptography.hazmat.primitives._serialization.NoEncryption object>, logger=None)

Bases: BaseStorage

Local filesystem storage backend for certificate artefacts.

Writes serialised cryptographic objects to a configurable directory tree. Each issuance group (certificate + key + CSR) is placed in a dedicated UUID subdirectory so that all artefacts for a given certificate can be found and deleted together.

Directory layout

<base_folder>/
└── [cert_path/]
    └── [<uuid>/]
        ├── <file_name>.pem   # x509.Certificate or CRL
        ├── <file_name>.key   # RSA private key
        ├── <file_name>.csr   # certificate signing request
        └── <file_name>.pub   # RSA public key (if applicable)

type base_folder:

str | Path

param base_folder:

Root directory under which all certificates are stored. The directory is created on first write if it does not exist. Default: "./certs".

type base_folder:

str | Path

type base_encoding:

Encoding

param base_encoding:

Default encoding for all serialised objects. Default: Encoding.PEM.

type base_encoding:

serialization.Encoding

type base_private_format:

PrivateFormat

param base_private_format:

Default format for RSA private-key files. Default: PrivateFormat.TraditionalOpenSSL (PKCS#1, OpenSSL-compatible).

type base_private_format:

serialization.PrivateFormat

type base_public_format:

PublicFormat

param base_public_format:

Default format for RSA public-key files. Default: PublicFormat.SubjectPublicKeyInfo (PKCS#8 / X.509 SubjectPublicKeyInfo).

type base_public_format:

serialization.PublicFormat

type base_encryption_algorithm:

KeySerializationEncryption

param base_encryption_algorithm:

Default encryption applied to private-key files. Default: NoEncryption() — keys are stored in plaintext.

type base_encryption_algorithm:

serialization.KeySerializationEncryption

type logger:

Logger | None

param logger:

Logger for diagnostic messages. Falls back to DEFAULT_LOGGER.

type logger:

Logger | None

__init__(base_folder='./certs', base_encoding=Encoding.PEM, base_private_format=PrivateFormat.TraditionalOpenSSL, base_public_format=PublicFormat.SubjectPublicKeyInfo, base_encryption_algorithm=<cryptography.hazmat.primitives._serialization.NoEncryption object>, logger=None)

Parameters:

• base_folder (str | Path)

• base_encoding (Encoding)

• base_private_format (PrivateFormat)

• base_public_format (PublicFormat)

• base_encryption_algorithm (KeySerializationEncryption)

• logger (Logger | None)

Return type:

None

delete_certificate_folder(uuid_str, cert_path=None)

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:

True — directory removed, or path was already absent. False — OSError occurred; check logs for details.

Return type:

bool

Warns:

UserWarning – If the target path does not exist or is not a directory.

save_certificate(cert, file_name, cert_path=None, uuid_str=None, encoding=None, private_format=None, public_format=None, encryption_algorithm=None, is_add_uuid=True, is_overwrite=False)

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:

(absolute_path_to_written_file, uuid_used). uuid_used is None when is_add_uuid is False.

Return type:

tuple[Path, str | None]

Raises:

• FileAlreadyExists – If the computed target path already exists and is_overwrite is False.

• TypeError – If cert is not a supported cryptographic type.

Parameters:

• base_folder (str | Path)

• base_encoding (serialization.Encoding)

• base_private_format (serialization.PrivateFormat)

• base_public_format (serialization.PublicFormat)

• base_encryption_algorithm (serialization.KeySerializationEncryption)

• logger (Logger | None)