Python API¶

django-ca provides a Python API for everyone that wants to extend the functionality or build your own solution on top.

Note

This project is developed using Python and Django. Using the Python API requires knowledge in both. If you need help, both projects provide excellent documentation.

General¶

django-ca is a standard Django App. Using it requires a basic Django environment. You do not have to provide any special settings, default settings should be fine.

If you plan on using this project in standalone scripts, Django has some hints to get you started. But note that you still have to configure all of the basic Django settings and there is virtually no functionality without a database.

In some environments, e.g. where django-ca is exclusively used with command-line scripts, it might we worth it to use the default SQLite database backend.

Certificate Authorities¶

Certificate Authorities are represented by the CertificateAuthority model. It is a standard Django model, which means you can use the QuerySet API to retrieve and manipulate CAs:

>>> from cryptography.x509.oid import NameOID
>>> from django_ca.models import CertificateAuthority
>>> ca = CertificateAuthority.objects.get(name="root")
>>> ca.enabled = False
>>> ca.save()

To create a new CA, you have to init(), this example creates a minimal CA using the file system storage backend:

>>> from datetime import datetime
>>> from django_ca.key_backends import key_backends
>>> from django_ca.key_backends.storages import CreatePrivateKeyOptions, UsePrivateKeyOptions
>>> from django_ca.models import CertificateAuthority
>>> from django_ca.utils import x509_name
>>> key_backend = key_backends["default"]
>>> key_backend_options = CreatePrivateKeyOptions(
...     key_type="RSA", key_size=1024, password=None, path="ca"
... )
>>> CertificateAuthority.objects.init(
...     name="ca-two",
...     key_backend=key_backends["default"],
...     key_backend_options=key_backend_options,
...     subject=x509.Name([x509.NameAttribute(NameOID.COMMON_NAME, "ca.example.com")])
... )
<CertificateAuthority: ca-two>

Please see CertificateAuthority for a more detailed description on how to handle CAs.

Certificates¶

Certificates are represented by the Certificate model, they too are a standard Django model:

>>> from django_ca.models import Certificate
>>> cert = Certificate.objects.get(serial=cert_serial)
>>> cert.revoke()  # this already calls save()

Much like with certificate authorities, creating a new certificate requires a manager method, Certificate.objects.create_cert():

>>> from django_ca.utils import x509_name
>>> Certificate.objects.create_cert(
...     ca,
...     UsePrivateKeyOptions(password=None),
...     csr,
...     subject=x509.Name([x509.NameAttribute(NameOID.COMMON_NAME, "example.com")])
... )
<Certificate: example.com>

Signals¶

Signals are a way for a developer to execute code whenever an event happens, for example to send out an email whenever a new certificate is issued. django-ca provides some custom signals.