`django_ca.pydantic` - Pydantic models¶

Type aliases¶

Reusable type aliases for Pydantic models.

django_ca.pydantic.type_aliases.Base64EncodedBytes¶

A bytes type that validates strings as base64-encoded strings and serializes as such when using JSON.

This type differs from pydantic.Base64Bytes in that bytes are left untouched and strings are decoded before the inner validation logic, making this type suitable for strict type validation.

alias of Annotated[bytes]

django_ca.pydantic.type_aliases.EllipticCurveTypeAlias¶

A type alias for EllipticCurve instances.

This type alias validates names from ELLIPTIC_CURVE_TYPES and serializes to the canonical name in JSON. Models using this type alias can be used with strict schema validation.

alias of Annotated[EllipticCurve]

django_ca.pydantic.type_aliases.HashAlgorithmTypeAlias¶

A type alias for HashAlgorithm instances.

This type alias validates names from HASH_ALGORITHM_TYPES and serializes to the canonical name in JSON. Models using this type alias can be used with strict schema validation.

alias of Annotated[Union[SHA224, SHA256, SHA384, SHA512, SHA3_224, SHA3_256, SHA3_384, SHA3_512]]

django_ca.pydantic.type_aliases.PowerOfTwoTypeAlias¶

A type alias for an integer that is a power of two, e.g. an RSA/DSA KeySize.

Note that this type alias does not validate CA_MIN_KEY_SIZE, as validators in this module must not use any settings, as this would cause a circular import.

alias of Annotated[int]

django_ca.pydantic.type_aliases.Serial¶

A certificate serial as a hex string, as they are stored in the database.

This type will convert integers to hex and upper-case any lower-case strings. The minimum length is 1 character, the maximum length is 40 (RFC 5280, section 4.1.2.2 specifies a maximum of 20 octets, which equals 40 characters in hex).

alias of Annotated[str]

Cryptography classes¶

All cryptography-related classes share that they can be instantiated from cryptography instances using model_validate() and share a cryptography property that converts a model instance into a cryptography instance:

>>> from cryptography import x509
>>> from cryptography.x509.oid import NameOID
>>> from django_ca.pydantic.name import NameAttributeModel
>>> attr = x509.NameAttribute(oid=NameOID.COMMON_NAME, value="example.com")
>>> model = NameAttributeModel.model_validate(attr)
>>> model
NameAttributeModel(oid='2.5.4.3', value='example.com')
>>> model.cryptography == attr
True

Name¶

class django_ca.pydantic.NameAttributeModel(*, oid: str, value: str)[source]¶

Pydantic model wrapping NameAttribute.

For the oid, you can either use a dotted string or an alias from NAME_OID_TYPES:

Pydantic

from django_ca.pydantic import NameAttributeModel

NameAttributeModel(
    oid="CN",  #  or "commonName" or NameOID.COMMON_NAME or just "2.5.4.3"
    value="example.com",
)

cryptography

from cryptography import x509
from cryptography.x509.oid import NameOID

x509.NameAttribute(oid=NameOID.COMMON_NAME, value="example.com")

JSON

{
    "oid": "2.5.4.3",
    "value": "example.com"
}

When processing a x500 unique identifier attribute, the value is expected to be base64 encoded:

Pydantic

import base64

from django_ca.pydantic import NameAttributeModel

value = base64.b64encode(b"example.com")
NameAttributeModel(oid="x500UniqueIdentifier", value=value)

cryptography

from cryptography import x509
from cryptography.x509.name import _ASN1Type
from cryptography.x509.oid import NameOID

x509.NameAttribute(
    oid=NameOID.X500_UNIQUE_IDENTIFIER, value=b"example.com", _type=_ASN1Type.BitString
)

JSON

{
    "oid": "2.5.4.45",
    "value": "ZXhhbXBsZS5jb20="
}

property cryptography: NameAttribute¶: The NameAttribute instance for this model.

class django_ca.pydantic.NameModel(root: RootModelRootType = PydanticUndefined)[source]¶

Pydantic model wrapping Name.

This model is a Pydantic RootModel that takes a list of NameAttributeModel instances:

Pydantic

from django_ca.pydantic import NameAttributeModel, NameModel

NameModel(
    [
        NameAttributeModel(oid="C", value="AT"),
        NameAttributeModel(oid="CN", value="example.com"),
    ]
)

cryptography

from cryptography import x509
from cryptography.x509.oid import NameOID

x509.Name(
    [
        x509.NameAttribute(oid=NameOID.COUNTRY_NAME, value="AT"),
        x509.NameAttribute(oid=NameOID.COMMON_NAME, value="example.com"),
    ]
)

JSON

[
    {
        "oid": "2.5.4.6",
        "value": "AT"
    },
    {
        "oid": "2.5.4.3",
        "value": "example.com"
    }
]

property cryptography: Name¶: The Name instance for this model.

Extension attributes¶

Some extensions use a more complex datastructure, so attributes are represented as nested models.

class django_ca.pydantic.extension_attributes.AccessDescriptionModel(*, access_method: str, access_location: GeneralNameModel)[source]¶

Pydantic model wrapping AccessDescription.

The access_method may be a dotted string OID or one of the aliases listed in ACCESS_METHOD_TYPES. The access_location is a GeneralNameModel:

Pydantic

from django_ca.pydantic import AccessDescriptionModel, GeneralNameModel

access_location = GeneralNameModel(type="URI", value="http://ocsp.example.com")
AccessDescriptionModel(
    access_method="ocsp",  # or the OID: "1.3.6.1.5.5.7.48.1"
    access_location=access_location,
)

cryptography

from cryptography import x509
from cryptography.x509.oid import AuthorityInformationAccessOID

access_location = x509.UniformResourceIdentifier("http://ocsp.example.com")
x509.AccessDescription(
    access_method=AuthorityInformationAccessOID.OCSP, access_location=access_location
)

JSON

{
    "access_method": "1.3.6.1.5.5.7.48.1",
    "access_location": {
        "type": "URI",
        "value": "http://ocsp.example.com"
    }
}

The syntax is identical for CA issuers:

Pydantic

from django_ca.pydantic import AccessDescriptionModel, GeneralNameModel

access_location = GeneralNameModel(type="URI", value="http://ca-issuers.example.com")
AccessDescriptionModel(
    access_method="ca_issuers",  # or the OID: "1.3.6.1.5.5.7.48.2"
    access_location=access_location,
)

cryptography

from cryptography import x509
from cryptography.x509.oid import AuthorityInformationAccessOID

access_location = x509.UniformResourceIdentifier("http://ca-issuers.example.com")
x509.AccessDescription(
    access_method=AuthorityInformationAccessOID.CA_ISSUERS,
    access_location=access_location,
)

JSON

{
    "access_method": "1.3.6.1.5.5.7.48.2",
    "access_location": {
        "type": "URI",
        "value": "http://ca-issuers.example.com"
    }
}

property cryptography: AccessDescription¶: Convert to a AccessDescription instance.

class django_ca.pydantic.extension_attributes.AuthorityKeyIdentifierValueModel(*, key_identifier: bytes | None, authority_cert_issuer: list[GeneralNameModel] | None = None, authority_cert_serial_number: int | None = None)[source]¶

Pydantic model wrapping AuthorityKeyIdentifier.

In its by far most common form, this model will just set the key_identifier attribute, with a value based on the certificate authority. Since this is a bytes value, the input must be base64 encoded:

>>> AuthorityKeyIdentifierValueModel(key_identifier=b"MTIz")  
AuthorityKeyIdentifierValueModel(
    key_identifier=b'123', authority_cert_issuer=None, authority_cert_serial_number=None
)

You can also give a authority_cert_issuer (a list of GeneralNameModel) and an authority_cert_serial_number:

>>> AuthorityKeyIdentifierValueModel(
...     key_identifier=None,
...     authority_cert_issuer=[{'type': 'URI', 'value': 'http://example.com'}],
...     authority_cert_serial_number=123
... )  
AuthorityKeyIdentifierValueModel(
    key_identifier=None,
    authority_cert_issuer=[GeneralNameModel(type='URI', value='http://example.com')],
    authority_cert_serial_number=123
)

The restrictions defined in RFC 5280 apply, so authority_cert_issuer and authority_cert_serial_number must either be both present or None, and either key_identifier and/or authority_cert_issuer must be given.

property cryptography: AuthorityKeyIdentifier¶: Convert to a AuthorityKeyIdentifier instance.

class django_ca.pydantic.extension_attributes.BasicConstraintsValueModel(*, ca: bool, path_length: int | None)[source]¶

Pydantic model wrapping BasicConstraints.

For a certificate representing a certificate authority, this extension sets ca to True and a path length, which may be None:

>>> BasicConstraintsValueModel(ca=True, path_length=0)
BasicConstraintsValueModel(ca=True, path_length=0)

For end-entity certificates, this extension sets ca to False and must set path_length to None:

>>> BasicConstraintsValueModel(ca=False, path_length=None)
BasicConstraintsValueModel(ca=False, path_length=None)

property cryptography: BasicConstraints¶: Convert to a BasicConstraints instance.

class django_ca.pydantic.extension_attributes.DistributionPointModel(*, full_name: list[GeneralNameModel] | None = None, relative_name: NameModel | None = None, crl_issuer: list[GeneralNameModel] | None = None, reasons: set[Literal['aa_compromise', 'affiliation_changed', 'ca_compromise', 'certificate_hold', 'cessation_of_operation', 'key_compromise', 'privilege_withdrawn', 'superseded']] | None = None)[source]¶

Pydantic model wrapping DistributionPoint.

In its by far most common form, this model only has a full_name containing a URI:

>>> DistributionPointModel(
...     full_name=[{"type": "URI", "value": "https://ca.example.com/crl"}]
... )  
DistributionPointModel(
    full_name=[GeneralNameModel(type='URI', value='https://ca.example.com/crl')],
    relative_name=None, crl_issuer=None, reasons=None
)

Of course, other fields are also supported:

>>> DistributionPointModel(
...     relative_name=[{"oid": "2.5.4.3", "value": "example.com"}],
...     crl_issuer=[{"type": "URI", "value": "https://ca.example.com/issuer"}],
...     reasons={"key_compromise",}
... )  
DistributionPointModel(
    full_name=None,
    relative_name=NameModel(root=[NameAttributeModel(oid='2.5.4.3', value='example.com')]),
    crl_issuer=[GeneralNameModel(type='URI', value='https://ca.example.com/issuer')],
    reasons={'key_compromise'}
)

property cryptography: DistributionPoint¶: Convert to a DistributionPoint instance.

class django_ca.pydantic.extension_attributes.IssuingDistributionPointValueModel(*, only_contains_user_certs: bool = False, only_contains_ca_certs: bool = False, indirect_crl: bool = False, only_contains_attribute_certs: bool = False, only_some_reasons: set[Literal['aa_compromise', 'affiliation_changed', 'ca_compromise', 'certificate_hold', 'cessation_of_operation', 'key_compromise', 'privilege_withdrawn', 'superseded']] | None = None, full_name: list[GeneralNameModel] | None = None, relative_name: NameModel | None = None)[source]¶

Pydantic model wrapping IssuingDistributionPoint.

>>> full_name = [{"type": "URI", "value": "https://ca.example.com/crl"}]
>>> IssuingDistributionPointValueModel(full_name=full_name)  
IssuingDistributionPointValueModel(
    only_contains_user_certs=False,
    only_contains_ca_certs=False,
    indirect_crl=False,
    only_contains_attribute_certs=False,
    only_some_reasons=None,
    full_name=[GeneralNameModel(type='URI', value='https://ca.example.com/crl')],
    relative_name=None
)

Note that all attributes default to False or None and can thus be omitted, but at least one parameter needs to be given.

property cryptography: IssuingDistributionPoint¶: Convert to a IssuingDistributionPoint instance.

class django_ca.pydantic.extension_attributes.MSCertificateTemplateValueModel(*, template_id: str, major_version: int | None = None, minor_version: int | None = None)[source]¶

Pydantic model wrapping MSCertificateTemplate.

The template_id parameter is a dotted-string object identifier, while major_version and minor_version are optional integers:

>>> MSCertificateTemplateValueModel(template_id="1.2.3", major_version=1)
MSCertificateTemplateValueModel(template_id='1.2.3', major_version=1, minor_version=None)

property cryptography: MSCertificateTemplate¶: Convert to a MSCertificateTemplate instance.

class django_ca.pydantic.extension_attributes.NameConstraintsValueModel(*, permitted_subtrees: list[GeneralNameModel] | None = None, excluded_subtrees: list[GeneralNameModel] | None = None)[source]¶

Pydantic model wrapping NameConstraints.

Both permitted_subtrees and excluded_subtrees are optional, but at least one of them must be given. They are a list of GeneralNameModel instances:

>>> NameConstraintsValueModel(
...     permitted_subtrees=[{"type": "DNS", "value": ".com"}]
... )  
NameConstraintsValueModel(
    permitted_subtrees=[GeneralNameModel(type='DNS', value='.com')], excluded_subtrees=None
)

property cryptography: NameConstraints¶: Convert to a NameConstraints instance.

class django_ca.pydantic.extension_attributes.NoticeReferenceModel(*, organization: str | None = None, notice_numbers: list[int])[source]¶

Pydantic model wrapping NoticeReference.

>>> NoticeReferenceModel(organization="MyOrg", notice_numbers=[1, 2, 3])
NoticeReferenceModel(organization='MyOrg', notice_numbers=[1, 2, 3])

Note that organization is optional.

property cryptography: NoticeReference¶: Convert to a NoticeReference instance.

class django_ca.pydantic.extension_attributes.PolicyConstraintsValueModel(*, require_explicit_policy: int | None, inhibit_policy_mapping: int | None)[source]¶

Pydantic model wrapping PolicyConstraints.

The require_explicit_policy and inhibit_policy_mapping are both optional and must be integers if set. At least one value must be given.

>>> PolicyConstraintsValueModel(require_explicit_policy=0, inhibit_policy_mapping=1)
PolicyConstraintsValueModel(require_explicit_policy=0, inhibit_policy_mapping=1)

property cryptography: PolicyConstraints¶: Convert to a PolicyConstraints instance.

class django_ca.pydantic.extension_attributes.PolicyInformationModel(*, policy_identifier: str, policy_qualifiers: list[str | UserNoticeModel] | None = None)[source]¶

Pydantic model wrapping PolicyInformation.

In its simplest for, this model requires only a policy_identifier:

>>> PolicyInformationModel(policy_identifier="2.5.29.32.0")
PolicyInformationModel(policy_identifier='2.5.29.32.0', policy_qualifiers=None)

A list of policy_qualifiers may also be passed, with elements being either a str or a UserNoticeModel:

>>> notice = UserNoticeModel(explicit_text="my text")
>>> PolicyInformationModel(
...     policy_identifier="1.3.6.1.5.5.7.2.1",
...     policy_qualifiers=["https://ca.example.com/cps", notice]
... )  
PolicyInformationModel(
    policy_identifier='1.3.6.1.5.5.7.2.1',
    policy_qualifiers=[
        'https://ca.example.com/cps',
        UserNoticeModel(notice_reference=None, explicit_text='my text')
    ]
)

property cryptography: PolicyInformation¶: Convert to a PolicyInformation instance.

class django_ca.pydantic.extension_attributes.SignedCertificateTimestampModel(*, version: Literal['v1'] = 'v1', log_id: bytes, timestamp: datetime, entry_type: Literal['precertificate', 'x509_certificate'])[source]¶

Pydantic model wrapping SignedCertificateTimestamp.

Note

Due to library limitations, this model cannot be converted to a cryptography class.

>>> SignedCertificateTimestampModel(
...     log_id=b"MTIz", timestamp=datetime(2023, 12, 10), entry_type="precertificate"
... )  
SignedCertificateTimestampModel(
    version='v1',
    log_id=b'123',
    timestamp=datetime.datetime(2023, 12, 10, 0, 0),
    entry_type='precertificate'
)

property cryptography: NoReturn¶: Will always raise an exception for this class.

class django_ca.pydantic.extension_attributes.UnrecognizedExtensionValueModel(*, oid: str, value: bytes)[source]¶

Pydantic model for a UnrecognizedExtension extension.

The value a base64 encoded bytes value, and the oid is any dotted string:

>>> UnrecognizedExtensionValueModel(value=b"MTIz", oid="1.2.3")
UnrecognizedExtensionValueModel(oid='1.2.3', value=b'123')

property cryptography: UnrecognizedExtension¶: The UnrecognizedExtension instance.

class django_ca.pydantic.extension_attributes.UserNoticeModel(*, notice_reference: NoticeReferenceModel | None = None, explicit_text: str | None)[source]¶

Pydantic model wrapping UserNotice.

In its simplest form, the model can just take an explicit text:

>>> UserNoticeModel(explicit_text="my text")
UserNoticeModel(notice_reference=None, explicit_text='my text')

But it may also take notice reference:

>>> ref = NoticeReferenceModel(notice_numbers=[1, 2, 3])
>>> UserNoticeModel(notice_reference=ref, explicit_text="my text")  
UserNoticeModel(notice_reference=NoticeReferenceModel(organization=None,
                    notice_numbers=[1, 2, 3]),
                explicit_text='my text')

property cryptography: UserNotice¶: Convert to a UserNotice instance.

CRL extensions¶

Models for CRL extensions are not currently used within the project itself.

class django_ca.pydantic.CRLNumberModel(*, type: Literal['crl_number'] = 'crl_number', critical: bool = False, value: int)[source]¶

Pydantic model for a CRLNumber extension.

The value is an integer:

>>> CRLNumberModel(value=1)
CRLNumberModel(critical=False, value=1)

class django_ca.pydantic.DeltaCRLIndicatorModel(*, type: Literal['delta_crl_indicator'] = 'delta_crl_indicator', critical: bool = True, value: int)[source]¶

Pydantic model for a DeltaCRLIndicator extension.

The value is an integer:

>>> DeltaCRLIndicatorModel(value=1)
DeltaCRLIndicatorModel(critical=True, value=1)

`django_ca.pydantic` - Pydantic models¶

Type aliases¶

Cryptography classes¶

Name¶

GeneralName¶

Extensions¶

Extension attributes¶

CRL extensions¶

django_ca.pydantic - Pydantic models¶

Type aliases¶

Cryptography classes¶

Name¶

GeneralName¶

Extensions¶

Extension attributes¶

CRL extensions¶

`django_ca.pydantic` - Pydantic models¶