tiny_ca.ca_factory.utils.serial module

Thin wrapper around SerialWithEncoding for reading serial numbers from existing x509.Certificate objects.

CertSerialParser does not generate serial numbers — that responsibility belongs to SerialWithEncoding.generate. Its sole purpose is to provide a consistent, typed interface for reading serials back from certificates that have already been issued.

class tiny_ca.ca_factory.utils.serial.CertSerialParser[source]

Bases: object

Read-only accessor for X.509 certificate serial numbers.

Provides two views of the same serial number stored in an x509.Certificate:

  • raw — the plain int exactly as stored in the certificate.

  • typed — a (CertType, name_prefix) pair decoded by SerialWithEncoding.parse, useful when the certificate was issued by this library and its serial number encodes type and name information.

All methods are @staticmethod; no instantiation is required.

static raw(cert)[source]

Return the serial number of cert as a plain integer.

This is a direct read of cert.serial_number with no transformation. Use this value when you need to pass the serial to database queries, CRL builders, or other low-level X.509 operations.

Parameters:

cert (x509.Certificate) – The certificate whose serial number should be read.

Returns:

The raw integer serial number as stored in the certificate.

Return type:

int

Examples

>>> serial = CertSerialParser.raw(my_cert)
>>> record = db.get_by_serial(serial)
async static raw_async(cert)[source]

Async version of raw().

Contains reading in the thread pool so as not to block the event loop.

Parameters:

  • cert (x509.Certificate)

  • Certificate

  • read. (serial number must be)

Return type:

int

Returns:

  • int

  • The serial number is int.

Examples

>>> serial = await CertSerialParser.raw_async(my_cert)
>>> record = await db.get_by_serial(serial)
static typed(cert)[source]

Decode the certificate’s serial number into its embedded type and name.

Delegates to SerialWithEncoding.parse which reverses the bit-packing applied during issuance. The serial number layout is:

[ 16-bit prefix ][ 80-bit encoded name ][ 64-bit random ]

Only certificates whose serials were generated by SerialWithEncoding (i.e. issued by this library) will decode meaningfully. Certificates from external CAs will return (None, "") or an unrelated string.

Parameters:

cert (x509.Certificate) – The certificate to decode.

Returns:

(cert_type, name_prefix) where:

  • cert_type is the CertType enum member extracted from the prefix bits, or None if the prefix is unrecognised.

  • name_prefix is the up-to-10-character ASCII string packed into the name bits of the serial (may be shorter due to zero-padding).

Return type:

tuple[CertType | None, str]

Examples

>>> cert_type, name = CertSerialParser.typed(my_cert)
>>> assert cert_type == CertType.SERVICE
>>> assert name.startswith("nginx")
async static typed_async(cert)[source]

Async version of typed().

Decodes the serial number of the certificate for the type of name that is installed, non-blocking event loop.

Parameters:

  • cert (x509.Certificate)

  • decoding. (Certificate for)

Return type:

tuple[CertType | None, str]

Returns:

  • tuple[CertType | None, str]

  • (cert_type, name_prefix)

Examples

>>> cert_type, name = await CertSerialParser.typed_async(my_cert)
>>> assert name.startswith("nginx")