tiny_ca.managers package

class tiny_ca.managers.CertLifecycleManager(storage=<tiny_ca.storage.local_storage.LocalStorage object>, factory=None, db_handler=None, logger=None)[source]

Bases: object

Orchestrates the full lifecycle of X.509 certificates.

CertLifecycleManager is the facade that application code interacts with. It coordinates four collaborators through dependency injection:

  • CertificateFactory — cryptographic generation of certificates and CRLs.

  • BaseStorage — persistent storage of PEM/key/CSR/CRL files.

  • BaseDB — registration, lookup, revocation, and rotation

    records in a relational database.

  • Logger — structured operational logging.

All three external collaborators are optional at construction time, but specific operations will raise ValueError or DBNotInitedError if a required collaborator is absent when that operation is invoked.

Parameters:

  • storage (BaseStorage) – File storage backend. Defaults to LocalStorage() which writes to ./certs relative to the working directory.

  • factory (CertificateFactory | None) – Cryptographic factory. Must be set before calling issue_certificate, generate_crl, or verify_certificate. Can be set after construction via the factory property setter.

  • db_handler (BaseDB | None) – Database adapter. When None, all operations that require persistence (status lookup, revocation, rotation) will raise DBNotInitedError.

  • logger (Logger | None) – Logger for operational messages. Falls back to DEFAULT_LOGGER.

Raises:

  • TypeError – If storage is not a BaseStorage instance.

  • TypeError – If db_handler is provided but is not a BaseDB instance.

__init__(storage=<tiny_ca.storage.local_storage.LocalStorage object>, factory=None, db_handler=None, logger=None)[source]
Parameters:
Return type:

None

cosign_certificate(cert, days_valid=None, valid_from=None)[source]
Return type:

Certificate

Parameters:

  • cert (Certificate)

  • days_valid (int | None)

  • valid_from (datetime | None)

create_self_signed_ca(config, cert_path=None, uuid_str=None, is_overwrite=False)[source]

Generate a self-signed root CA certificate and persist both artefacts.

Delegates cryptographic generation to CertificateFactory.build_self_signed_ca and then saves the certificate and private key through the configured BaseStorage. When a db_handler is present the certificate is also registered in the database.

Parameters:

  • config (CAConfig) – Pydantic model carrying common_name, organization, country, key_size, and days_valid.

  • cert_path (str | None) – Sub-directory under the storage base folder. None places the files directly in the base folder.

  • uuid_str (str | None) – Explicit UUID for the storage sub-directory. None causes the storage layer to generate one automatically.

  • is_overwrite (bool) – When True, any existing certificate with the same CN is revoked and its files are deleted before the new one is saved. When False (default), NotUniqueCertOwner is raised if a conflict exists.

Returns:

(path_to_cert_pem, path_to_key_pem) as returned by the storage layer.

Return type:

tuple[str, str]

delete_certificate(serial, cert_path=None)[source]

Hard-delete a certificate from the DB and its artefact folder from storage.

Returns True if the DB row was deleted (storage deletion is best-effort).

Return type:

bool

Parameters:

  • serial (int)

  • cert_path (str | None)

export_pkcs12(cert, private_key, password=None, name=None)[source]

Pack cert + key into a PKCS#12 bundle. Delegates to CertificateFactory.export_pkcs12.

Return type:

bytes

Parameters:
property factory: CertificateFactory | None

The active CertificateFactory used for certificate issuance.

Returns:

The current factory, or None if not yet initialised.

Return type:

CertificateFactory | None

generate_crl(cert_path=None, days_valid=1)[source]

Build, sign, and persist a fresh Certificate Revocation List.

Retrieves all currently-revoked certificates from the database, passes them to CertificateFactory.build_crl, and writes the resulting CRL to storage as crl.pem (overwriting any previous version — CRLs are always regenerated in-place).

Parameters:

  • days_valid (int) – Number of days until the CRL’s nextUpdate field. Relying parties will reject the CRL after this point. Default: 1.

  • cert_path (str | None)

Returns:

The signed CRL object (also persisted to storage).

Return type:

x509.CertificateRevocationList

Raises:
get_cert_chain(cert)[source]

Return [cert, ca_cert] chain. Delegates to CertificateFactory.get_cert_chain.

Return type:

list[Certificate]

Parameters:

cert (Certificate)

get_certificate_status(serial)[source]

Determine the current status of the certificate identified by serial.

Looks up the certificate record in the database and evaluates its state in the following priority order: 1. Not found → UNKNOWN 2. Revocation date is set → REVOKED 3. not_valid_after is in the past → EXPIRED 4. Otherwise → VALID

Parameters:

serial (int) – Integer serial number of the certificate to check.

Returns:

One of VALID, REVOKED, EXPIRED, or UNKNOWN.

Return type:

CertificateStatus

Raises:

DBNotInitedError – If no db_handler was provided.

get_expiring_soon(within_days=30)[source]

Return VALID certs expiring within within_days days. Requires db_handler.

Return type:

list[CertificateRecord]

Parameters:

within_days (int)

inspect_certificate(cert)[source]
Return type:

CertificateDetails

Parameters:

cert (Certificate)

issue_certificate(config, cert_path=None, uuid_str=None, is_overwrite=False)[source]

Issue a new end-entity certificate and persist all three artefacts.

The method generates the certificate, private key, and CSR via the configured CertificateFactory, then saves each file through BaseStorage. If a db_handler is configured the certificate metadata is also written to the database.

Artefacts written to storage

  • <file_name>.pem — the signed certificate.

  • <file_name>.key — the private key (unencrypted by default).

  • <file_name>.csr — the certificate signing request (for audit).

type config:

ClientConfig

param config:

Pydantic model containing all certificate parameters: common_name, serial_type, key_size, days_valid, email, is_server_cert, is_client_cert, san_dns, san_ip, and an optional name for the output file basename.

type config:

ClientConfig

type cert_path:

str | None

param cert_path:

Sub-directory under the storage base folder.

type cert_path:

str | None

type uuid_str:

str | None

param uuid_str:

Explicit UUID; None auto-generates one.

type uuid_str:

str | None

type is_overwrite:

bool

param is_overwrite:

Allow replacing an existing certificate with the same CN.

type is_overwrite:

bool

returns:

(certificate, private_key, csr) in-memory objects.

rtype:

tuple[x509.Certificate, rsa.RSAPrivateKey, x509.CertificateSigningRequest]

raises ValueError:

If self.factory has not been initialised.

raises NotUniqueCertOwner:

If is_overwrite is False and a certificate with the same CN already exists in the database.

Parameters:
Return type:

tuple[Certificate, object, CertificateSigningRequest]

issue_intermediate_ca(common_name, key_size=4096, days_valid=1825, valid_from=None, path_length=0, organization=None, country=None, cert_path=None, uuid_str=None)[source]

Issue a subordinate CA cert signed by this CA and save artefacts.

Returns (cert, private_key). The cert is NOT registered in the DB automatically — call register_cert_in_db if persistence is needed.

Return type:

tuple[Certificate, object]

Parameters:

  • common_name (str)

  • key_size (int)

  • days_valid (int)

  • valid_from (datetime)

  • path_length (int | None)

  • organization (str | None)

  • country (str | None)

  • cert_path (str | None)

  • uuid_str (str | None)

list_certificates(status=None, key_type=None, limit=100, offset=0)[source]

Return paginated certificate records. Requires db_handler.

Return type:

list[CertificateRecord]

Parameters:

  • status (str | None)

  • key_type (str | None)

  • limit (int)

  • offset (int)

refresh_expired_statuses()[source]

Bulk-mark expired certificates. Returns count of updated rows.

Return type:

int

renew_certificate(serial, days_valid=365, valid_from=None)[source]

Renew the certificate identified by serial: same key, new validity window.

Fetches the certificate PEM from the database, deserialises it, and delegates to CertificateFactory.renew_certificate.

Raises:
Return type:

Certificate

Parameters:
revoke_certificate(serial, reason)[source]

Revoke the certificate identified by serial.

Delegates to BaseDB.revoke_certificate. The record is updated in-place (status → REVOKED, revocation date and reason stored); no file is deleted. Call generate_crl afterwards to publish the updated revocation list.

Parameters:

  • serial (int) – Integer serial number of the certificate to revoke.

  • reason (x509.ReasonFlags) – RFC 5280 revocation reason code (e.g. x509.ReasonFlags.key_compromise).

Returns:

True if the revocation was recorded successfully; False if the operation failed (see logs for details).

Return type:

bool

Raises:

DBNotInitedError – If no db_handler was provided at construction time.

rotate_certificate(serial, config)[source]

Revoke an existing certificate and issue a replacement in a single operation.

The old certificate is revoked with reason superseded before the new one is issued. Both operations are performed against the configured db_handler; if the revocation fails an exception is propagated and the new certificate is not issued.

Parameters:

  • serial (int) – Serial number of the certificate to replace.

  • config (ClientConfig) – Parameters for the replacement certificate. The CN may differ from the original.

Returns:

(new_certificate, new_private_key, new_csr).

Return type:

tuple[x509.Certificate, rsa.RSAPrivateKey, x509.CertificateSigningRequest]

Raises:
verify_certificate(cert)[source]

Perform a full verification of cert: chain, signature, and revocation.

Combines cryptographic validation (via CertificateFactory.validate_cert) with a database revocation check (via get_certificate_status).

Validation steps

  1. Issuer field matches the CA subject.

  2. Current UTC time is within the validity window.

  3. Cryptographic signature is valid.

  4. Certificate is not listed as revoked in the database.

type cert:

Certificate

param cert:

The certificate object to verify.

type cert:

x509.Certificate

returns:

True when all checks pass.

rtype:

bool

raises ValueError:

If self.factory has not been initialised.

raises ValidationCertError:

If the certificate fails any cryptographic check or is revoked.

Parameters:

cert (Certificate)

Return type:

bool

verify_crl(crl)[source]

Verify CRL signature and expiry. Delegates to CertificateFactory.verify_crl.

Return type:

None

Parameters:

crl (CertificateRevocationList)

Submodules