reviewboard.certs.cert¶

Certificates, fingerprints, and bundles.

SANValue¶

A value in a certificate SAN field.

New in version 8.0.

alias of Union[IPv4Address, IPv4Network, IPv6Address, IPv6Network, str]

class CertDataFormat(value, names=None, *, 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 CertPurpose(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)[source]¶

Bases: Enum

The purpose of a certificate.

New in version 8.0.

TRUST = 'trust'[source]¶

A certificate used to verify and trust a server.

CLIENT = 'client'[source]¶

A certificate used to identify the client for authentication.

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

Bases: object

Representation of certificate fingerprints.

New in version 6.0.

SHA1_FINGERPRINT_RE = re.compile('(?:[0-9A-F]{2}:){19}[0-9A-F]{2}', re.IGNORECASE)[source]¶

Regex for matching a SHA1 fingerprint.

New in version 8.0.

SHA1_RE = re.compile('[0-9A-F]{40}', re.IGNORECASE)[source]¶

Regex for matching a SHA1 string.

New in version 8.0.

SHA256_FINGERPRINT_RE = re.compile('(?:[0-9A-F]{2}:){31}[0-9A-F]{2}', re.IGNORECASE)[source]¶

Regex for matching a SHA256 fingerprint.

New in version 8.0.

SHA256_RE = re.compile('[0-9A-F]{64}', re.IGNORECASE)[source]¶

Regex for matching a SHA256 string.

New in version 8.0.

classmethod from_json(data: SerializableDjangoJSONDictImmutable) → 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_string(fingerprint: str) → Optional[Self][source]¶

Return a new instance from a single fingerprint string.

This will normalize the provided fingerprint (stripping any whitespace), determine if this is SHA-1 or SHA-256, and then return a new instance if the value is supported.

New in version 8.0.

Parameters:

fingerprint (str) – The fingerprint string in AA:BB:CC... format.

Returns:

The resulting fingerprints instance, or None if the string length doesn’t match a known algorithm.

Return type:

reviewboard.certs.cert.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: str | None = None, sha256: str | None = 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: str | None = None¶

The human-readable SHA1 fingerprint.

sha256: str | None = None¶

The human-readable SHA256 fingerprint.

to_json() → SerializableDjangoJSONDictImmutable[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

__hash__ = None¶

class Certificate(*, hostname: str, port: int, cert_data: bytes | None = None, key_data: bytes | None = None, data_format: ~reviewboard.certs.cert.CertDataFormat = CertDataFormat.PEM, purpose: ~reviewboard.certs.cert.CertPurpose = CertPurpose.TRUST, 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.

There are two types of certificates:

• Trust certificates.

  These are used to verify a remote server’s certificate during TLS. These may be root CA certificates, intermediate CA certificates, self-signed server certificates, or other certificates used as trust anchors.

  They do not include a private key.

• Client certificates.

  These are used to authenticate Review Board with a remote service during mutual TLS. This requires an associated private key.

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.

Changed in version 8.0: Added explicit support for specifying a certificate purpose.

New in version 6.0.

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

Return an instance parsed from a PEM bundle file.

Changed in version 8.0:

• Added the purpose argument.

• This may now raise ValueError if providing an invalid combination of arguments.

Parameters:

• hostname (str) – The primary hostname the certificate represents, used for lookup.

• port (int) – The port that served the certificate.

• cert_path (str) – The path to the local certificate file.

• key_path (str) – The path to the local private key.

• data_format (CertDataFormat, optional) – The format of the data stored in cert_path.

• purpose (CertPurpose, optional) –

  The purpose of the certificate.

  This sets whether the certificate should be used to trust a remote server or authenticate Review Board.

  By default, the purpose is to trust the server.

  New in version 8.0.

Raises:

• ValueError – One or more arguments were invalid. .. versionadded:: 8.0

• 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.

classmethod create_from_server(*, hostname: str, port: int) → Optional[Self][source]¶

Return a Certificate from a remote server.

This is useful when inspecting a server or preparing an error response when certificate validation fails.

New in version 7.1.

Parameters:

• hostname (str) – The hostname of the server.

• port (int) – The port of the server.

Returns:

The fetched certificate, or None if it could not be fetched.

Return type:

Certificate

__init__(*, hostname: str, port: int, cert_data: bytes | None = None, key_data: bytes | None = None, data_format: ~reviewboard.certs.cert.CertDataFormat = CertDataFormat.PEM, purpose: ~reviewboard.certs.cert.CertPurpose = CertPurpose.TRUST, 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.

Changed in version 8.0: Added the purpose argument.

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.

• purpose (CertPurpose, optional) –

  The purpose of the certificate.

  This sets whether the certificate should be used to trust a remote server or authenticate Review Board.

  By default, the purpose is to trust the server.

  New in version 8.0.

• 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).

Raises:

ValueError – One or more arguments were invalid.

cert_data: bytes | None¶

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.

data_format: CertDataFormat¶

The format for the loaded certificate and private key data.

hostname: str¶

The hostname that would serve this certificate.

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

key_data: bytes | None¶

The loaded private key data, if available.

This will match the format specified in data_format.

port: int¶

The port on the host that would serve this certificate.

purpose: CertPurpose¶

The purpose set for a certificate.

This defines whether the certificate is used for trusting a remote server or authenticating Review Board with a service.

New in version 8.0.

property fingerprints: reviewboard.certs.cert.CertificateFingerprints | None[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: str | None[source]¶

The subject of the certificate.

Type:

str

subject_alternative_names[source]¶

The Subject Alternative Names of the certificate.

This will include structured values for any DNS and IP addresses found in the Subject Alternative Names extension of the certificate, if present.

New in version 8.0.

Type:

list of SANValue – A list of supported SAN values.

property issuer: str | None[source]¶

The issuer of the certificate.

Type:

str

property valid_from: datetime.datetime | None[source]¶

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

Type:

datetime.datetime

property valid_through: datetime.datetime | None[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

matches_host(hostname_or_ip: str) → bool[source]¶

Return whether the certificate matches the provided hostname or IP.

A certificate is a match if any of the following conditions are true:

• The subject is a match for the hostname.

• The first label of a cert hostname is a wildcard and matches the first label of the hostname, and the remaining labels are a match.

• The value is an IPv4/IPv6 address and matches a SAN entry.

Hostnames are all normalized for comparison.

Partial wildcards (e.g., foo*.example.com, *bar.example.com, or foo*bar.example.com) are not supported. Most Certificate Authorities no longer support these, and major browsers (including Chrome) consider them security risks.

New in version 8.0.

Parameters:

hostname_or_ip (str) – The hostname or IP address to check.

Returns:

True if the host is matched by the certificate. False if it is not.

Return type:

bool

to_json() → SerializableDjangoJSONDictImmutable[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.

• purpose (str) – The purpose of the certificate.

  New in version 8.0.

• 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.

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.

data_format: CertDataFormat¶

The format for the loaded certificate and private key data.

name: str¶

The name of this bundle.

This is in slug format.

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.