Skip to content

Latest commit

 

History

History
167 lines (129 loc) · 5.16 KB

models.rst

File metadata and controls

167 lines (129 loc) · 5.16 KB
Raw

django_ca.models - django-ca models

django-ca uses three classes, called "models" in Django terminology, to store everything in the database. They are the core classes for this project, if you want to use this project programmatically, you'll have to use these classes:

  • CertificateAuthority <models-certificate-authority> is used to store certificate authorities.
  • Certificate <models-certificate> is used to store certificates.
  • Finally, Watcher <models-watcher> stores email addresses for who should be notified if certificates expire.

Note that both CertificateAuthority and Certificate inherit from :py~django_ca.models.X509CertMixin, which provides many common convenience methods.

CertificateAuthority

django_ca.models.CertificateAuthority

Creating CAs

Use CertificateAuthority.objects.init() to create new certificate authorities. The method has many options but is designed to provide defaults that work in most cases:

>>> from django_ca.models import CertificateAuthority
>>> from django_ca.utils import x509_name
>>> ca = CertificateAuthority.objects.init(
...   name='ca', 
...   subject=x509_name('/CN=ca.example.com'),
...   pathlen=1  # so we can create one level of intermediate CAs
... )
>>> ca
<CertificateAuthority: ca>

This CA will contain all properties and X509 extensions to be a fully functioning CA. To create an intermediate CA, simply pass the parent:

>>> child = CertificateAuthority.objects.init(
...   name='child', 
...   subject=x509_name('/CN=child.example.com'),
...   parent=ca)
>>> child.parent
<CertificateAuthority: ca>
>>> ca.children.all()
<CertificateAuthorityQuerySet [<CertificateAuthority: child>]>

Or to create a CA with all extensions that live CAs have, you can pass many more parameters:

>>> full = CertificateAuthority.objects.init(
...   name='full', 
...   subject=x509_name('/CN=full.example.com'),
...   parent=ca,  # some extensions are only valid for intermediate CAs
...   issuer_url='http://full.example.com/full.der',
...
...   # this CA can only sign for *.com domains:
...   permitted_subtrees=[x509.DNSName('.com')],
...
...   # CRL/OCSP URLs for signed certificates. These can be changed later:
...   crl_url=['http://full.example.com/full.crl', ],
...   ocsp_url='http://full.example.com/ocsp',
...
...   # CRL/OCSP/Issuer URLs for the CA. These are only meaningful for
...   # intermediate CAs:
...   ca_crl_url=['http://parent.example.com/parent.crl', ],
...   ca_ocsp_url='http://parent.example.com/ocsp',
...   ca_issuer_url='http://parent.example.com/parent.crt',
... )

There are some more parameters to configure how the CA will be signed:

>>> from cryptography.hazmat.primitives.asymmetric import ec
>>> from cryptography.hazmat.primitives import hashes
>>> CertificateAuthority.objects.init(
...   name='props', 
...   subject=x509_name('/CN=child.example.com'),
...   algorithm=hashes.SHA256(),  # SHA512 would be the default
...   pathlen=3,  # three levels of intermediate CAs allowed,
...   password=b'foobar',  # encrypt private key with this password
...   key_size=4096,  # key size for DSA/RSA keys - unused in this example
...   key_type='ECC',  # create an ECC private key
...   ecc_curve=ec.SECP256R1()  # ECC key curve
... )
<CertificateAuthority: props>

Here are all parameters for creating CAs:

django_ca.managers.CertificateAuthorityManager.init

Certificate

django_ca.models.Certificate

Manager methods

:py~django_ca.managers.CertificateManager is the default manager for :py~django_ca.models.Certificate, meaning you can access it using Certificate.objects, e.g.:

>>> csr  # doctest: +ELLIPSIS
<builtins.CertificateSigningRequest object at ...>
>>> from django_ca.models import Certificate
>>> Certificate.objects.create_cert(csr=csr, ca=ca, subject='/CN=example.com')
<Certificate: example.com>

django_ca.managers.CertificateManager

X509CertMixin

:py~django_ca.models.X509CertMixin is a common base class to both :py~django_ca.models.CertificateAuthority and :py~django_ca.models.Certificate and provides many convenience attributes.

django_ca.models.X509CertMixin

Watchers

django_ca.models.Watcher

ACME

django_ca.models.AcmeAccount

django_ca.models.AcmeOrder

django_ca.models.AcmeAuthorization

django_ca.models.AcmeChallenge

django_ca.models.AcmeCertificate