pki.util.x509 ============= .. py:module:: pki.util.x509 .. autoapi-nested-parse:: Handles certificate creation for Issuing CA certificates. Module Contents --------------- .. py:data:: logger .. py:class:: CertificateGenerator Methods for generating X.509 certificates. .. py:method:: create_root_ca(cn, validity_days = 7300, private_key = None, hash_algorithm = None, path_length = None) :staticmethod: Creates a root CA certificate for testing and AutoGenPKI. :param cn: Common name for the root CA. :param validity_days: Validity period in days. :param private_key: Private key to use. If None, generates new RSA-2048 key. :param hash_algorithm: Hash algorithm to use for signing. :param path_length: Maximum number of CA certificates that may follow this certificate. If None, defaults to 1. :returns: Tuple of (certificate, private_key). .. py:method:: create_issuing_ca(issuer_private_key, issuer_cn, subject_cn, private_key = None, validity_days = 3650, hash_algorithm = None, path_length = None) :staticmethod: Creates an issuing CA certificate + key pair. :param issuer_private_key: Private key of the issuing CA. None for root CA. :param issuer_cn: Common name of the issuer. :param subject_cn: Common name of the subject. :param private_key: Private key to use. If None, generates new RSA-2048 key. :param validity_days: Validity period in days. :param hash_algorithm: Hash algorithm to use for signing. :param path_length: 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). .. py:method:: create_ee(issuer_private_key, issuer_name, subject_name, private_key = None, extensions = None, validity_days = 365) :staticmethod: Creates a generic end entity certificate + key pair. :param issuer_private_key: The private key of the issuer. :param issuer_name: The full issuer Name (must be x509.Name to ensure proper certificate chain matching). :param subject_name: The subject common name (str) or full subject Name. :param private_key: The private key for the EE. If None, generates new RSA-2048 key. :param extensions: List of (extension, critical) tuples to add. :param validity_days: Validity period in days. :returns: Tuple of (certificate, private_key). .. py:method:: create_test_pki(chain_depth = 0) :staticmethod: Get a test PKI chain with a specified depth (excluding root CA). depth=0 is a self-signed EE. .. py:method:: save_issuing_ca(issuing_ca_cert, chain, private_key, unique_name = 'issuing_ca', ca_type = CaModel.CaTypeChoice.LOCAL_UNPROTECTED, parent_ca = None) :staticmethod: Saves an Issuing CA certificate to the database and returns the CaModel. :param issuing_ca_cert: The issuing CA certificate. :param chain: List of intermediate certificates in the chain. :param private_key: The private key for the issuing CA. :param unique_name: Unique name for this CA. :param ca_type: The type of issuing CA. :param parent_ca: Optional parent CA in the hierarchy (the CA that issued this certificate). :returns: The created CA model. :rtype: CaModel .. py:method:: save_keyless_ca(root_ca_cert, unique_name = 'root_ca', crl_pem = None) :staticmethod: Saves a keyless root CA certificate as a keyless CA to the database and returns the CaModel. .. py:exception:: ClientCertificateAuthenticationError Bases: :py:obj:`Exception` Exception raised for general client certificate authentication failures. .. py:class:: NginxTLSClientCertExtractor Extracts the TLS client certificate from the request. .. py:method:: get_client_cert_as_x509(request) :staticmethod: Retrieve the client certificate from the request and convert it to an x509.Certificate object. :param request: 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. .. py:class:: CertificateVerifier Methods for verifying client, server, and CA certificates. .. py:method:: verify_server_cert(cert, subject, trusted_roots = None, untrusted_intermediates = None, verification_time = None) :staticmethod: 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 :param cert: The leaf server certificate to verify. :type cert: x509.Certificate :param subject: The expected DNS name or hostname to match against the certificate's Subject Alternative Name (SAN) extension. :type subject: str :param trusted_roots: List of trusted root CA certificates to use as the trust anchor. If None, the verification will fail as there is no trust anchor. :type trusted_roots: list[x509.Certificate] | None :param untrusted_intermediates: 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. :type untrusted_intermediates: list[x509.Certificate] | None :param verification_time: The time at which to verify the certificate validity. If None, defaults to the current UTC time. :type verification_time: datetime.datetime | None :returns: A validated certificate chain from the leaf certificate up to a trusted root, ordered from leaf to root. :rtype: 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. :raises UnsupportedGeneralNameType: If a valid chain exists, but contains an unsupported general name type in the Subject Alternative Name extension. :raises 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. .. py:method:: verify_ca_cert(cert, trusted_roots = None, untrusted_intermediates = None, verification_time = None, required_key_usage = None) :staticmethod: 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. :param cert: The CA certificate to verify. :type cert: x509.Certificate :param trusted_roots: 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]. :type trusted_roots: list[x509.Certificate] | None :param untrusted_intermediates: 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. :type untrusted_intermediates: list[x509.Certificate] | None :param verification_time: The time at which to verify the certificate validity. If None, defaults to the current UTC time. :type verification_time: datetime.datetime | None :param required_key_usage: Expected KeyUsage extension. If provided, the certificate's key usage must match exactly. If None, only validates required usages. :type required_key_usage: x509.KeyUsage | None :returns: A validated certificate chain from the CA certificate up to a trusted root, ordered from leaf to root. :rtype: 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.