pki.models.credential ===================== .. py:module:: pki.models.credential .. autoapi-nested-parse:: Module that contains the CredentialModel. Module Contents --------------- .. py:exception:: CredentialAlreadyExistsError(*args, **kwargs) Bases: :py:obj:`django.core.exceptions.ValidationError` The CredentialAlreadyExistsError is raised if a credential already exists in the database. .. py:class:: PKCS11Key(*args, **kwargs) Bases: :py:obj:`django.db.models.Model` Model representing a private key stored in a PKCS#11 HSM/token. .. py:class:: KeyType(*args, **kwds) Bases: :py:obj:`django.db.models.TextChoices` Supported key types in PKCS#11. .. py:attribute:: RSA .. py:attribute:: EC .. py:attribute:: AES .. py:attribute:: token_label .. py:attribute:: key_label .. py:attribute:: key_type .. py:attribute:: created_at .. py:class:: Meta Meta class to define unique constraints and verbose names for the PKCS11Key model. .. py:attribute:: unique_together :type: ClassVar :value: [['token_label', 'key_label']] .. py:attribute:: verbose_name .. py:attribute:: verbose_name_plural .. py:method:: get_pkcs11_key_instance(lib_path, user_pin) Get the appropriate PKCS#11 key instance. .. py:class:: CredentialModel(*args, **kwargs) Bases: :py:obj:`trustpoint.logger.LoggerMixin`, :py:obj:`util.db.CustomDeleteActionModel` The CredentialModel that holds all local credentials used by the Trustpoint. This model holds both local unprotected credentials, for which the keys and certificates are stored in the DB, but also credentials that are stored within an HSM or TPM utilizing PKCS#11. PKCS#11 credentials are not yet supported. .. py:class:: CredentialTypeChoice(*args, **kwds) Bases: :py:obj:`django.db.models.IntegerChoices` The CredentialTypeChoice defines the type of the credential and thus implicitly restricts its usage. It is intended to limit the credential usage to specific cases, e.g. usage as Issuing CA. The abstractions using the CredentialModel are responsible to check that the credential has the correct and expected CredentialTypeChoice. .. py:attribute:: TRUSTPOINT_TLS_SERVER .. py:attribute:: ROOT_CA .. py:attribute:: ISSUING_CA .. py:attribute:: ISSUED_CREDENTIAL .. py:attribute:: DEV_OWNER_ID .. py:attribute:: SIGNER .. py:attribute:: credential_type .. py:attribute:: private_key .. py:attribute:: pkcs11_private_key .. py:attribute:: certificate .. py:attribute:: certificates .. py:attribute:: certificate_chain :type: django.db.models.ManyToManyField[pki.models.CertificateModel, CertificateChainOrderModel] .. py:attribute:: created_at .. py:method:: clean() Validates the CredentialModel instance. .. py:property:: certificate_or_error :type: pki.models.CertificateModel Returns the certificate, raising an error if it is None. :returns: The non-null certificate. :rtype: CertificateModel :raises ValueError: If certificate is None. .. py:method:: save_credential_serializer(credential_serializer, credential_type) :classmethod: This method will try to normalize the credential_serializer and then save it to the database. :param credential_serializer: The credential serializer to store in the database. :param credential_type: The credential type to set. :returns: The stored credential model. :rtype: CredentialModel .. py:property:: ordered_certificate_chain_queryset :type: django.db.models.QuerySet[CertificateChainOrderModel] Gets the ordered certificate chain queryset. .. py:method:: save_keyless_credential(certificate, certificate_chain, credential_type) :classmethod: Stores a credential without a private key. .. py:method:: update_keyless_credential(certificate, certificate_chain) Updates the primary certificate and certificate chain of the credential. Previous certificates are kept as part of the credential. .. py:method:: pre_delete() Deletes related models, only allow deletion if there are no more active certificates. .. py:method:: get_private_key() Gets an abstraction of the credential private key. Note, in the case of keys stored in an HSM or TPM using PKCS#11, it will only be possible to use the key abstraction to sign and verify, but not to export the key in any way. :returns: The credential private key abstraction. :rtype: PrivateKey .. py:method:: get_pkcs11_private_key() Gets the private key abstraction. .. py:method:: get_private_key_serializer() Gets a serializer of the credential private key. For PKCS#11 keys, since the private key cannot be exported, this method returns a PrivateKeySerializer constructed from the public key extracted from the certificate. This allows code that needs the public key (via .public_key_serializer) to work with both software-stored and HSM-stored credentials. :returns: The credential private key serializer. :rtype: PrivateKeySerializer :raises RuntimeError: If no private key information is available. .. py:method:: get_certificate() Gets the credential certificate as x509.Certificate instance. :returns: The credential certificate. :rtype: x509.Certificate .. py:method:: get_certificate_chain() Gets the credential certificate chain as a list of x509.Certificate instances. :returns: The credential certificate chain as list of x509.Certificate instances. :rtype: list[x509.Certificate] .. py:method:: get_certificate_serializer() Gets the credential certificate as a CertificateSerializer instance. :returns: The credential certificate. :rtype: CertificateSerializer :raises ValueError: If the certificate is not set. .. py:method:: get_certificate_chain_serializer() Gets the credential certificate chain as a CertificateCollectionSerializer instance. :returns: The credential certificate chain. :rtype: CertificateCollectionSerializer .. py:method:: get_last_in_chain() Gets the root ca certificate model, if any. .. py:method:: get_root_ca_certificate() Gets the root CA certificate of the credential certificate chain. .. py:method:: get_root_ca_certificate_serializer() Gets the root CA certificate serializer. .. py:method:: get_credential_serializer() Gets the serializer for this credential. .. py:property:: signature_suite :type: trustpoint_core.oid.SignatureSuite Returns the signature suite used by the current credential primary certificate. .. py:property:: public_key_info :type: trustpoint_core.oid.PublicKeyInfo Returns the PublicKeyInfo the current credential primary certificate. .. py:property:: hash_algorithm :type: cryptography.hazmat.primitives.hashes.HashAlgorithm | None Returns the hash algorithm used by the current credential. .. py:method:: is_valid_issued_credential() Determines if this issued credential is valid. This method performs the following checks: 1. The credential must be of type ISSUED_CREDENTIAL. 2. A primary certificate must exist. 3. The certificate's status must be 'OK'. :returns: A tuple where: - The first value is True if the credential meets all criteria, False otherwise. - The second value is a reason string explaining why the credential is invalid. :rtype: tuple[bool, str] .. py:class:: PrimaryCredentialCertificate(*args, **kwargs) Bases: :py:obj:`django.db.models.Model` Model to store which certificate is the primary certificate of a credential. Used as through model for the many-to-many relationship between CredentialModel and CertificateModel. .. py:attribute:: credential .. py:attribute:: certificate .. py:attribute:: is_primary .. py:method:: save(*args, **kwargs) If a new certificate is added to a credential, it is set to primary and all others to non-primary. .. py:class:: CertificateChainOrderModel(*args, **kwargs) Bases: :py:obj:`django.db.models.Model` This Model is used to preserve the order of certificates in credential certificate chains. .. py:attribute:: certificate .. py:attribute:: credential .. py:attribute:: order .. py:attribute:: primary_certificate .. py:class:: Meta This Meta class add some configuration to the CertificateChainOrderModel. Sets the default ordering such that the field order is used. Restricts entries such that the tuple (credential, order) is unique. .. py:attribute:: ordering :type: ClassVar :value: ['order'] .. py:attribute:: constraints :type: ClassVar .. py:method:: save(*args, **kwargs) Stores a CertificateChainOrderModel in the database. This is only possible if the order takes the next available value. That is, e.g. if the corresponding credential certificate chain has already two certificates stored with order 0 and 1, then the next entry to be stored must have order 2. :param \*args: Positional arguments, passed to super().save() :param \*\*kwargs: Keyword arguments, passed to super().save() :returns: None :raises ValueError: If the CertificateChainOrderModel entry to be stored does not have the correct order. .. py:method:: delete(*args, **kwargs) Tries to delete the CertificateChainOrderModel entry. A CertificateChainOrderModel entry can only be deleted if it has the highest order in the corresponding credential certificate chain. :param \*args: Positional arguments, passed to super().delete() :param \*\*kwargs: Keyword arguments, passed to super().delete() :returns: tuple[int, dict[str, int]] (returned by parent) :raises ValueError: If the CertificateChainOrderModel entry does not have the highest order in the corresponding credential certificate chain. .. py:class:: IDevIDReferenceModel(*args, **kwargs) Bases: :py:obj:`django.db.models.Model` Model to store the string referencing an IDevID certificate. Obtained from the SAN of the DevOwnerID certificate. The ``idevid_ref`` field holds the raw ``dev-owner:`` URI embedded in the DevOwnerID SAN. ``dev_owner_id_certificate`` points to the :class:`~pki.models.certificate.CertificateModel` of the DevOwnerID certificate whose SAN contained this reference, so the details view can display the DevOwnerID certificate information without a fragile fingerprint-string lookup. .. py:attribute:: dev_owner_id .. py:attribute:: idevid_ref .. py:attribute:: dev_owner_id_certificate .. py:property:: idevid_subject_serial_number :type: str Returns the IDevID Subject Serial Number from the SAN of the DevOwnerID certificate. The stored ``idevid_ref`` format is ``dev-owner:..``. This property strips the ``dev-owner:`` scheme prefix and returns the first segment. .. py:property:: idevid_x509_serial_number :type: str Returns the IDevID X.509 Serial Number from the SAN of the DevOwnerID certificate. Second dot-separated segment after stripping the ``dev-owner:`` prefix. .. py:property:: idevid_sha256_fingerprint :type: str Returns the IDevID SHA256 Fingerprint from the SAN of the DevOwnerID certificate. Third dot-separated segment after stripping the ``dev-owner:`` prefix. .. py:class:: OwnerCredentialModel(*args, **kwargs) Bases: :py:obj:`trustpoint.logger.LoggerMixin`, :py:obj:`util.db.CustomDeleteActionModel` Device owner credential model. This model is a wrapper to manage a DevOwnerID for use by devices to trust the Trustpoint. The actual DevOwnerID certificate is stored as an ``IssuedCredentialModel`` with ``issued_credential_type=DEV_OWNER_ID`` pointing back to this model. Supports two acquisition modes: - File upload / Manual: a ``NoOnboardingConfigModel`` with ``MANUAL`` protocol is created. - Remote CA enrollment: ``no_onboarding_config`` (EST username/password) or ``onboarding_config`` (EST IDevID) is set together with the remote_* fields. .. py:class:: OwnerCredentialTypeChoice(*args, **kwds) Bases: :py:obj:`django.db.models.IntegerChoices` How the DevOwnerID certificate is acquired. - ``LOCAL``: uploaded as a file or generated locally (no remote CA). - ``REMOTE_EST``: enrolled from a remote CA via EST (RFC 7030) with username/password. - ``REMOTE_CMP``: enrolled from a remote CA via CMP (RFC 4210 / 9483). - ``REMOTE_EST_ONBOARDING``: enrolled from a remote CA via EST using IDevID onboarding. .. py:attribute:: LOCAL .. py:attribute:: REMOTE_EST .. py:attribute:: REMOTE_CMP .. py:attribute:: REMOTE_EST_ONBOARDING .. py:attribute:: unique_name .. py:attribute:: owner_credential_type .. py:attribute:: remote_host .. py:attribute:: remote_port .. py:attribute:: remote_path .. py:attribute:: remote_path_domain_credential .. py:attribute:: est_username .. py:attribute:: key_type .. py:attribute:: onboarding_config .. py:attribute:: no_onboarding_config .. py:attribute:: created_at .. py:property:: dev_owner_id_credentials :type: django.db.models.QuerySet[pki.models.issued_credential.RemoteIssuedCredentialModel] Returns all DevOwnerID RemoteIssuedCredentialModel instances for this owner credential, newest first. An OwnerCredentialModel may accumulate multiple DevOwnerID credentials over time, e.g. after re-enrollment or renewal rounds. .. py:property:: dev_owner_id_credential :type: pki.models.issued_credential.RemoteIssuedCredentialModel | None Returns the most recently created DevOwnerID RemoteIssuedCredentialModel, or ``None``. Use :attr:`dev_owner_id_credentials` when you need the full set of credentials. .. py:property:: domain_credentials :type: django.db.models.QuerySet[pki.models.issued_credential.RemoteIssuedCredentialModel] Returns all Domain Credential RemoteIssuedCredentialModel instances for this owner credential, newest first. Domain credentials are obtained during onboarding before the DevOwnerID is enrolled. .. py:property:: domain_credential :type: pki.models.issued_credential.RemoteIssuedCredentialModel | None Returns the most recently created Domain Credential RemoteIssuedCredentialModel, or ``None``. .. py:property:: has_valid_domain_credential :type: bool Returns True if there is at least one valid domain credential. .. py:method:: create_new_owner_credential(unique_name, credential_serializer, no_onboarding_config = None) :classmethod: Creates a new OwnerCredentialModel with the DevOwnerID stored as RemoteIssuedCredentialModel. The DevOwnerID certificate (with optional chain and private key) is stored in a ``CredentialModel`` and wrapped in a ``RemoteIssuedCredentialModel`` of type ``DEV_OWNER_ID``. If no ``no_onboarding_config`` is provided a new ``NoOnboardingConfigModel`` with protocol ``MANUAL`` is created automatically. :param unique_name: Unique human-readable name for this owner credential. :param credential_serializer: The DevOwnerID credential (cert + optional key + chain). :param no_onboarding_config: Optional pre-created ``NoOnboardingConfigModel`` to attach. :returns: The newly created instance. :rtype: OwnerCredentialModel .. py:method:: post_delete() Deletes all remote issued credentials and the onboarding config on deletion.