django_ca.profiles - Certificate profiles

The profiles module defines classes and methods for handling profiles.

Even if you use the Python API, you do not need to handle any instances from this module directly in most cases. Instead, you can simply pass a name of the profile instead. For example, to create a certificate using the webserver profile:

# Note: "csr" is a predefined variable, see https://cryptography.io/en/latest/x509/tutorial/
>>> from django_ca.models import Certificate
>>> Certificate.objects.create_cert(ca, csr, 'webserver', subject='/CN=example.com')
<Certificate: example.com>

But you can also create your own profile manually to create a special type of certificate:

>>> from django_ca.models import CertificateAuthority
>>> profile = Profile('example', subject='/C=AT', extensions={'ocsp_no_check': {}})
>>> ca = CertificateAuthority.objects.first()
>>> profile.create_cert(ca, csr, subject='/CN=example.com')
<Certificate(subject=<Name(C=AT,CN=example.com)>, ...)>

You can also access profiles using profiles.profiles, create a copy and update the copy:

>>> from django_ca.profiles import profiles
>>> profile = profiles['webserver'].copy()
>>> cert = Certificate.objects.create_cert(ca, csr, profile=profile, subject='/CN=example.com')
>>> cert.subject_alternative_name
<SubjectAlternativeName: ['DNS:example.com'], critical=False>
>>> profile.cn_in_san = False
>>> cert = Certificate.objects.create_cert(ca, csr, profile=profile, subject='/CN=example.com')
>>> cert.subject_alternative_name is None
True

class django_ca.profiles.Profile(name, subject=None, algorithm=None, extensions=None, cn_in_san=True, expires=None, description='', autogenerated=False, add_crl_url=True, add_ocsp_url=True, add_issuer_url=True, add_issuer_alternative_name=True)

A certificate profile defining properties and extensions of a certificate.

Instances of this class usually represent profiles defined in CA_PROFILES, but you can also create your own profile to create a different type of certificate. An instance of this class can be used to create a signed certificate based on the given CA:

>>> Profile('example', subject='/C=AT', extensions={'ocsp_no_check': {}})
<Profile: example>

copy()

Create a deep copy of a profile.

create_cert(ca, csr, subject=None, expires=None, algorithm=None, extensions=None, cn_in_san=None, add_crl_url=None, add_ocsp_url=None, add_issuer_url=None, add_issuer_alternative_name=None, password=None)

Create a x509 certificate based on this profile, the passed CA and input parameters.

This function is the core function used to create x509 certificates. In it’s simplest form, you only need to pass a ca, a CSR and a subject to get a valid certificate:

>>> profile = get_profile('webserver')
>>> profile.create_cert(ca, csr, subject='/CN=example.com')  
<Certificate(subject=<Name(...,CN=example.com)>, ...)>

The function will add CRL, OCSP, Issuer and IssuerAlternativeName URLs based on the CA if the profile has the add_crl_url, add_ocsp_url and add_issuer_url and add_issuer_alternative_name values set. Parameters to this function with the same name allow you override this behavior.

The function allows you to override profile values using the expires and algorithm values. You can pass additional extensions as a list, which will override any extensions from the profile, but the CA passed will append to these extensions unless the add_… values are False.

Parameters

caCertificateAuthority

The CA to sign the certificate with.

csrCertificateSigningRequest

The CSR for the certificate.

subjectdict or str or Subject

Update the subject string, e.g. "/CN=example.com" or Subject("/CN=example.com"). The values from the passed subject will update the profiles subject.

expiresint or datetime or timedelta, optional

Override when this certificate will expire.

algorithmHashAlgorithm, optional

Override the hash algorithm used when signing the certificate.

extensionslist or dict of Extension

List or dict of additional extensions to set for the certificate. Note that values from the CA might update the passed extensions: For example, if you pass an IssuerAlternativeName extension, add_issuer_alternative_name is True and the passed CA has an IssuerAlternativeName set, that value will be appended to the extension you pass here. If you pass a dict with a None value, that extension will be removed from the profile.

cn_in_sanbool, optional

Override if the CommonName should be added as an SubjectAlternativeName. If not passed, the value set in the profile is used.

add_crl_urlbool, optional

Override if any CRL URLs from the CA should be added to the CA. If not passed, the value set in the profile is used.

add_ocsp_urlbool, optional

Override if any OCSP URLs from the CA should be added to the CA. If not passed, the value set in the profile is used.

add_issuer_urlbool, optional

Override if any Issuer URLs from the CA should be added to the CA. If not passed, the value set in the profile is used.

add_issuer_alternative_namebool, optional

Override if any IssuerAlternativeNames from the CA should be added to the CA. If not passed, the value set in the profile is used.

password: bytes or str, optional

The password to the private key of the CA.

Returns

cryptography.x509.Certificate

The signed certificate.

get_expires(expires)

Get expiry for the given expiry timestamp.

serialize()

Function to serialize a profile.

This is function is called by the admin interface to retrieve profile information to the browser, so the value returned by this function should always be JSON serializable.