reviewboard.certs.cert¶

Certificates, fingerprints, and bundles.

class CertDataFormat(value, names=None, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]¶

Bases: Enum

Certificate data formats.

New in version 6.0.

PEM = 'PEM'[source]¶

PEM-formatted certificate data.

class CertificateFingerprints(*, sha1: Optional[str] = None, sha256: Optional[str] = None)[source]¶

Bases: object

Representation of certificate fingerprints.

New in version 6.0.

classmethod from_json(data: SerializableJSONDictImmutable) → Self[source]¶

Return a new instance from a serialized JSON payload.

The payload is expected to be in the following format:

Keys:

• sha1 (str, optional) – The human-readable SHA1 fingerprint in AA:BB:CC... form.

• sha256 (str, optional) – The human-readable SHA256 fingerprint in AA:BB:CC... form.

Parameters:

data (dict) – The JSON dictionary containing the fingerprint information.

Returns:

The parsed fingerprints instance.

Return type:

CertificateFingerprints

classmethod from_x509_cert(x509_cert: Certificate) → Self[source]¶

Return a new instance from a Cryptography X509 certificate.

Parameters:

x509_cert (cryptography.x509.Certificate) – The Cryptography certificate used to load the fingerprints.

Returns:

The loaded fingerprints instance.

Return type:

CertificateFingerprints

__init__(*, sha1: Optional[str] = None, sha256: Optional[str] = None) → None[source]¶

Initialize the certificate fingerprints instance.

Parameters:

• sha1 (str) – The SHA1 fingerprint in AA:BB:CC... format.

• shaw256 (str) – The SHA256 fingerprint in AA:BB:CC... format.

sha1: Optional[str] = None¶

The human-readable SHA1 fingerprint.

Type:

str

sha256: Optional[str] = None¶

The human-readable SHA256 fingerprint.

Type:

str

to_json() → SerializableJSONDictImmutable[source]¶

Serialize the fingerprints to a JSON payload.

Returns:

The resulting JSON payload, containing:

Keys:

• sha1 (str, optional) – A human-readable SHA1 fingerprint in AA:BB:CC... form.

• sha256 (str, optional) – A human-readable SHA256 fingerprint in AA:BB:CC... form.

These keys will only be present if there are fingerprints available.

Return type:

dict

is_empty() → bool[source]¶

Return whether these fingerprints are empty.

Returns:

True if the fingerprints are empty (no fingerprints are stored). False if there are fingerprints available.

Return type:

bool

matches(other: CertificateFingerprints) → bool[source]¶

Return whether one set of fingerprints matches another.

This will compare any available fingerprints between two instances, returning whether there’s a match.

Parameters:

other (CertificateFingerprints) – The other instance to compare to.

Returns:

True if there is a match between two instances. False if there is not.

Return type:

bool

__eq__(other: object) → bool[source]¶

Return whether this object is equal to another.

Two objects are equal if they’re both CertificateFingerprints instances and contain the same signatures.

Parameters:

other (object) – The object to compare this to.

Returns:

True if they are equal. False if they are not.

Return type:

bool

__repr__() → str[source]¶

Return a string representation of the instance.

Returns:

The string representation.

Return type:

str

__annotations__ = {'sha1': 'Optional[str]', 'sha256': 'Optional[str]'}¶

__hash__ = None¶

class Certificate(*, hostname: str, port: int, cert_data: ~typing.Optional[bytes] = None, key_data: ~typing.Optional[bytes] = None, data_format: ~reviewboard.certs.cert.CertDataFormat = CertDataFormat.PEM, fingerprints: ~typing.Union[~typing.Literal[<UnsetSymbol.UNSET: '<UNSET>'>], ~reviewboard.certs.cert.CertificateFingerprints] = UnsetSymbol.UNSET, issuer: ~typing.Union[~typing.Literal[<UnsetSymbol.UNSET: '<UNSET>'>], str] = UnsetSymbol.UNSET, subject: ~typing.Union[~typing.Literal[<UnsetSymbol.UNSET: '<UNSET>'>], str] = UnsetSymbol.UNSET, valid_from: ~typing.Union[~typing.Literal[<UnsetSymbol.UNSET: '<UNSET>'>], ~datetime.datetime] = UnsetSymbol.UNSET, valid_through: ~typing.Union[~typing.Literal[<UnsetSymbol.UNSET: '<UNSET>'>], ~datetime.datetime] = UnsetSymbol.UNSET)[source]¶

Bases: object

A representation of a SSL/TLS certificate.

This may be an incomplete representation, with only the hostname and at least one fingerprint being required. It can be used to convey information about certificates from a server or tool, or used to provide data for storage.

Consumers should take care not to modify any certificate data after loading. While it’s possible to change the data, doing so can lead to incorrect results, as some data is computed and then cached on the instance and cannot be updated later.

New in version 6.0.

classmethod create_from_files(*, hostname: str, port: int, cert_path: str, key_path: Optional[str] = None, data_format: CertDataFormat = CertDataFormat.PEM) → Self[source]¶

Return an instance parsed from a PEM bundle file.

Parameters:

• name (str) – The descriptive name of this bundle file.

• path (str) – The path to the file.

Raises:

• reviewboard.certs.errors.CertificateNotFoundError – One or more of the certificate files was not founD.

• reviewboard.certs.errors.CertificateStorageError – There was an error loading the CA bundle. Details are in the error message.

__init__(*, hostname: str, port: int, cert_data: ~typing.Optional[bytes] = None, key_data: ~typing.Optional[bytes] = None, data_format: ~reviewboard.certs.cert.CertDataFormat = CertDataFormat.PEM, fingerprints: ~typing.Union[~typing.Literal[<UnsetSymbol.UNSET: '<UNSET>'>], ~reviewboard.certs.cert.CertificateFingerprints] = UnsetSymbol.UNSET, issuer: ~typing.Union[~typing.Literal[<UnsetSymbol.UNSET: '<UNSET>'>], str] = UnsetSymbol.UNSET, subject: ~typing.Union[~typing.Literal[<UnsetSymbol.UNSET: '<UNSET>'>], str] = UnsetSymbol.UNSET, valid_from: ~typing.Union[~typing.Literal[<UnsetSymbol.UNSET: '<UNSET>'>], ~datetime.datetime] = UnsetSymbol.UNSET, valid_through: ~typing.Union[~typing.Literal[<UnsetSymbol.UNSET: '<UNSET>'>], ~datetime.datetime] = UnsetSymbol.UNSET) → None[source]¶

Initialize the certificate.

Parameters:

• hostname (str) – The hostname that would serve this certificate.

• port (int) – The port on the host that would serve this certificate.

• cert_data (bytes) –

  The loaded certificate data.

  This must be in the format defined by data_format.

• key_data (bytes, optional) –

  The loaded private key data, if available.

  This must be in the format defined by data_format.

• data_format (CertDataFormat, optional) –

  The format used for cert_data and key_data.

  This currently only accepts PEM-encoded data.

• subject (str, optional) –

  The subject (usually the hostname) of the certificate.

  If not provided, this will be loaded from cert_data when needed (and if cert_data is provided).

• issuer (str, optional) –

  The issuer of the certificate.

  If not provided, this will be loaded from cert_data when needed (and if cert_data is provided).

• valid_from (datetime, optional) –

  The first date/time in which the certificate is valid.

  This must have a timezone associated with it.

  If not provided, this will be loaded from cert_data when needed (and if cert_data is provided).

• valid_through (datetime, optional) –

  The last date/time in which the certificate is valid.

  This must have a timezone associated with it.

  If not provided, this will be loaded from cert_data when needed (and if cert_data is provided).

• fingerprints (CertificateFingerprints, optional) –

  Fingerprints to set for the certificate.

  If not provided, this will be loaded from cert_data when needed (and if cert_data is provided).

cert_data: Optional[bytes]¶

The loaded certificate data.

This will always be available for stored certificates, but may not be available as part of error responses.

If available, it will match the format specified in data_format.

Type:

bytes

data_format: CertDataFormat¶

The format for the loaded certificate and private key data.

Type:

CertDataFormat

hostname: str¶

The hostname that would serve this certificate.

Note that this may be a wildcard domain (e.g., *.example.com).

Type:

str

key_data: Optional[bytes]¶

The loaded private key data, if available.

This will match the format specified in data_format.

Type:

bytes

port: int¶

The port on the host that would serve this certificate.

Type:

int

property fingerprints: Optional[CertificateFingerprints][source]¶

Fingerprints for the certificate.

Type:

CertificateFingerprints

x509_cert[source]¶

A Cryptography X509 Certificate representing this certificate.

This will be created from the loaded from the certificate data stored in cert_data. The created instance will be locally cached for future lookups.

If certificate data is not available, this will be None.

Type:

cryptography.x509.Certificate

property subject: Optional[str][source]¶

The subject of the certificate.

Type:

str

property issuer: Optional[str][source]¶

The issuer of the certificate.

Type:

str

property valid_from: Optional[datetime][source]¶

The date/time in which the certificate is first valid.

Type:

datetime.datetime

property valid_through: Optional[datetime][source]¶

The last date/time in which the certificate is valid.

Type:

datetime.datetime

property is_valid: bool[source]¶

Whether this certificate is still considered valid.

The certificate is valid if the current date/time is within its validity date range.

Type:

bool

property is_wildcard: bool[source]¶

Whether this is a wildcard certificate.

Wildcard certificates pertain to multiple domains (e.g., *.example.com, *a.example.com, or b*.example.com).

Type:

bool

__annotations__ = {'_fingerprints': 'Unsettable[Optional[CertificateFingerprints]]', '_issuer': 'Unsettable[Optional[str]]', '_subject': 'Unsettable[Optional[str]]', '_valid_from': 'Unsettable[Optional[datetime]]', '_valid_through': 'Unsettable[Optional[datetime]]', 'cert_data': 'Optional[bytes]', 'data_format': 'CertDataFormat', 'hostname': 'str', 'key_data': 'Optional[bytes]', 'port': 'int'}¶

to_json() → SerializableJSONDictImmutable[source]¶

Serialize the certificate to data ready to be serialized to JSON.

Returns:

The resulting JSON payload, containing:

Keys:

• fingerprints (dict) – A dictionary of fingerprints for the certificate, or None if not available.

• hostname (str) – The hostname serving the certificate.

• issuer (str) – The issuer of the certificate, or None if not available.

• port (int) – The port on the host serving the certificate.

• subject (str) – The subject of the certificate, or None if not available.

• valid_from (str) – The first date/time in which the certificate is valid, or None if not available.

  This will be in ISO8601 format.

• valid_through (str) – The last date/time in which the certificate is valid, or None if not available.

  This will be in ISO8601 format.

Return type:

dict

write_cert_file(path: str) → None[source]¶

Write the certificate data to a file.

Parameters:

path (str) – The file path where the certificate data will be written.

Raises:

reviewboard.certs.errors.CertificateStorageError – There was an error writing the file.

write_key_file(path: str) → None[source]¶

Write the private key data to a file.

Parameters:

path (str) – The file path where the private key data will be written.

Raises:

reviewboard.certs.errors.CertificateStorageError – There was an error writing the file.

__repr__() → str[source]¶

Return a string representation of the instance.

Returns:

The string representation.

Return type:

str

class CertificateBundle(*, bundle_data: bytes, data_format: CertDataFormat = CertDataFormat.PEM, name: str = 'certs')[source]¶

Bases: object

A bundle of root and intermediary certificates.

This represents a “CA bundle,” which specifies a root certificate and any necessary intermediary certificates used to validate other certificates, including those signed using an in-house certificate authority.

Consumers should take care not to modify any certificate data after loading. While it’s possible to change the data, doing so can lead to incorrect results, as some data is computed and then cached on the instance and cannot be updated later.

New in version 6.0.

__annotations__ = {'bundle_data': 'bytes', 'data_format': 'CertDataFormat', 'name': 'str'}¶

classmethod create_from_file(*, name: str, path: str) → Self[source]¶

Return an instance parsed from a PEM bundle file.

Parameters:

• name (str) –

  The name of this bundle file.

  This must be in slug format.

• path (str) – The path to the file.

Raises:

reviewboard.certs.errors.CertificateStorageError – There was an error loading the CA bundle. Details are in the error message.

__init__(*, bundle_data: bytes, data_format: CertDataFormat = CertDataFormat.PEM, name: str = 'certs') → None[source]¶

Initialize the certificate bundle.

Parameters:

• bundle_data (bytes) – The loaded data of the certificate bundle.

• data_format (CertDataFormat, optional) –

  The format used for contents.

  This currently only accepts PEM-encoded data.

• name (str, optional) – The name of the certificate bundle.

bundle_data: bytes¶

The loaded data of the certificate bundle.

Type:

bytes

data_format: CertDataFormat¶

The format for the loaded certificate and private key data.

Type:

CertDataFormat

name: str¶

The name of this bundle.

This is in slug format.

Type:

str

write_bundle_file(path: str) → None[source]¶

Write the certificate bundle data to a file.

Parameters:

path (str) – The file path where the certificate bundle data will be written.

Raises:

reviewboard.certs.errors.CertificateStorageError – There was an error writing the file.