django_ca.utils - utility functions

Reusable utility functions used throughout django-ca.

django_ca.utils.ELLIPTIC_CURVE_NAMES = {'brainpoolP256r1': <class 'cryptography.hazmat.primitives.asymmetric.ec.BrainpoolP256R1'>, 'brainpoolP384r1': <class 'cryptography.hazmat.primitives.asymmetric.ec.BrainpoolP384R1'>, 'brainpoolP512r1': <class 'cryptography.hazmat.primitives.asymmetric.ec.BrainpoolP512R1'>, 'secp192r1': <class 'cryptography.hazmat.primitives.asymmetric.ec.SECP192R1'>, 'secp224r1': <class 'cryptography.hazmat.primitives.asymmetric.ec.SECP224R1'>, 'secp256k1': <class 'cryptography.hazmat.primitives.asymmetric.ec.SECP256K1'>, 'secp256r1': <class 'cryptography.hazmat.primitives.asymmetric.ec.SECP256R1'>, 'secp384r1': <class 'cryptography.hazmat.primitives.asymmetric.ec.SECP384R1'>, 'secp521r1': <class 'cryptography.hazmat.primitives.asymmetric.ec.SECP521R1'>, 'sect163k1': <class 'cryptography.hazmat.primitives.asymmetric.ec.SECT163K1'>, 'sect163r2': <class 'cryptography.hazmat.primitives.asymmetric.ec.SECT163R2'>, 'sect233k1': <class 'cryptography.hazmat.primitives.asymmetric.ec.SECT233K1'>, 'sect233r1': <class 'cryptography.hazmat.primitives.asymmetric.ec.SECT233R1'>, 'sect283k1': <class 'cryptography.hazmat.primitives.asymmetric.ec.SECT283K1'>, 'sect283r1': <class 'cryptography.hazmat.primitives.asymmetric.ec.SECT283R1'>, 'sect409k1': <class 'cryptography.hazmat.primitives.asymmetric.ec.SECT409K1'>, 'sect409r1': <class 'cryptography.hazmat.primitives.asymmetric.ec.SECT409R1'>, 'sect571k1': <class 'cryptography.hazmat.primitives.asymmetric.ec.SECT571K1'>, 'sect571r1': <class 'cryptography.hazmat.primitives.asymmetric.ec.SECT571R1'>}

Mapping of canonical elliptic curve names to the implementing classes

django_ca.utils.GENERAL_NAME_RE = re.compile('^(email|URI|IP|DNS|RID|dirName|otherName):(.*)', re.IGNORECASE)

Regular expression to match general names.

class django_ca.utils.GeneralNameList(iterable=None)

List that holds GeneralName instances and parses str when added.

A GeneralNameList is a list subclass that will always only hold GeneralName instances, but any str passed to it will be passed to parse_general_name():

>>> from cryptography import x509
>>> l = GeneralNameList(['example.com'])
>>> l += ['DNS:example.net', x509.DNSName('example.org')]
>>> print(l)
<GeneralNameList: ['DNS:example.com', 'DNS:example.net', 'DNS:example.org']>
>>> 'example.com' in l, 'DNS:example.com' in l, x509.DNSName('example.com') in l
(True, True, True)
>>> l == ['example.com', 'example.net', 'example.org']
True
>>> l == [x509.DNSName('example.com'), 'example.net', 'DNS:example.org']
True

append(value)

Equivalent to list.append().

count(value)

Equivalent to list.count().

extend(iterable)

Equivalent to list.extend().

index(value, *args)

Equivalent to list.index().

insert(index, value)

Equivalent to list.insert().

remove(value)

Equivalent to list.remove().

serialize()

Generate a list of formatted names.

django_ca.utils.HASH_ALGORITHM_NAMES = {'md5': <class 'cryptography.hazmat.primitives.hashes.MD5'>, 'sha1': <class 'cryptography.hazmat.primitives.hashes.SHA1'>, 'sha224': <class 'cryptography.hazmat.primitives.hashes.SHA224'>, 'sha256': <class 'cryptography.hazmat.primitives.hashes.SHA256'>, 'sha3-224': <class 'cryptography.hazmat.primitives.hashes.SHA3_224'>, 'sha3-256': <class 'cryptography.hazmat.primitives.hashes.SHA3_256'>, 'sha3-384': <class 'cryptography.hazmat.primitives.hashes.SHA3_384'>, 'sha3-512': <class 'cryptography.hazmat.primitives.hashes.SHA3_512'>, 'sha384': <class 'cryptography.hazmat.primitives.hashes.SHA384'>, 'sha512': <class 'cryptography.hazmat.primitives.hashes.SHA512'>, 'sha512-224': <class 'cryptography.hazmat.primitives.hashes.SHA512_224'>, 'sha512-256': <class 'cryptography.hazmat.primitives.hashes.SHA512_256'>, 'sm3': <class 'cryptography.hazmat.primitives.hashes.SM3'>}

Mapping of canonical hash algorithm names to the implementing classes

django_ca.utils.NAME_RE = re.compile('(?:/+|\\A)\\s*(?P<field>[^\\s]*?)\\s*=(?P<quote>[\\\'"])?\\s*(?P<content>(?(quote).*?|[^/]*))\\s*(?(quote)(?<!\\\\)(?P=quote))', re.IGNORECASE)

Regular expression to match RDNs out of a full x509 name.

django_ca.utils.OID_NAME_MAPPINGS = {<ObjectIdentifier(oid=2.5.4.15, name=businessCategory)>: 'businessCategory', <ObjectIdentifier(oid=2.5.4.3, name=commonName)>: 'CN', <ObjectIdentifier(oid=2.5.4.6, name=countryName)>: 'C', <ObjectIdentifier(oid=2.5.4.46, name=dnQualifier)>: 'dnQualifier', <ObjectIdentifier(oid=0.9.2342.19200300.100.1.25, name=domainComponent)>: 'DC', <ObjectIdentifier(oid=1.2.840.113549.1.9.1, name=emailAddress)>: 'emailAddress', <ObjectIdentifier(oid=2.5.4.44, name=generationQualifier)>: 'generationQualifier', <ObjectIdentifier(oid=2.5.4.42, name=givenName)>: 'givenName', <ObjectIdentifier(oid=1.2.643.3.131.1.1, name=INN)>: 'inn', <ObjectIdentifier(oid=1.3.6.1.4.1.311.60.2.1.3, name=jurisdictionCountryName)>: 'jurisdictionCountryName', <ObjectIdentifier(oid=1.3.6.1.4.1.311.60.2.1.1, name=jurisdictionLocalityName)>: 'jurisdictionLocalityName', <ObjectIdentifier(oid=1.3.6.1.4.1.311.60.2.1.2, name=jurisdictionStateOrProvinceName)>: 'jurisdictionStateOrProvinceName', <ObjectIdentifier(oid=2.5.4.7, name=localityName)>: 'L', <ObjectIdentifier(oid=1.2.643.100.1, name=OGRN)>: 'ogrn', <ObjectIdentifier(oid=2.5.4.11, name=organizationalUnitName)>: 'OU', <ObjectIdentifier(oid=2.5.4.10, name=organizationName)>: 'O', <ObjectIdentifier(oid=2.5.4.16, name=postalAddress)>: 'postalAddress', <ObjectIdentifier(oid=2.5.4.17, name=postalCode)>: 'postalCode', <ObjectIdentifier(oid=2.5.4.65, name=pseudonym)>: 'pseudonym', <ObjectIdentifier(oid=2.5.4.5, name=serialNumber)>: 'serialNumber', <ObjectIdentifier(oid=1.2.643.100.3, name=SNILS)>: 'snils', <ObjectIdentifier(oid=2.5.4.8, name=stateOrProvinceName)>: 'ST', <ObjectIdentifier(oid=2.5.4.9, name=streetAddress)>: 'streetAddress', <ObjectIdentifier(oid=2.5.4.4, name=surname)>: 'sn', <ObjectIdentifier(oid=2.5.4.12, name=title)>: 'title', <ObjectIdentifier(oid=1.2.840.113549.1.9.2, name=unstructuredName)>: 'unstructuredName', <ObjectIdentifier(oid=0.9.2342.19200300.100.1.1, name=userID)>: 'uid', <ObjectIdentifier(oid=2.5.4.45, name=x500UniqueIdentifier)>: 'x500UniqueIdentifier'}

Map OID objects to IDs used in subject strings

django_ca.utils.SERIAL_RE = re.compile('^([0-9A-F][0-9A-F]:?)+[0-9A-F][0-9A-F]?$')

Regular expression matching certificate serials as hex

django_ca.utils.add_colons(value, pad='0')

Add colons after every second digit.

This function is used in functions to prettify serials.

>>> add_colons('teststring')
'te:st:st:ri:ng'

Parameters

sstr

The string to add colons to

padstr, optional

If not an empty string, pad the string so that the last element always has two characters. The default is "0".

django_ca.utils.bytes_to_hex(value)

Convert a bytes array to hex.

>>> bytes_to_hex(b'test')
'74:65:73:74'

django_ca.utils.encode_dns(name)

IDNA encoding for domains.

Examples:

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

django_ca.utils.encode_url(url)

IDNA encoding for domains in URLs.

Examples:

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

django_ca.utils.format_general_name(name)

Format a single general name.

>>> import ipaddress
>>> format_general_name(x509.DNSName('example.com'))
'DNS:example.com'
>>> format_general_name(x509.IPAddress(ipaddress.IPv4Address('127.0.0.1')))
'IP:127.0.0.1'

django_ca.utils.format_name(subject)

Convert a subject into the canonical form for distinguished names.

This function does not take care of sorting the subject in any meaningful order.

Examples:

>>> format_name([('CN', 'example.com'), ])
'/CN=example.com'
>>> format_name([('CN', 'example.com'), ('O', "My Organization"), ])
'/CN=example.com/O=My Organization'

django_ca.utils.format_relative_name(name)

Convert a relative name (RDN) into a canonical form.

Examples:

>>> format_relative_name([('C', 'AT'), ('CN', 'example.com')])
'/C=AT/CN=example.com'
>>> format_relative_name(x509.RelativeDistinguishedName([
...     x509.NameAttribute(NameOID.COMMON_NAME, 'example.com')
... ]))
'/CN=example.com'

django_ca.utils.generate_private_key(key_size, key_type, ecc_curve)

Generate a private key.

This function assumes that you called validate_key_parameters() on the input values and does not do any sanity checks on its own.

Parameters

key_sizeint

The size of the private key (not used for ECC keys).

key_type{‘RSA’, ‘DSA’, ‘ECC’}

The type of the private key.

ecc_curveEllipticCurve

The ECC curve to use for an ECC key.

Returns

key

A private key of the appropriate type.

django_ca.utils.get_cert_builder(expires, serial=None)

Get a basic X.509 certificate builder object.

Parameters

expiresdatetime

Serial number to set for this certificate. Use random_serial_number() to generate such a value. By default, a value will be generated.

django_ca.utils.get_crl_cache_key(serial, algorithm=<cryptography.hazmat.primitives.hashes.SHA512 object>, encoding=Encoding.DER, scope=None)

Get the cache key for a CRL with the given parameters.

django_ca.utils.hex_to_bytes(value)

Convert a hex number to bytes.

This should be the inverse of bytes_to_hex().

>>> hex_to_bytes('74:65:73:74')
b'test'

django_ca.utils.int_to_hex(i)

Create a hex-representation of the given serial.

>>> int_to_hex(12345678)
'BC614E'

django_ca.utils.is_power2(num)

Return True if num is a power of 2.

>>> is_power2(4)
True
>>> is_power2(3)
False

django_ca.utils.multiline_url_validator(value)

Validate that a TextField contains one valid URL per line.

See also

https://docs.djangoproject.com/en/1.9/ref/validators/

django_ca.utils.parse_csr(csr, csr_format)

Parse a CSR in the given format.

Deprecated since version 1.18.0: This function is no longer useful and will be removed in django-ca 1.20.0.

Parameters

csrstr or bytes or CertificateSigningRequest

The CSR to parse.

csr_formatEncoding

The format that the CSR is in.

django_ca.utils.parse_encoding(value=None)

Parse a value to a valid encoding.

This function accepts either a member of Encoding or a string describing a member. If no value is passed, it will assume PEM as a default value. Note that "ASN1" is treated as an alias for "DER".

>>> parse_encoding()
<Encoding.PEM: 'PEM'>
>>> parse_encoding('DER')
<Encoding.DER: 'DER'>
>>> parse_encoding(Encoding.PEM)
<Encoding.PEM: 'PEM'>

django_ca.utils.parse_expires(expires=None)

Parse a value specifying an expiry into a concrete datetime.

django_ca.utils.parse_general_name(name)

Parse a general name from user input.

This function will do its best to detect the intended type of any value passed to it:

>>> parse_general_name('example.com')
<DNSName(value='example.com')>
>>> parse_general_name('*.example.com')
<DNSName(value='*.example.com')>
>>> parse_general_name('.example.com')  # Syntax used e.g. for NameConstraints: All levels of subdomains
<DNSName(value='.example.com')>
>>> parse_general_name('user@example.com')
<RFC822Name(value='user@example.com')>
>>> parse_general_name('https://example.com')
<UniformResourceIdentifier(value='https://example.com')>
>>> parse_general_name('1.2.3.4')
<IPAddress(value=1.2.3.4)>
>>> parse_general_name('fd00::1')
<IPAddress(value=fd00::1)>
>>> parse_general_name('/CN=example.com')
<DirectoryName(value=<Name(CN=example.com)>)>

The default fallback is to assume a DNSName. If this doesn’t work, an exception will be raised:

>>> parse_general_name('foo..bar`*123')  
Traceback (most recent call last):
    ...
ValueError: Could not parse name: foo..bar`*123

If you want to override detection, you can prefix the name to match GENERAL_NAME_RE:

>>> parse_general_name('email:user@example.com')
<RFC822Name(value='user@example.com')>
>>> parse_general_name('URI:https://example.com')
<UniformResourceIdentifier(value='https://example.com')>
>>> parse_general_name('dirname:/CN=example.com')
<DirectoryName(value=<Name(CN=example.com)>)>

Some more exotic values can only be generated by using this prefix:

>>> parse_general_name('rid:2.5.4.3')
<RegisteredID(value=<ObjectIdentifier(oid=2.5.4.3, name=commonName)>)>
>>> parse_general_name('otherName:2.5.4.3;UTF8:example.com')
<OtherName(type_id=<ObjectIdentifier(oid=2.5.4.3, name=commonName)>, value=b'\x0c\x0bexample.com')>

If you give a prefixed value, this function is less forgiving of any typos and does not catch any exceptions:

>>> parse_general_name('email:foo@bar com')
Traceback (most recent call last):
    ...
ValueError: Invalid domain: bar com

django_ca.utils.parse_hash_algorithm(value=None)

Parse a hash algorithm value.

The most common use case is to pass a str naming a class in hashes.

For convenience, passing None will return the value of CA_DIGEST_ALGORITHM, and passing an HashAlgorithm will return that instance unchanged.

Example usage:

>>> parse_hash_algorithm()  
<cryptography.hazmat.primitives.hashes.SHA512 object at ...>
>>> parse_hash_algorithm('SHA512')  
<cryptography.hazmat.primitives.hashes.SHA512 object at ...>
>>> parse_hash_algorithm(' SHA512 ')  
<cryptography.hazmat.primitives.hashes.SHA512 object at ...>
>>> parse_hash_algorithm(hashes.SHA512)  
<cryptography.hazmat.primitives.hashes.SHA512 object at ...>
>>> parse_hash_algorithm(hashes.SHA512())  
<cryptography.hazmat.primitives.hashes.SHA512 object at ...>
>>> parse_hash_algorithm('Wrong')  
Traceback (most recent call last):
    ...
ValueError: Unknown hash algorithm: Wrong
>>> parse_hash_algorithm(object())  
Traceback (most recent call last):
    ...
ValueError: Unknown type passed: object

Parameters

valuestr or HashAlgorithm, optional

The value to parse, the function description on how possible values are used.

Returns

algorithm

A HashAlgorithm instance.

Raises

ValueError

If an unknown object is passed or if value does not name a known algorithm.

django_ca.utils.parse_key_curve(value=None)

Parse an elliptic curve value.

This function uses a value identifying an elliptic curve to return an EllipticCurve instance. The name must match a class name of one of the classes named under “Elliptic Curves” in Elliptic curve cryptography.

For convenience, passing None will return the value of CA_DEFAULT_ECC_CURVE, and passing an EllipticCurve will return that instance unchanged.

Example usage:

>>> parse_key_curve('SECP256R1')  
<cryptography.hazmat.primitives.asymmetric.ec.SECP256R1 object at ...>
>>> parse_key_curve('SECP384R1')  
<cryptography.hazmat.primitives.asymmetric.ec.SECP384R1 object at ...>
>>> parse_key_curve(ec.SECP256R1())  
<cryptography.hazmat.primitives.asymmetric.ec.SECP256R1 object at ...>
>>> parse_key_curve()  
<cryptography.hazmat.primitives.asymmetric.ec.SECP256R1 object at ...>

Parameters

valuestr, otional

The name of the curve or None to return the default curve.

Returns

curve

An EllipticCurve instance.

Raises

ValueError

If the named curve is not supported.

django_ca.utils.parse_name(name)

Parses a subject string as used in OpenSSLs command line utilities.

The name is expected to be close to the subject format commonly used by OpenSSL, for example /C=AT/L=Vienna/CN=example.com/emailAddress=user@example.com. The function does its best to be lenient on deviations from the format, object identifiers are case-insensitive (e.g. cn is the same as CN, whitespace at the start and end is stripped and the subject does not have to start with a slash (/).

>>> parse_name('/CN=example.com')
[('CN', 'example.com')]
>>> parse_name('c=AT/l= Vienna/o="ex org"/CN=example.com')
[('C', 'AT'), ('L', 'Vienna'), ('O', 'ex org'), ('CN', 'example.com')]

Dictionary keys are normalized to the values of OID_NAME_MAPPINGS and keys will be sorted based on x509 name specifications regardless of the given order:

>>> parse_name('L="Vienna / District"/EMAILaddress=user@example.com')
[('L', 'Vienna / District'), ('emailAddress', 'user@example.com')]
>>> parse_name('/C=AT/CN=example.com') == parse_name('/CN=example.com/C=AT')
True

Due to the magic of NAME_RE, the function even supports quoting strings and including slashes, so strings like /OU="Org / Org Unit"/CN=example.com will work as expected.

>>> parse_name('L="Vienna / District"/CN=example.com')
[('L', 'Vienna / District'), ('CN', 'example.com')]

But note that it’s still easy to trick this function, if you really want to. The following example is not a valid subject, the location is just bogus, and whatever you were expecting as output, it’s certainly different:

>>> parse_name('L="Vienna " District"/CN=example.com')
[('L', 'Vienna'), ('CN', 'example.com')]

Examples of where this string is used are:

# openssl req -new -key priv.key -out csr -utf8 -batch -sha256 -subj '/C=AT/CN=example.com'
# openssl x509 -in cert.pem -noout -subject -nameopt compat
/C=AT/L=Vienna/CN=example.com

django_ca.utils.read_file(path)

Read the file from the given path.

If path is an absolute path, reads a file from the local file system. For relative paths, read the file using the storage backend configured using CA_FILE_STORAGE.

django_ca.utils.sanitize_serial(value)

Sanitize a serial provided by user/untrusted input.

This function is intended to be used to get a serial as used internally by django-ca from untrusted user input. Internally, serials are stored in upper case and without : and leading zeros, but user output adds at least :.

Examples:

>>> sanitize_serial('01:aB')
'1AB'

django_ca.utils.shlex_split(val, sep)

Split a character on the given set of characters.

Example:

>>> shlex_split('foo,bar', ', ')
['foo', 'bar']
>>> shlex_split('foo\\,bar1', ',')  # escape a separator
['foo,bar1']
>>> shlex_split('"foo,bar", bla', ', ')
['foo,bar', 'bla']
>>> shlex_split('foo,"bar,bla"', ',')
['foo', 'bar,bla']

django_ca.utils.sort_name(subject)

Returns the subject in the correct order for a x509 subject.

django_ca.utils.validate_email(addr)

Validate an email address.

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

>>> validate_email('foo@bar.com')
'foo@bar.com'
>>> validate_email('foo@bar com')
Traceback (most recent call last):
    ...
ValueError: Invalid domain: bar com

django_ca.utils.validate_hostname(hostname, allow_port=False)

Validate a hostname, optionally with a given port.

>>> validate_hostname('example.com')
'example.com'
>>> validate_hostname('example.com:8000', allow_port=True)
'example.com:8000'

Parameters

hostnamestr

The hostname to validate.

allow_portbool, optional

If True, the hostname can also contain an optional port number, e.g. “example.com:8000”.

Raises

ValueError

If hostname or port are not valid.

django_ca.utils.validate_key_parameters(key_size=None, key_type='RSA', ecc_curve=None)

Validate parameters for private key generation and return sanitized values.

This function can be used to fail early if invalid parameters are passed, before the private key is generated.

>>> validate_key_parameters()  # defaults
(1024, 'RSA', None)
>>> validate_key_parameters(4096, 'ECC', None)  
(None, 'ECC', <cryptography.hazmat.primitives.asymmetric.ec.SECP256R1 object at ...>)
>>> validate_key_parameters(4000, 'RSA', None)
Traceback (most recent call last):
    ...
ValueError: 4000: Key size must be a power of two

django_ca.utils.x509_name(name)

Parses a subject into a x509.Name.

If name is a string, parse_name() is used to parse it.

>>> x509_name('/C=AT/CN=example.com')
<Name(C=AT,CN=example.com)>
>>> x509_name([('C', 'AT'), ('CN', 'example.com')])
<Name(C=AT,CN=example.com)>

django_ca.utils.x509_relative_name(name)

Parse a relative name (RDN) into a RelativeDistinguishedName.

>>> x509_relative_name('/CN=example.com')
<RelativeDistinguishedName(CN=example.com)>
>>> x509_relative_name([('CN', 'example.com')])
<RelativeDistinguishedName(CN=example.com)>