pki.util.x509

Handles certificate creation for Issuing CA certificates.

Module Contents

pki.util.x509.logger[source]
class pki.util.x509.CertificateGenerator[source]

Methods for generating X.509 certificates.

static create_root_ca(cn, validity_days=7300, private_key=None, hash_algorithm=None, path_length=None)[source]

Creates a root CA certificate for testing and AutoGenPKI.

Parameters:

  • cn (str) – Common name for the root CA.

  • validity_days (int) – Validity period in days.

  • private_key (None | trustpoint_core.crypto_types.PrivateKey) – Private key to use. If None, generates new RSA-2048 key.

  • hash_algorithm (None | cryptography.hazmat.primitives.hashes.HashAlgorithm) – Hash algorithm to use for signing.

  • path_length (int | None) – Maximum number of CA certificates that may follow this certificate. If None, defaults to 1.

Returns:

Tuple of (certificate, private_key).

Return type:

tuple[cryptography.x509.Certificate, trustpoint_core.crypto_types.PrivateKey]

static create_issuing_ca(issuer_private_key, issuer_cn, subject_cn, private_key=None, validity_days=3650, hash_algorithm=None, path_length=None)[source]

Creates an issuing CA certificate + key pair.

Parameters:

  • issuer_private_key (None | trustpoint_core.crypto_types.PrivateKey) – Private key of the issuing CA. None for root CA.

  • issuer_cn (str) – Common name of the issuer.

  • subject_cn (str) – Common name of the subject.

  • private_key (None | trustpoint_core.crypto_types.PrivateKey) – Private key to use. If None, generates new RSA-2048 key.

  • validity_days (int) – Validity period in days.

  • hash_algorithm (None | cryptography.hazmat.primitives.hashes.HashAlgorithm) – Hash algorithm to use for signing.

  • path_length (int | None) – Maximum number of CA certificates that may follow this certificate in a valid certification path. If None, defaults to 1 for root CAs and 0 for intermediate CAs.

Returns:

Tuple of (certificate, private_key).

Return type:

tuple[cryptography.x509.Certificate, trustpoint_core.crypto_types.PrivateKey]

static create_ee(issuer_private_key, issuer_name, subject_name, private_key=None, extensions=None, validity_days=365)[source]

Creates a generic end entity certificate + key pair.

Parameters:

  • issuer_private_key (trustpoint_core.crypto_types.PrivateKey) – The private key of the issuer.

  • issuer_name (cryptography.x509.Name) – The full issuer Name (must be x509.Name to ensure proper certificate chain matching).

  • subject_name (str | cryptography.x509.Name) – The subject common name (str) or full subject Name.

  • private_key (None | trustpoint_core.crypto_types.PrivateKey) – The private key for the EE. If None, generates new RSA-2048 key.

  • extensions (list[tuple[cryptography.x509.ExtensionType, bool]] | None) – List of (extension, critical) tuples to add.

  • validity_days (int) – Validity period in days.

Returns:

Tuple of (certificate, private_key).

Return type:

tuple[cryptography.x509.Certificate, trustpoint_core.crypto_types.PrivateKey]

static create_test_pki(chain_depth=0)[source]

Get a test PKI chain with a specified depth (excluding root CA). depth=0 is a self-signed EE.

Parameters:

chain_depth (int)

Return type:

tuple[list[cryptography.x509.Certificate], list[trustpoint_core.crypto_types.PrivateKey]]

static save_issuing_ca(issuing_ca_cert, chain, private_key, unique_name='issuing_ca', ca_type=CaModel.CaTypeChoice.LOCAL_UNPROTECTED, parent_ca=None)[source]

Saves an Issuing CA certificate to the database and returns the CaModel.

Parameters:

  • issuing_ca_cert (cryptography.x509.Certificate) – The issuing CA certificate.

  • chain (list[cryptography.x509.Certificate]) – List of intermediate certificates in the chain.

  • private_key (trustpoint_core.crypto_types.PrivateKey) – The private key for the issuing CA.

  • unique_name (str) – Unique name for this CA.

  • ca_type (pki.models.CaModel.CaTypeChoice) – The type of issuing CA.

  • parent_ca (pki.models.CaModel | None) – Optional parent CA in the hierarchy (the CA that issued this certificate).

Returns:

The created CA model.

Return type:

CaModel

static save_keyless_ca(root_ca_cert, unique_name='root_ca', crl_pem=None)[source]

Saves a keyless root CA certificate as a keyless CA to the database and returns the CaModel.

Parameters:

  • root_ca_cert (cryptography.x509.Certificate)

  • unique_name (str)

  • crl_pem (str | None)

Return type:

pki.models.CaModel

exception pki.util.x509.ClientCertificateAuthenticationError[source]

Bases: Exception

Exception raised for general client certificate authentication failures.

class pki.util.x509.NginxTLSClientCertExtractor[source]

Extracts the TLS client certificate from the request.

static get_client_cert_as_x509(request)[source]

Retrieve the client certificate from the request and convert it to an x509.Certificate object.

Parameters:

request (django.http.HttpRequest) – Django HttpRequest containing the headers.

Returns:

x509.Certificate object.

Raises:

ClientCertificateAuthenticationError – if no client certificate found or it is not a valid PEM-encoded cert.

Return type:

tuple[cryptography.x509.Certificate, list[cryptography.x509.Certificate]]

class pki.util.x509.CertificateVerifier[source]

Methods for verifying client, server, and CA certificates.

static verify_server_cert(cert, subject, trusted_roots=None, untrusted_intermediates=None, verification_time=None)[source]

Verifies a server’s TLS certificate against a trusted certificate store.

Performs full X.509 chain validation including: - Certificate validity (not before/not after) - Hostname verification (DNS name matching against SAN) - Chain building to a trusted root CA - Basic constraints and key usage extensions - RSA key size validation (if RSA certificate) - ECC curve strength validation (if ECC certificate) - Signature algorithm strength validation

Parameters:

  • cert (x509.Certificate) – The leaf server certificate to verify.

  • subject (str) – The expected DNS name or hostname to match against the certificate’s Subject Alternative Name (SAN) extension.

  • trusted_roots (list[x509.Certificate] | None) – List of trusted root CA certificates to use as the trust anchor. If None, the verification will fail as there is no trust anchor.

  • untrusted_intermediates (list[x509.Certificate] | None) – Intermediate certificates that are not trusted by default but provided to assist chain building. Used to help construct the certificate path from the leaf to a trusted root.

  • verification_time (datetime.datetime | None) – The time at which to verify the certificate validity. If None, defaults to the current UTC time.

Returns:

A validated certificate chain from the leaf certificate up to a trusted root,

ordered from leaf to root.

Return type:

list[x509.Certificate]

Raises:

  • VerificationError – If a valid chain cannot be constructed, the certificate is not valid at the verification time, or the subject name does not match the provided DNS name.

  • UnsupportedGeneralNameType – If a valid chain exists, but contains an unsupported general name type in the Subject Alternative Name extension.

  • ValueError – If the certificate is RSA but the key size is below the minimum required by security policy, if the ECC curve is weak according to security policy, or if the signature algorithm is weak.

static verify_ca_cert(cert, trusted_roots=None, untrusted_intermediates=None, verification_time=None, required_key_usage=None)[source]

Verifies a CA certificate against a trusted certificate store.

Performs full X.509 chain validation including: - Certificate validity (not before/not after) - Chain building to a trusted root CA with signature verification - BasicConstraints extension validation (ca=True) - KeyUsage extension validation (key_cert_sign=True, crl_sign=True) - RSA key size validation (if RSA certificate) - ECC curve strength validation (if ECC certificate) - Signature algorithm strength validation

Note: Unlike verify_server_cert, this method does NOT use PolicyBuilder as it only supports EE certificates. CA chain verification is performed manually via signature verification and issuer/subject name matching.

Parameters:

  • cert (x509.Certificate) – The CA certificate to verify.

  • trusted_roots (list[x509.Certificate] | None) – List of trusted root CA certificates to use as the trust anchor. If None, defaults to empty list. For self-signed CAs, include the cert itself or set to [cert].

  • untrusted_intermediates (list[x509.Certificate] | None) – Intermediate CA certificates that are not trusted by default but provided to assist chain building. Used to help construct the certificate path from the leaf CA to a trusted root.

  • verification_time (datetime.datetime | None) – The time at which to verify the certificate validity. If None, defaults to the current UTC time.

  • required_key_usage (x509.KeyUsage | None) – Expected KeyUsage extension. If provided, the certificate’s key usage must match exactly. If None, only validates required usages.

Returns:

A validated certificate chain from the CA certificate up to a trusted root,

ordered from leaf to root.

Return type:

list[x509.Certificate]

Raises:

ValueError – If the certificate lacks required CA extensions, security properties are insufficient, validity period is outside the verification time, or chain cannot be built.