pki.models.credential

Module that contains the CredentialModel.

Exceptions

CredentialAlreadyExistsError

The CredentialAlreadyExistsError is raised if a credential already exists in the database.

Classes

PKCS11Key	Model representing a private key stored in a PKCS#11 HSM/token.
CredentialModel	The CredentialModel that holds all local credentials used by the Trustpoint.
PrimaryCredentialCertificate	Model to store which certificate is the primary certificate of a credential.
CertificateChainOrderModel	This Model is used to preserve the order of certificates in credential certificate chains.
IDevIDReferenceModel	Model to store the string referencing an IDevID certificate.
OwnerCredentialModel	Device owner credential model.

Module Contents

exception pki.models.credential.CredentialAlreadyExistsError(*args, **kwargs)

Bases: django.core.exceptions.ValidationError

The CredentialAlreadyExistsError is raised if a credential already exists in the database.

Parameters:

• args (Any)

• kwargs (Any)

class pki.models.credential.PKCS11Key(*args, **kwargs)

Bases: django.db.models.Model

Model representing a private key stored in a PKCS#11 HSM/token.

class KeyType(*args, **kwds)

Bases: django.db.models.TextChoices

Supported key types in PKCS#11.

RSA

EC

AES

token_label

key_label

key_type

created_at

class Meta

Meta class to define unique constraints and verbose names for the PKCS11Key model.

unique_together: ClassVar = [['token_label', 'key_label']]

verbose_name

verbose_name_plural

__str__()

Return a string representation of the PKCS11Key instance.

Return type:

str

get_pkcs11_key_instance(lib_path, user_pin)

Get the appropriate PKCS#11 key instance.

Parameters:

• lib_path (str)

• user_pin (str)

Return type:

management.pkcs11_util.Pkcs11RSAPrivateKey | management.pkcs11_util.Pkcs11ECPrivateKey | management.pkcs11_util.Pkcs11AESKey

class pki.models.credential.CredentialModel(*args, **kwargs)

Bases: trustpoint.logger.LoggerMixin, 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.

class CredentialTypeChoice(*args, **kwds)

Bases: 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.

TRUSTPOINT_TLS_SERVER

ROOT_CA

ISSUING_CA

ISSUED_CREDENTIAL

DEV_OWNER_ID

SIGNER

credential_type

private_key

pkcs11_private_key

certificate

certificates

certificate_chain: django.db.models.ManyToManyField[pki.models.CertificateModel, CertificateChainOrderModel]

created_at

__repr__()

Returns a string representation of this CredentialModel entry.

Return type:

str

__str__()

Returns a human-readable string that represents this CredentialModel entry.

Returns:

Human-readable string that represents this CredentialModel entry.

Return type:

str

clean()

Validates the CredentialModel instance.

Return type:

None

classmethod save_credential_serializer(credential_serializer, credential_type)

This method will try to normalize the credential_serializer and then save it to the database.

Parameters:

• credential_serializer (trustpoint_core.serializer.CredentialSerializer) – The credential serializer to store in the database.

• credential_type (CredentialModel) – The credential type to set.

Returns:

The stored credential model.

Return type:

CredentialModel

property ordered_certificate_chain_queryset: django.db.models.QuerySet[CertificateChainOrderModel]

Gets the ordered certificate chain queryset.

Return type:

django.db.models.QuerySet[CertificateChainOrderModel]

classmethod _import_private_key_to_hsm(crypto_private_key, token_config, key_label)

Import a private key to HSM and create corresponding PKCS11Key model.

Parameters:

• crypto_private_key (trustpoint_core.crypto_types.PrivateKey) – The private key from cryptography library

• key_label (str) – Custom label for the key (auto-generated if None)

• token_config (management.models.PKCS11Token) – PKCS11Token configuration

Returns:

The created model instance referencing the HSM key

Return type:

PKCS11Key

Raises:

• RuntimeError – If HSM import fails

• ValueError – If unsupported key type

• NotImplementedError – If EC key import not yet supported

classmethod _create_private_key_in_hsm(key_type, token_config, key_label, key_size=None, key_curve=None)

Generate a new private key in HSM and create corresponding PKCS11Key model.

Parameters:

• key_type (type[trustpoint_core.crypto_types.PrivateKey]) – Type of key to generate (‘rsa.PrivateKey’ or ‘ec.PrivateKey’)

• token_config (management.models.PKCS11Token) – PKCS11Token configuration

• key_label (str) – Label for the new key in HSM

• key_size (int | None) – For RSA keys: key size in bits (e.g., 2048, 4096)

• key_curve (cryptography.hazmat.primitives.asymmetric.ec.EllipticCurve | None) – For EC keys: curve instance (e.g., ec.SECP256R1())

Returns:

The created model instance referencing the HSM key

Return type:

PKCS11Key

Raises:

• RuntimeError – If HSM key generation fails

• ValueError – If unsupported key type or invalid parameters

• NotImplementedError – If EC key generation not yet supported

static _validate_hsm_inputs(token_config, key_label, key_type, key_size, key_curve)

Validates the inputs for HSM key creation.

Parameters:

• token_config (management.models.PKCS11Token)

• key_label (str)

• key_type (type[trustpoint_core.crypto_types.PrivateKey])

• key_size (int | None)

• key_curve (cryptography.hazmat.primitives.asymmetric.ec.EllipticCurve | None)

Return type:

None

static _initialize_key_handler(key_type, token_config, key_label, key_size, key_curve)

Initializes the PKCS#11 key handler.

Parameters:

• key_type (type[trustpoint_core.crypto_types.PrivateKey])

• token_config (management.models.PKCS11Token)

• key_label (str)

• key_size (int | None)

• key_curve (cryptography.hazmat.primitives.asymmetric.ec.EllipticCurve | None)

Return type:

tuple[management.pkcs11_util.Pkcs11RSAPrivateKey | management.pkcs11_util.Pkcs11ECPrivateKey, str]

classmethod _save_normalized_credential_serializer(normalized_credential_serializer, credential_type)

This method will store a credential that is expected to be normalized.

Parameters:

• normalized_credential_serializer (trustpoint_core.serializer.CredentialSerializer)

• credential_type (CredentialModel)

Return type:

CredentialModel

static _validate_and_save_certificate(normalized_credential_serializer)

Validates and saves the certificate from the provided serializer.

Parameters:

normalized_credential_serializer (CredentialSerializer) – The serializer containing the certificate to be validated and saved.

Raises:

ValueError – If the certificate in the serializer is None.

Returns:

The saved certificate model instance.

Return type:

CertificateModel

classmethod _process_private_key(normalized_credential_serializer)

Processes the private key based on its location and returns the appropriate values.

Parameters:

normalized_credential_serializer (trustpoint_core.serializer.CredentialSerializer)

Return type:

tuple[PKCS11Key | None, str]

classmethod _handle_hsm_key(normalized_credential_serializer)

Handles the creation or import of a private key in an HSM (Hardware Security Module).

Parameters:

normalized_credential_serializer (trustpoint_core.serializer.CredentialSerializer)

Return type:

PKCS11Key

classmethod _create_credential_model(certificate, credential_type, private_key_pem, pkcs11_private_key)

Creates and saves a CredentialModel instance.

Parameters:

• certificate (pki.models.CertificateModel)

• credential_type (CredentialModel)

• private_key_pem (str)

• pkcs11_private_key (PKCS11Key | None)

Return type:

CredentialModel

static _save_additional_certificates(credential_model, additional_certificates)

Saves additional certificates in the certificate chain.

Parameters:

• credential_model (CredentialModel)

• additional_certificates (list[cryptography.x509.Certificate])

Return type:

None

classmethod save_keyless_credential(certificate, certificate_chain, credential_type)

Stores a credential without a private key.

Parameters:

• certificate (cryptography.x509.Certificate)

• certificate_chain (list[cryptography.x509.Certificate])

• credential_type (CredentialModel)

Return type:

CredentialModel

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.

Parameters:

• certificate (cryptography.x509.Certificate)

• certificate_chain (list[cryptography.x509.Certificate])

Return type:

None

pre_delete()

Deletes related models, only allow deletion if there are no more active certificates.

Return type:

None

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.

Return type:

PrivateKey

get_pkcs11_private_key()

Gets the private key abstraction.

Return type:

trustpoint_core.crypto_types.PrivateKey

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.

Return type:

PrivateKeySerializer

Raises:

RuntimeError – If no private key information is available.

get_certificate()

Gets the credential certificate as x509.Certificate instance.

Returns:

The credential certificate.

Return type:

x509.Certificate

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.

Return type:

list[x509.Certificate]

get_certificate_serializer()

Gets the credential certificate as a CertificateSerializer instance.

Returns:

The credential certificate.

Return type:

CertificateSerializer

get_certificate_chain_serializer()

Gets the credential certificate chain as a CertificateCollectionSerializer instance.

Returns:

The credential certificate chain.

Return type:

CertificateCollectionSerializer

get_last_in_chain()

Gets the root ca certificate model, if any.

Return type:

None | pki.models.CertificateModel

get_root_ca_certificate()

Gets the root CA certificate of the credential certificate chain.

Return type:

None | cryptography.x509.Certificate

get_root_ca_certificate_serializer()

Gets the root CA certificate serializer.

Return type:

None | trustpoint_core.serializer.CertificateSerializer

get_credential_serializer()

Gets the serializer for this credential.

Return type:

trustpoint_core.serializer.CredentialSerializer

property signature_suite: trustpoint_core.oid.SignatureSuite

Returns the signature suite used by the current credential primary certificate.

Return type:

trustpoint_core.oid.SignatureSuite

property public_key_info: trustpoint_core.oid.PublicKeyInfo

Returns the PublicKeyInfo the current credential primary certificate.

Return type:

trustpoint_core.oid.PublicKeyInfo

property hash_algorithm: cryptography.hazmat.primitives.hashes.HashAlgorithm | None

Returns the hash algorithm used by the current credential.

Return type:

cryptography.hazmat.primitives.hashes.HashAlgorithm | None

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.

Return type:

tuple[bool, str]

class pki.models.credential.PrimaryCredentialCertificate(*args, **kwargs)

Bases: 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.

credential

certificate

is_primary

__repr__()

Returns a string representation of this PrimaryCredentialCertificate entry.

Return type:

str

__str__()

Returns a human-readable string that represents this PrimaryCredentialCertificate entry.

Return type:

str

save(*args, **kwargs)

If a new certificate is added to a credential, it is set to primary and all others to non-primary.

Parameters:

• args (Any)

• kwargs (Any)

Return type:

None

class pki.models.credential.CertificateChainOrderModel(*args, **kwargs)

Bases: django.db.models.Model

This Model is used to preserve the order of certificates in credential certificate chains.

certificate

credential

order

primary_certificate

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.

ordering: ClassVar = ['order']

constraints: ClassVar

__repr__()

Returns a string representation of this CertificateChainOrderModel entry.

Return type:

str

__str__()

Returns a human-readable string that represents this CertificateChainOrderModel entry.

Returns:

Human-readable string that represents this CertificateChainOrderModel entry.

Return type:

str

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.

Parameters:

• *args (Any) – Positional arguments, passed to super().save()

• **kwargs (Any) – Keyword arguments, passed to super().save()

Returns:

None

Raises:

ValueError – If the CertificateChainOrderModel entry to be stored does not have the correct order.

Return type:

None

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.

Parameters:

• *args (Any) – Positional arguments, passed to super().delete()

• **kwargs (Any) – 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.

Return type:

tuple[int, dict[str, int]]

_get_max_order()

Gets highest order of a certificate of a credential certificate chain.

Returns:

The highest order of a certificate of a credential certificate chain.

Return type:

int

class pki.models.credential.IDevIDReferenceModel(*args, **kwargs)

Bases: django.db.models.Model

Model to store the string referencing an IDevID certificate.

Obtained from the SAN of the DevOwnerID certificate.

dev_owner_id

idevid_ref

__str__()

Returns a human-readable string that represents this IDevIDRefSanModel entry.

Return type:

str

property idevid_subject_serial_number: str

Returns the IDevID Subject Serial Number from the SAN of the DevOwnerID certificate.

Return type:

str

property idevid_x509_serial_number: str

Returns the IDevID X.509 Serial Number from the SAN of the DevOwnerID certificate.

Return type:

str

property idevid_sha256_fingerprint: str

Returns the IDevID SHA256 Fingerprint from the SAN of the DevOwnerID certificate.

Return type:

str

class pki.models.credential.OwnerCredentialModel(*args, **kwargs)

Bases: trustpoint.logger.LoggerMixin, util.db.CustomDeleteActionModel

Device owner credential model.

This model is a wrapper to store a DevOwnerID Credential for use by devices to trust the Trustpoint.

unique_name

credential: django.db.models.OneToOneField[CredentialModel]

created_at

__str__()

Returns a human-readable string that represents this OwnerCredentialModel entry.

Returns:

Human-readable string that represents this OwnerCredentialModel entry.

Return type:

str

__repr__()

Returns a string representation of the OwnerCredentialModel instance.

Return type:

str

classmethod create_new_owner_credential(unique_name, credential_serializer)

Creates a new owner credential model and returns it.

Parameters:

• unique_name (str) – The unique name that will be used to identify the Owner Credential.

• credential_serializer (trustpoint_core.serializer.CredentialSerializer) – The credential as CredentialSerializer instance.

Returns:

The newly created owner credential model.

Return type:

OwnerCredentialModel

post_delete()

Deletes the credential of this owner credential after deleting it.

Return type:

None