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 programatically, you’ll have to use these classes:
- CertificateAuthority is used to store certificate authorities.
- Certificate is used to store certificates.
- Finally, Watcher stores email addresses for who should be notified if certificates expire.
Note that both CertificateAuthority
and Certificate
inherit from
X509CertMixin
, which provides many common
convenience methods.
CertificateAuthority¶
-
class
django_ca.models.
CertificateAuthority
(id, created, valid_from, expires, pub, cn, serial, revoked, revoked_date, revoked_reason, name, enabled, parent, private_key_path, crl_url, issuer_url, ocsp_url, issuer_alt_name)[source]¶ -
allows_intermediate_ca
¶ Wether this CA allows creating intermediate CAs.
-
bundle
¶ A list of any parent CAs, including this CA.
The list is ordered so the Root CA will be the first.
Return the AuthorityKeyIdentifier extension used in certificates signed by this CA.
-
max_pathlen
¶ The maximum pathlen for any intermediate CAs signed by this CA.
This value is either
None
, if this and all parent CAs don’t have apathlen
attribute, or anint
if any parent CA has the attribute.
-
name
¶ Human-readable name of the CA, only used for displaying the CA.
-
pathlen
¶ The
pathlen
attribute of theBasicConstraints
extension (either anint
orNone
).
-
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
>>> ca = CertificateAuthority.objects.init(
... name='ca', subject='/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='/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='/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:
... name_constraints=(['DNS:.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:
>>> CertificateAuthority.objects.init(
... name='props', subject='/CN=child.example.com',
... algorithm='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 RSA keys - unused in this example
... key_type='ECC', # create an ECC private key
... ecc_curve='SECP256R1'
... )
<CertificateAuthority: props>
Here are all parameters for creating CAs:
-
CertificateAuthorityManager.
init
(name, subject, expires=None, algorithm=None, parent=None, pathlen=None, issuer_url=None, issuer_alt_name='', crl_url=None, ocsp_url=None, ca_issuer_url=None, ca_crl_url=None, ca_ocsp_url=None, name_constraints=None, password=None, parent_password=None, ecc_curve=None, key_type='RSA', key_size=None, extra_extensions=None)[source]¶ Create a new certificate authority.
Parameters: - name : str
The name of the CA. This is a human-readable string and is used for administrative purposes only.
- subject : dict or str or
Subject
Subject string, e.g.
"/CN=example.com"
orSubject("/CN=example.com")
. The value is actually passed toSubject
if it is not already an instance of that class.- expires : datetime, optional
Datetime for when this certificate authority will expire, defaults to CA_DEFAULT_EXPIRES.
- algorithm : str or
HashAlgorithm
, optional Hash algorithm used when signing the certificate, passed to
parse_hash_algorithm()
. The default is the value of the CA_DIGEST_ALGORITHM setting.- parent :
CertificateAuthority
, optional Parent certificate authority for the new CA. Passing this value makes the CA an intermediate authority.
- pathlen : int, optional
Value of the path length attribute for the
BasicConstraints
extension.- issuer_url : str
URL for the DER/ASN1 formatted certificate that is signing certificates.
- issuer_alt_name :
IssuerAlternativeName
or str, optional IssuerAlternativeName used when signing certificates. If the value is not an instance of
IssuerAlternativeName
, it will be passed as argument to the constructor of the class.- crl_url : list of str, optional
CRL URLs used for certificates signed by this CA.
- ocsp_url : str, optional
OCSP URL used for certificates signed by this CA.
- ca_issuer_url : str, optional
URL for the DER/ASN1 formatted certificate that is signing this CA. For intermediate CAs, this would usually be the
issuer_url
of the parent CA.- ca_crl_url : list of str, optional
CRL URLs used for this CA. This value is only meaningful for intermediate CAs.
- ca_ocsp_url : str, optional
OCSP URL used for this CA. This value is only meaningful for intermediate CAs.
- name_constraints : list of lists or
NameConstraints
List of names that this CA can sign and/or cannot sign. The value is passed to
NameConstraints
if the value is not already an instance of that class.- password : bytes, optional
Password to encrypt the private key with.
- parent_password : bytes, optional
Password that the private key of the parent CA is encrypted with.
- ecc_curve : str or EllipticCurve, optional
The elliptic curve to use for ECC type keys, passed verbatim to
parse_key_curve()
.- key_type: str, optional
The type of private key to generate, must be one of
"RSA"
,"DSA"
or"ECC"
, with"RSA"
being the default.- key_size : int, optional
Integer specifying the key size, must be a power of two (e.g. 2048, 4096, …). Defaults to the CA_DEFAULT_KEY_SIZE, unused if
key_type="ECC"
.- extra_extensions : list of
cryptography.x509.Extension
ordjango_ca.extensions.Extension
, optional An optional list of additional extensions to add to the certificate.
Raises: - ValueError
For various cases of wrong input data (e.g.
key_size
not being the power of two).- PermissionError
If the private key file cannot be written to disk.
Certificate¶
-
class
django_ca.models.
Certificate
(id, created, valid_from, expires, pub, cn, serial, revoked, revoked_date, revoked_reason, ca, csr)[source]¶ -
bundle
¶ The complete certificate bundle. This includes all CAs as well as the certificates itself.
-
Manager methods¶
CertificateManager
is the default manager for
Certificate
, meaning you can access it
using Certificate.objects
, e.g.:
>>> from django_ca.models import Certificate
>>> Certificate.objects.init(csr=csr, ca=ca, subject='/CN=example.com')
<Certificate: example.com>
-
class
django_ca.managers.
CertificateManager
[source]¶ -
init
(ca, csr, **kwargs)[source]¶ Create a signed certificate from a CSR and store it to the database.
All parameters are passed on to
Certificate.objects.sign_cert()
.
-
sign_cert
(ca, csr, expires=None, algorithm=None, subject=None, cn_in_san=True, csr_format=<Encoding.PEM: 'PEM'>, subject_alternative_name=None, key_usage=None, extended_key_usage=None, tls_feature=None, extra_extensions=None, password=None)[source]¶ Create a signed certificate from a CSR.
PLEASE NOTE: This function creates the raw certificate and is usually not invoked directly. It is called by
Certificate.objects.init()
, which passes along all parameters unchanged and saves the raw certificate to the database.Parameters: - ca :
CertificateAuthority
The certificate authority to sign the certificate with.
- csr : str
A valid CSR. The format is given by the
csr_format
parameter.- expires : datetime, optional
Datetime for when this certificate will expire, defaults to the
CA_DEFAULT_EXPIRES
setting.- algorithm : str or
HashAlgorithm
, optional Hash algorithm used when signing the certificate, passed to
parse_hash_algorithm()
. The default is the value of the CA_DIGEST_ALGORITHM setting.- subject : dict or str or
Subject
Subject string, e.g.
"/CN=example.com"
orSubject("/CN=example.com")
. The value is actually passed toSubject
if it is not already an instance of that class. If this value is not passed or if the value does not contain a CommonName, the first value of thesubject_alternative_name
parameter is used as CommonName.- cn_in_san : bool, optional
Wether the CommonName should also be included as subjectAlternativeName. The default is
True
, but the parameter is ignored if no CommonName is given. This is typically set toFalse
when creating a client certificate, where the subjects CommonName has no meaningful value as subjectAlternativeName.- csr_format :
Encoding
, optional The format of the CSR. The default is
PEM
.- subject_alternative_name : list of str or
SubjectAlternativeName
, optional A list of alternative names for the certificate. The value is passed to
SubjectAlternativeName
if not already an instance of that class.- key_usage : str or dict or
KeyUsage
, optional Value for the
keyUsage
X509 extension. The value is passed toKeyUsage
if not already an instance of that class.- extended_key_usage : str or dict or
ExtendedKeyUsage
, optional Value for the
extendedKeyUsage
X509 extension. The value is passed toExtendedKeyUsage
if not already an instance of that class.- tls_feature : str or dict or
TLSFeature
, optional Value for the
TLSFeature
X509 extension. The value is passed toTLSFeature
if not already an instance of that class.- extra_extensions : list of
cryptography.x509.Extension
ordjango_ca.extensions.Extension
, optional An optional list of additional extensions to add to the certificate.
- password : bytes, optional
Password used to load the private key of the certificate authority. If not passed, the private key is assumed to be unencrypted.
Returns: - cryptography.x509.Certificate
The signed certificate.
- ca :
-
X509CertMixin¶
X509CertMixin
is a common base class to both
CertificateAuthority
and
Certificate
and provides many convenience
attributes.
-
class
django_ca.models.
X509CertMixin
(*args, **kwargs)[source]¶ The
AuthorityKeyIdentifier
extension, orNone
if it doesn’t exist.
-
extended_key_usage
¶ The
ExtendedKeyUsage
extension, orNone
if it doesn’t exist.
-
not_after
¶ Date/Time this certificate expires.
-
not_before
¶ Date/Time this certificate was created
-
subject_key_identifier
¶ The
SubjectKeyIdentifier
extension, orNone
if it doesn’t exist.
-
tls_feature
¶ The
TLSFeature
extension, orNone
if it doesn’t exist.
-
x509
¶ The underlying
cryptography.x509.Certificate
.