`django_ca.pydantic` - Pydantic models

Type aliases

Reusable type aliases for Pydantic models.

django_ca.pydantic.type_aliases.AnnotatedEllipticCurveName

Annotated version of EllipticCurveName.

This type will also accept instances of EllipticCurve and convert them transparently.

alias of Annotated[Literal[‘sect571r1’, ‘sect409r1’, ‘sect283r1’, ‘sect233r1’, ‘sect163r2’, ‘sect571k1’, ‘sect409k1’, ‘sect283k1’, ‘sect233k1’, ‘sect163k1’, ‘secp521r1’, ‘secp384r1’, ‘secp256r1’, ‘secp256k1’, ‘secp224r1’, ‘secp192r1’, ‘brainpoolP256r1’, ‘brainpoolP384r1’, ‘brainpoolP512r1’], BeforeValidator(func=elliptic_curve_validator, json_schema_input_type=PydanticUndefined)]

django_ca.pydantic.type_aliases.AnnotatedSignatureHashAlgorithmName

Annotated version of SignatureHashAlgorithmName.

This type will also accept instances of HashAlgorithm and convert them transparently.

alias of Annotated[Literal[‘SHA-224’, ‘SHA-256’, ‘SHA-384’, ‘SHA-512’, ‘SHA3/224’, ‘SHA3/256’, ‘SHA3/384’, ‘SHA3/512’], BeforeValidator(func=signature_hash_algorithm_validator, json_schema_input_type=PydanticUndefined)]

django_ca.pydantic.type_aliases.AnnotatedSignatureHashAlgorithmNameWithLegacy

Same as AnnotatedSignatureHashAlgorithmName, but also accepts legacy algorithms.

alias of Annotated[Literal[‘MD5’, ‘SHA1’] | Literal[‘SHA-224’, ‘SHA-256’, ‘SHA-384’, ‘SHA-512’, ‘SHA3/224’, ‘SHA3/256’, ‘SHA3/384’, ‘SHA3/512’], BeforeValidator(func=signature_hash_algorithm_validator_with_legacy_names, json_schema_input_type=PydanticUndefined)]

django_ca.pydantic.type_aliases.Base64EncodedBytes

A str type that converts bytes to base64-encoded strings.

This type differs from pydantic.Base64Bytes in that bytes will be considered as unencoded input and converted to base64.

alias of Annotated[str, BeforeValidator(func=bytes_to_base64_str_validator, json_schema_input_type=PydanticUndefined), AfterValidator(func=base64_str_validator)]

django_ca.pydantic.type_aliases.CertificateRevocationListReasonCode

A subset of ReasonFlags that allows only reason codes valid in a certificate revocation list (CRL).

alias of Annotated[ReasonFlags, BeforeValidator(func=reason_flag_validator, json_schema_input_type=PydanticUndefined), AfterValidator(func=reason_flag_crl_scope_validator)]

django_ca.pydantic.type_aliases.OIDType

A string that will convert ObjectIdentifier objects.

This type alias will also validate the x509 dotted string format.

alias of Annotated[str, BeforeValidator(func=oid_parser, json_schema_input_type=PydanticUndefined), AfterValidator(func=oid_validator)]

django_ca.pydantic.type_aliases.PowerOfTwoInt

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, AfterValidator(func=is_power_two_validator)]

django_ca.pydantic.type_aliases.PromiseTypeAlias

Type alias for Djangos lazily translated strings.

Translated strings will be evaluated (= translated) upon JSON serialization. For JSON schemas, this type alias identifies itself as a normal string.

alias of Annotated[Promise, PlainSerializer(func=~django_ca.pydantic.type_aliases., return_type=str, when_used=always)]

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, upper-case any lower-case strings and remove ‘:’. 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, BeforeValidator(func=int_to_hex_parser, json_schema_input_type=PydanticUndefined), AfterValidator(func=serial_validator), FieldInfo(annotation=NoneType, required=True, metadata=[MinLen(min_length=1), MaxLen(max_length=40), _PydanticGeneralMetadata(pattern=’^[A-F0-9]+$’)])]

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[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[str | bytes]: The NameAttribute instance for this model.

class django_ca.pydantic.NameModel[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[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.AdmissionModel[source]

Pydantic model wrapping Admission.

Added in version 2.1.0.

property cryptography: Admission: Convert to a Admission instance.

class django_ca.pydantic.extension_attributes.AdmissionsValueModel[source]

Pydantic model wrapping Admissions.

Added in version 2.1.0.

property cryptography: Admissions: Convert to a Admissions instance.

class django_ca.pydantic.extension_attributes.AuthorityKeyIdentifierValueModel[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. This is a base64-encoded string:

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

You may also pass bytes instead, in which case the value will be base64 encoded:

>>> AuthorityKeyIdentifierValueModel(key_identifier=b"123")
AuthorityKeyIdentifierValueModel(
    key_identifier='MTIz', 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[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[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[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[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[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.NamingAuthorityModel[source]

Pydantic model wrapping NamingAuthority.

Added in version 2.1.0.

property cryptography: NamingAuthority: Convert to a NamingAuthority instance.

class django_ca.pydantic.extension_attributes.NoticeReferenceModel[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[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[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.PrivateKeyUsagePeriodValueModel[source]

Pydantic model wrapping PrivateKeyUsagePeriod.

validate_values() → Self[source]: Validate that at least one value is set, and order of values.

class django_ca.pydantic.extension_attributes.ProfessionInfoModel[source]

Pydantic model wrapping ProfessionInfo.

Added in version 2.1.0.

check_consistency() → ProfessionInfoModel[source]: Verify that profession_oids has the same length as profession_items if set.

property cryptography: ProfessionInfo: Convert to a ProfessionInfo instance.

class django_ca.pydantic.extension_attributes.SignedCertificateTimestampModel[source]

Pydantic model wrapping SignedCertificateTimestamp.

Note

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

>>> SignedCertificateTimestampModel(
...     log_id="MTIz", timestamp=datetime(2023, 12, 10), entry_type="precertificate"
... )
SignedCertificateTimestampModel(
    version='v1',
    log_id='MTIz',
    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[source]

Pydantic model for a UnrecognizedExtension extension.

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

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

You can also pass bytes to value, in which case it will base base64 encoded:

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

property cryptography: UnrecognizedExtension: The UnrecognizedExtension instance.

class django_ca.pydantic.extension_attributes.UserNoticeModel[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[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[source]

Pydantic model for a DeltaCRLIndicator extension.

The value is an integer:

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

Validators

Validators for Pydantic models.

django_ca.pydantic.validators.access_method_parser(value: Any) → Any[source]: Convert access method type aliases to dotted string.

django_ca.pydantic.validators.base64_str_validator(value: str) → str[source]: Validator that asserts that the passed string is a valid Base64 encoded string.

django_ca.pydantic.validators.bytes_to_base64_str_validator(value: Any) → Any[source]: Encode bytes as base64-encoded string.

django_ca.pydantic.validators.crl_scope_validator(only_contains_ca_certs: bool, only_contains_user_certs: bool, only_contains_attribute_certs: bool, only_some_reasons: Iterable[ReasonFlags] | None) → None[source]: Validate the scope of a certificate revocation list (CRL).

django_ca.pydantic.validators.dns_validator(name: str) → str[source]

IDNA encoding for domains.

Examples:

>>> dns_validator('example.com')
'example.com'
>>> dns_validator('exämple.com')
'xn--exmple-cua.com'
>>> dns_validator('.exämple.com')
'.xn--exmple-cua.com'
>>> dns_validator('*.exämple.com')
'*.xn--exmple-cua.com'

django_ca.pydantic.validators.elliptic_curve_validator(value: Any) → Any[source]: Convert a EllipticCurve into a canonical name.

django_ca.pydantic.validators.email_validator(addr: str) → str[source]

Validate an email address.

This function raises ValueError if the email address is not valid.

>>> email_validator("user@example.com")
'user@example.com'
>>> email_validator("user@exämple.com")
'user@xn--exmple-cua.com'

django_ca.pydantic.validators.extended_key_usage_validator(value: str) → str[source]: Convert human-readable ExtendedKeyUsage values into dotted strings.

django_ca.pydantic.validators.int_to_hex_parser(value: Any) → Any[source]: Convert an integer to an upper-case hex-string.

django_ca.pydantic.validators.is_power_two_validator(value: int) → int[source]: Validate that a given integer is a power of two.

django_ca.pydantic.validators.key_usage_validator(value: Any) → Any[source]: Convert a human-readable key usage name to a valid parameter.

django_ca.pydantic.validators.name_oid_dotted_string_parser(value: Any) → Any[source]: Convert human-readable NameOID values into dotted strings.

django_ca.pydantic.validators.name_oid_parser(value: Any) → Any[source]: Parse a NameOID string or dotted string to a x509 Object Identifier.

django_ca.pydantic.validators.non_empty_validator(value: list[str]) → list[str][source]: Validate that the given list is not empty.

django_ca.pydantic.validators.oid_parser(value: str | ObjectIdentifier) → str[source]: Validate a ObjectIdentifier.

django_ca.pydantic.validators.oid_validator(value: str) → str[source]: Validate that the given value is a valid dotted string.

django_ca.pydantic.validators.pem_csr_validator(value: bytes) → bytes[source]: Validate that the given bytes is a valid CSR in PEM format.

django_ca.pydantic.validators.reason_flag_crl_scope_validator(value: ReasonFlags) → ReasonFlags[source]: Ensure that the ReasonFlags is allowed in a CRL scope.

django_ca.pydantic.validators.reason_flag_validator(value: Any) → Any[source]: Validate a str to a ReasonFlags.

django_ca.pydantic.validators.serial_validator(value: str) → str[source]: Validator for serials.

django_ca.pydantic.validators.signature_hash_algorithm_validator(value: Any) → Any[source]: Convert a HashAlgorithm into a canonical name.

django_ca.pydantic.validators.signature_hash_algorithm_validator_with_legacy_names(value: Any) → Any[source]: Same, but allows legacy names.

django_ca.pydantic.validators.timedelta_as_number_parser(unit: Literal['seconds', 'hours', 'days'] = 'seconds') → Callable[[Any], Any][source]: Validator for timedelta.

Warning

This validator differs in that it has to be called with a unit for timedeltas.

django_ca.pydantic.validators.tls_feature_validator(value: str | TLSFeatureType) → str[source]: Validate a TLSFeatureType.

django_ca.pydantic.validators.unique_validator(value: Sequence[T]) → Sequence[T][source]: Validate that every string in the list is unique.

django_ca.pydantic.validators.url_validator(url: str) → str[source]

IDNA encoding for domains in URLs.

Examples:

>>> url_validator('https://example.com')
'https://example.com'
>>> url_validator('https://exämple.com/foobar')
'https://xn--exmple-cua.com/foobar'
>>> url_validator('https://exämple.com:8000/foobar')
'https://xn--exmple-cua.com:8000/foobar'

`django_ca.pydantic` - Pydantic models

Type aliases

Cryptography classes

Name

GeneralName

Extensions

Extension attributes

CRL extensions

Validators

django_ca.pydantic - Pydantic models

Type aliases

Cryptography classes

Name

GeneralName

Extensions

Extension attributes

CRL extensions

Validators

`django_ca.pydantic` - Pydantic models