django_ca.extensions - X509 extensions

class django_ca.extensions.Extension(value)[source]

Convenience class to handle X509 Extensions.

The class is designed to take whatever format an extension might occur, essentially providing a convertible format for extensions that is used in many places throughout the code. It accepts str if e.g. the value was received from the commandline:

>>> KeyUsage('keyAgreement,keyEncipherment')
<KeyUsage: ['keyAgreement', 'keyEncipherment'], critical=False>
>>> KeyUsage('critical,keyAgreement,keyEncipherment')
<KeyUsage: ['keyAgreement', 'keyEncipherment'], critical=True>

Or it can be a dict as used by the CA_PROFILES setting:

>>> KeyUsage({'value': ['keyAgreement', 'keyEncipherment']})
<KeyUsage: ['keyAgreement', 'keyEncipherment'], critical=False>
>>> KeyUsage({'critical': True, 'value': ['keyAgreement', 'keyEncipherment']})
<KeyUsage: ['keyAgreement', 'keyEncipherment'], critical=True>

… and finally it can also use a subclass of ExtensionType from cryptography:

>>> from cryptography import x509
>>> ExtendedKeyUsage(x509.extensions.Extension(
...    oid=ExtensionOID.EXTENDED_KEY_USAGE,
...    critical=False,
...    value=x509.ExtendedKeyUsage([ExtendedKeyUsageOID.SERVER_AUTH])
... ))
<ExtendedKeyUsage: ['serverAuth'], critical=False>
Parameters
valuelist or tuple or dict or str or ExtensionType

The value of the extension, the description provides further details.

Attributes
name

A human readable name of this extension.

value

Raw value for this extension. The type various from subclass to subclass.

as_extension()[source]

This extension as ExtensionType.

as_text()[source]

Human-readable version of the value, not including the “critical” flag.

extension_type

The extension_type for this value.

for_builder()[source]

Return kwargs suitable for a CertificateBuilder.

Example:

>>> kwargs = KeyUsage('keyAgreement,keyEncipherment').for_builder()
>>> builder.add_extension(**kwargs)  
name

A human readable name of this extension.

serialize()[source]

Serialize this extension to a string in a way that it can be passed to a constructor again.

For example, this should always be True:

>>> ku = KeyUsage('keyAgreement,keyEncipherment')
>>> ku == KeyUsage(ku.serialize())
True
class django_ca.extensions.KeyIdExtension(value)[source]

Bases: django_ca.extensions.Extension

Base class for extensions that contain a KeyID as value.

class django_ca.extensions.ListExtension(value)[source]

Bases: django_ca.extensions.Extension

Base class for extensions with multiple ordered values.

Subclasses behave like a list, and you can also pass a list of values to the constructor:

>>> san = SubjectAlternativeName(['example.com', 'example.net'])
>>> san[0]
'DNS:example.com'

If the passed value is a list, the critical flag will be set according the the default value for this extension.

class django_ca.extensions.KnownValuesExtension(value)[source]

Bases: django_ca.extensions.ListExtension

A generic base class for extensions with multiple values with a set of pre-defined valid values.

This base class is for extensions where we know what potential values an extension can have. For example, the KeyUsage extension has only a certain set of valid values:

>>> KeyUsage(['keyAgreement', 'keyEncipherment'])
<KeyUsage: ['keyAgreement', 'keyEncipherment'], critical=False>
>>> KeyUsage(['wrong-value'])
Traceback (most recent call last):
    ...
ValueError: Unknown value(s): wrong-value

Known values are set in the KNOWN_VALUES attribute for each class. The constructor will raise ValueError if an unknown value is passed.

class django_ca.extensions.AlternativeNameExtension(value)[source]

Bases: django_ca.extensions.GeneralNameMixin, django_ca.extensions.ListExtension

Base class for extensions that contain a list of general names.

This class also allows you to pass GeneralName instances:

>>> san = SubjectAlternativeName([x509.DNSName('example.com'), 'example.net'])
>>> san
<SubjectAlternativeName: ['DNS:example.com', 'DNS:example.net'], critical=False>
>>> 'example.com' in san, 'DNS:example.com' in san, x509.DNSName('example.com') in san
(True, True, True)
class django_ca.extensions.NullExtension(value=None)[source]

Bases: django_ca.extensions.Extension

Base class for extensions that have a NULL value.

Extensions using this base class do not accept a str as value:

>>> OCSPNoCheck()
<OCSPNoCheck: critical=False>
>>> OCSPNoCheck({'critical': True})
<OCSPNoCheck: critical=True>
>>> OCSPNoCheck({'critical': True})
<OCSPNoCheck: critical=True>
>>> OCSPNoCheck(x509.extensions.Extension(oid=ExtensionOID.OCSP_NO_CHECK, critical=True, value=None))
<OCSPNoCheck: critical=True>
as_extension()[source]

This extension as ExtensionType.

class django_ca.extensions.GeneralNameMixin[source]

Bases: object

Mixin to internally store values as GeneralName instances.

This mixin ensures that values passed as GeneralName instances will never get parsed. This is useful because there are some instances where names may not be parsed reliably. This means that the DNS name here is never converted between the instantiation here and actually adding the extension to the certificate:

>>> san = SubjectAlternativeName([x509.DNSName('example.com')])
>>> Certificate.objects.init(subjectAltName=...)  

Concrete extensions

class django_ca.extensions.AuthorityInformationAccess(value)[source]

Bases: django_ca.extensions.GeneralNameMixin, django_ca.extensions.Extension

Class representing a AuthorityInformationAccess extension.

class django_ca.extensions.AuthorityKeyIdentifier(value)[source]

Bases: django_ca.extensions.KeyIdExtension

Class representing a AuthorityKeyIdentifier extension.

class django_ca.extensions.BasicConstraints(*args, **kwargs)[source]

Bases: django_ca.extensions.Extension

Class representing a BasicConstraints extension.

This class has the boolean attributes ca and the attribute pathlen, which is either None or an int. Note that this extension is marked as critical by default if you pass a dict to the constructor:

>>> BasicConstraints('critical,CA:TRUE, pathlen:3')
<BasicConstraints: 'CA:TRUE, pathlen:3', critical=True>
>>> bc = BasicConstraints({'ca': True, 'pathlen': 4})
>>> (bc.ca, bc.pathlen, bc.critical)
(True, 4, True)

# Note that string parsing ignores case and whitespace and is quite forgiving
>>> BasicConstraints('critical, ca=true    , pathlen: 3 ')
<BasicConstraints: 'CA:TRUE, pathlen:3', critical=True>
class django_ca.extensions.ExtendedKeyUsage(value)[source]

Bases: django_ca.extensions.KnownValuesExtension

Class representing a ExtendedKeyUsage extension.

KNOWN_VALUES = {'OCSPSigning', 'clientAuth', 'codeSigning', 'emailProtection', 'msKDC', 'serverAuth', 'smartcardLogon', 'timeStamping'}

Known values for this extension.

class django_ca.extensions.IssuerAlternativeName(value)[source]

Bases: django_ca.extensions.AlternativeNameExtension

Class representing an Issuer Alternative Name extension.

This extension is usually marked as non-critical.

>>> IssuerAlternativeName('https://example.com')
<IssuerAlternativeName: ['URI:https://example.com'], critical=False>
class django_ca.extensions.KeyUsage(*args, **kwargs)[source]

Bases: django_ca.extensions.KnownValuesExtension

Class representing a KeyUsage extension, which defines the purpose of a certificate.

This extension is usually marked as critical and RFC5280 defines that confirming CAs SHOULD mark it as critical. The value keyAgreement is always added if decipherOnly is present, since the value of this extension is not meaningful otherwise.

>>> KeyUsage('critical,encipherOnly')
<KeyUsage: ['encipherOnly'], critical=True>
>>> KeyUsage('critical,decipherOnly')
<KeyUsage: ['decipherOnly', 'keyAgreement'], critical=True>
KNOWN_VALUES = {'cRLSign', 'dataEncipherment', 'decipherOnly', 'digitalSignature', 'encipherOnly', 'keyAgreement', 'keyCertSign', 'keyEncipherment', 'nonRepudiation'}

Known values for this extension.

class django_ca.extensions.NameConstraints(value)[source]

Bases: django_ca.extensions.GeneralNameMixin, django_ca.extensions.Extension

Class representing a NameConstraints extenion

Unlike most other extensions, this extension does not accept a string as value, but you can pass a list containing the permitted/excluded subtrees as lists. Similar to SubjectAlternativeName, you can pass both strings or instances of GeneralName:

>>> NameConstraints([['DNS:.com', 'example.org'], [x509.DNSName('.net')]])
<NameConstraints: permitted=['DNS:.com', 'DNS:example.org'], excluded=['DNS:.net'], critical=True>
class django_ca.extensions.OCSPNoCheck(value=None)[source]

Bases: django_ca.extensions.NullExtension

Extension to indicate that an OCSP client should (blindly) trust the certificate for it’s lifetime.

This extension is only meaningful in an OCSP responder certificate.

class django_ca.extensions.PrecertPoison(value=None)[source]

Bases: django_ca.extensions.NullExtension

Extension to indicate that the certificate is a submission to a certificate transparency log.

Note that creating this extension will raise ValueError if it is not marked as critical:

>>> PrecertPoison()
<PrecertPoison: critical=True>
>>> PrecertPoison({'critical': False})
Traceback (most recent call last):
    ...
ValueError: PrecertPoison must always be marked as critical
class django_ca.extensions.PrecertificateSignedCertificateTimestamps(value)[source]

Bases: django_ca.extensions.ListExtension

Class representing signed certificate timestamps.

This extension can be used to verify that a certificate is included in a Certificate Transparency log.

Note

Cryptography currently does not provide a way to create instances of this extension without already having a certificate that provides this extension.

See also

RFC 6962

class django_ca.extensions.SubjectAlternativeName(value)[source]

Bases: django_ca.extensions.AlternativeNameExtension

Class representing an Subject Alternative Name extension.

This extension is usually marked as non-critical.

>>> SubjectAlternativeName('example.com')
<SubjectAlternativeName: ['DNS:example.com'], critical=False>
class django_ca.extensions.SubjectKeyIdentifier(value)[source]

Bases: django_ca.extensions.KeyIdExtension

Class representing a SubjectKeyIdentifier extension.

class django_ca.extensions.TLSFeature(value)[source]

Bases: django_ca.extensions.KnownValuesExtension

Class representing a TLSFeature extension.

KNOWN_VALUES = {'MultipleCertStatusRequest', 'OCSPMustStaple'}

Known values for this extension.