pki.models.ca ============= .. py:module:: pki.models.ca .. autoapi-nested-parse:: Module that contains the CaModel. Module Contents --------------- .. py:data:: MIN_CRL_CYCLE_INTERVAL_HOURS :value: 0.0833 .. py:class:: CaModel(*args, **kwargs) Bases: :py:obj:`trustpoint.logger.LoggerMixin`, :py:obj:`util.db.CustomDeleteActionModel` Generic CA Model representing any Certificate Authority. This unified model can represent two types of CAs: 1. Keyless CAs: CAs where we only have the certificate (no private key). Used for trust anchors, upstream CAs, certificate chain validation. 2. Issuing CAs: CAs managed by Trustpoint that can issue certificates. For keyless CAs: Only 'certificate' field is set, 'credential' is null, ca_type is KEYLESS. For issuing CAs: 'credential' and 'ca_type' are set, 'certificate' is null. .. py:class:: CaTypeChoice(*args, **kwds) Bases: :py:obj:`django.db.models.IntegerChoices` The CaTypeChoice defines the type of CA. Depending on the type, different fields are required: - KEYLESS: Only certificate field is set (no private key) - LOCAL issuing types: credential field is set, certificate obtained locally - REMOTE issuing types: credential field is set, certificate requested remotely - REMOTE RA types: no credential/certificate, used for connection to external CAs as Registration Authority .. py:attribute:: KEYLESS .. py:attribute:: AUTOGEN_ROOT .. py:attribute:: AUTOGEN .. py:attribute:: LOCAL_UNPROTECTED .. py:attribute:: LOCAL_PKCS11 .. py:attribute:: REMOTE_EST_RA .. py:attribute:: REMOTE_CMP_RA .. py:attribute:: REMOTE_ISSUING_EST .. py:attribute:: REMOTE_ISSUING_CMP .. py:attribute:: unique_name .. py:attribute:: parent_ca .. py:attribute:: is_active .. py:attribute:: created_at .. py:attribute:: updated_at .. py:attribute:: ca_type .. py:attribute:: certificate .. py:attribute:: credential :type: django.db.models.OneToOneField[pki.models.credential.CredentialModel | None] .. py:attribute:: chain_truststore .. py:attribute:: remote_host .. py:attribute:: remote_port .. py:attribute:: remote_path .. py:attribute:: est_username .. py:attribute:: onboarding_config .. py:attribute:: no_onboarding_config .. py:attribute:: crl_cycle_enabled .. py:attribute:: crl_cycle_interval_hours .. py:attribute:: crl_validity_hours .. py:attribute:: last_crl_generation_started_at .. py:attribute:: auto_crl_on_revocation_enabled .. py:class:: Meta Meta options for CaModel. .. py:attribute:: verbose_name .. py:attribute:: verbose_name_plural .. py:attribute:: db_table :value: 'pki_genericcamodel' .. py:attribute:: ordering :type: ClassVar[list[str]] :value: ['unique_name'] .. py:attribute:: constraints :type: ClassVar[list[django.db.models.BaseConstraint]] .. py:property:: is_issuing_ca :type: bool Returns True if this is an issuing CA (can issue certificates). .. py:property:: is_keyless_ca :type: bool Returns True if this is a keyless CA, or a remote RA with a certificate. .. py:property:: common_name :type: str Returns common name, or a placeholder if missing. .. py:property:: subject_public_bytes :type: bytes Returns the subject public bytes from the CA certificate, or b'' if missing. .. py:property:: ca_certificate_model :type: pki.models.certificate.CertificateModel | None Returns the CA certificate model for both issuing and keyless CAs, or None if missing. .. py:method:: get_certificate() Returns the CA certificate (crypto object) for both issuing and keyless CAs, or None if missing. .. py:method:: get_credential() Returns the credential for issuing CAs, or None if not present. .. py:method:: get_ca_chain_from_truststore() Returns the CA chain from the associated chain_truststore. This method validates that the chain_truststore contains certificates that correspond to CAs in the hierarchy path, and returns the CA objects in issuing CA to root order. :returns: List of CA models from issuing CA to root CA. :rtype: list[CaModel] :raises ValueError: If the chain_truststore is not properly configured or contains invalid certificates. .. py:property:: last_crl_issued_at :type: datetime.datetime | None Returns when the last CRL was issued (from active CRL). :returns: The this_update time of the active CRL, or None if no CRL exists. :rtype: datetime | None .. py:property:: crl_number :type: int Returns the current CRL number (from active CRL). :returns: The CRL number of the active CRL, or 0 if no CRL exists. :rtype: int .. py:property:: crl_pem :type: str Returns the active CRL in PEM format. :returns: The CRL in PEM format, or empty string if no CRL exists. :rtype: str .. py:property:: next_crl_generation_scheduled_at :type: datetime.datetime | None Returns when the next CRL generation is scheduled. :returns: The scheduled time for the next CRL generation, or None if not enabled or not scheduled. :rtype: datetime | None .. py:method:: clean() Validates that exactly one of certificate or credential is set. .. py:method:: save(*args, **kwargs) Override save to ensure validation. .. py:method:: create_keyless_ca(unique_name, certificate_obj, parent_ca = None) :classmethod: Creates a new keyless CA from a certificate. :param unique_name: The unique name that will be used to identify the CA. :param certificate_obj: The CA certificate as cryptography x509.Certificate. :param parent_ca: Optional parent CA in the hierarchy. :returns: The newly created keyless CA. :rtype: CaModel :raises ValidationError: If the certificate is not a valid CA certificate. .. py:method:: create_new_issuing_ca(credential_serializer, ca_type = None, unique_name = None, parent_ca = None) :classmethod: Creates a new Issuing CA model. :param credential_serializer: The credential as CredentialSerializer instance. It will be normalized and validated, if it is a valid credential to be used as an Issuing CA. :param ca_type: The CA type (must be an issuing type, not KEYLESS). :param unique_name: The unique name for the CA. If not provided, will be auto-generated from certificate common name. :param parent_ca: Optional parent CA in the hierarchy. :returns: The newly created Issuing CA model. :rtype: CaModel :raises ValidationError: If the certificate is not a valid CA certificate. :raises ValueError: If the CA type is not supported .. py:method:: issue_crl(crl_validity_hours = 24) Issues a CRL with revoked certificates issued by this CA. :param crl_validity_hours: Hours until the next CRL update (nextUpdate field). Defaults to 24. :returns: True if the CRL was successfully issued, False otherwise. :rtype: bool .. py:property:: signature_suite :type: trustpoint_core.oid.SignatureSuite | None The signature suite for the CA public key certificate, or None if missing. .. py:property:: public_key_info :type: trustpoint_core.oid.PublicKeyInfo | None The public key info for the CA certificate's public key. Returns None if the CA doesn't have a certificate yet (e.g., remote CA pending). .. py:method:: get_issued_certificates() Returns certificates issued by this CA, except its own in case of a self-signed CA. This goes through all active certificates and checks issuance by this CA based on cert.issuer_public_bytes == ca.subject_public_bytes. .. warning:: This means that it may inadvertently return certificates that were issued by a different CA with the same subject name. :returns: Certificates issued by this CA, or empty queryset for RAs/keyless CAs. :rtype: QuerySet .. py:method:: import_crl(crl_pem, *, set_active = True) Imports a CRL for this CA. :param crl_pem: The CRL in PEM format. :param set_active: If True, this CRL becomes the active one for the CA. :returns: The created CRL model. :rtype: CrlModel :raises ValidationError: If the CRL is invalid or doesn't match this CA. .. py:method:: get_active_crl() Returns the currently active CRL for this CA. :returns: The active CRL or None if no CRL exists. :rtype: CrlModel | None .. py:method:: get_latest_crl() Returns the most recent CRL for this CA (by this_update). :returns: The latest CRL or None if no CRL exists. :rtype: CrlModel | None .. py:method:: get_crl_as_crypto() Returns the active CRL as a cryptography CertificateRevocationList object. :returns: The CRL or None if no active CRL is available. :rtype: x509.CertificateRevocationList | None .. py:method:: schedule_next_crl_generation(*, post_revocation_crl = False) Schedule the next CRL generation task for this CA using Django-Q2. Creates a scheduled task in Django-Q2 that will execute at the calculated time. The task will automatically trigger CRL generation without manual intervention. .. py:method:: get_hierarchy_depth() Returns the depth of this CA in the hierarchy. :returns: The depth (0 for root CA, 1 for intermediate, etc.) :rtype: int .. py:method:: get_root_ca() Returns the root CA in the hierarchy. :returns: The root CA (self if this is already a root CA). :rtype: CaModel .. py:method:: get_all_child_cas(*, include_self = False) Returns all descendant CAs (children, grandchildren, etc.). :param include_self: If True, includes this CA in the result. :returns: All descendant CAs. :rtype: QuerySet .. py:method:: get_hierarchy_path() Returns the path from root CA to this CA. :returns: List of CAs from root to this CA (inclusive). :rtype: list[CaModel] .. py:method:: is_root_ca() Returns True if this CA has no parent (is a root CA). :returns: True if this is a root CA. :rtype: bool .. py:method:: revoke_all_issued_certificates(reason = RevokedCertificateModel.ReasonCode.UNSPECIFIED) Revokes all certificates issued by this CA. .. py:method:: pre_delete() Checks for unexpired certificates issued by this CA and child CAs before deleting it. :raises ValidationError: If there are unexpired certificates issued by this CA or if this CA has child CAs. .. py:method:: post_delete() Deletes the underlying credential or certificate after deleting this CA. .. py:property:: display_not_valid_after :type: datetime.datetime | None Returns the not valid after date for display purposes.