tls_certificates¶

Manage TLS certificates using the tls-certificates interface (V1).

This is a port of tls_certificates_interface.tls_certificates v4.22.

Learn more about how to use the TLS Certificates interface library by reading the [usage documentation on Charmhub](https://charmhub.io/tls-certificates-interface/).

class Certificate( raw: str, common_name: str, expiry_time: datetime, validity_start_time: datetime, is_ca: bool = False, sans_dns: frozenset[str] | None = frozenset({}), sans_ip: frozenset[str] | None = frozenset({}), sans_oid: frozenset[str] | None = frozenset({}), email_address: str | None = None, organization: str | None = None, organizational_unit: str | None = None, country_name: str | None = None, state_or_province_name: str | None = None, locality_name: str | None = None, )¶

Bases: object

This class represents a certificate.

country_name: str | None = None¶

email_address: str | None = None¶

classmethod from_string( certificate: str, ) → Certificate¶: Create a Certificate object from a certificate.

is_ca: bool = False¶

locality_name: str | None = None¶

matches_private_key( private_key: PrivateKey, ) → bool¶

Check if this certificate matches a given private key.

Parameters:: private_key (PrivateKey) – The private key to validate against.
Returns:: True if the certificate matches the private key, False otherwise.
Return type:: bool

organization: str | None = None¶

organizational_unit: str | None = None¶

sans_dns: frozenset[str] | None = frozenset({})¶

sans_ip: frozenset[str] | None = frozenset({})¶

sans_oid: frozenset[str] | None = frozenset({})¶

state_or_province_name: str | None = None¶

raw: str¶

common_name: str¶

expiry_time: datetime¶

validity_start_time: datetime¶

class CertificateAvailableEvent( handle: Handle, certificate: Certificate, certificate_signing_request: CertificateSigningRequest, ca: Certificate, chain: list[Certificate], )¶

Bases: EventBase

Charm Event triggered when a TLS certificate is available.

chain_as_pem() → str¶: Return full certificate chain as a PEM string.

restore(snapshot: dict[str, str])¶: Restore snapshot.

snapshot() → dict[str, str]¶: Return snapshot.

class CertificateRequestAttributes( common_name: str, sans_dns: frozenset[str] | None = frozenset({}), sans_ip: frozenset[str] | None = frozenset({}), sans_oid: frozenset[str] | None = frozenset({}), email_address: str | None = None, organization: str | None = None, organizational_unit: str | None = None, country_name: str | None = None, state_or_province_name: str | None = None, locality_name: str | None = None, is_ca: bool = False, add_unique_id_to_subject_name: bool = True, )¶

Bases: object

A representation of the certificate request attributes.

This class should be used inside the requirer charm to specify the requested attributes for the certificate.

add_unique_id_to_subject_name: bool = True¶

country_name: str | None = None¶

email_address: str | None = None¶

classmethod from_csr( csr: CertificateSigningRequest, is_ca: bool, )¶: Create a CertificateRequestAttributes object from a CSR.

generate_csr( private_key: PrivateKey, ) → CertificateSigningRequest¶

Generate a CSR using private key and subject.

Parameters:: private_key (PrivateKey) – Private key
Returns:: CSR
Return type:: CertificateSigningRequest

is_ca: bool = False¶

is_valid() → bool¶: Check whether the certificate request is valid.

locality_name: str | None = None¶

organization: str | None = None¶

organizational_unit: str | None = None¶

sans_dns: frozenset[str] | None = frozenset({})¶

sans_ip: frozenset[str] | None = frozenset({})¶

sans_oid: frozenset[str] | None = frozenset({})¶

state_or_province_name: str | None = None¶

common_name: str¶

class CertificateSigningRequest( raw: str, common_name: str, sans_dns: frozenset[str] | None = None, sans_ip: frozenset[str] | None = None, sans_oid: frozenset[str] | None = None, email_address: str | None = None, organization: str | None = None, organizational_unit: str | None = None, country_name: str | None = None, state_or_province_name: str | None = None, locality_name: str | None = None, has_unique_identifier: bool = False, )¶

Bases: object

This class represents a certificate signing request.

country_name: str | None = None¶

email_address: str | None = None¶

classmethod from_string( csr: str, ) → CertificateSigningRequest¶: Create a CertificateSigningRequest object from a CSR.

get_sha256_hex() → str¶: Calculate the hash of the provided data and return the hexadecimal representation.

has_unique_identifier: bool = False¶

locality_name: str | None = None¶

matches_certificate( certificate: Certificate, ) → bool¶

Check if a CSR matches a certificate.

Parameters:: certificate (Certificate) – Certificate
Returns:: True/False depending on whether the CSR matches the certificate.
Return type:: bool

matches_private_key( key: PrivateKey, ) → bool¶

Check if a CSR matches a private key.

This function only works with RSA keys.

Parameters:: key (PrivateKey) – Private key
Returns:: True/False depending on whether the CSR matches the private key.
Return type:: bool

organization: str | None = None¶

organizational_unit: str | None = None¶

sans_dns: frozenset[str] | None = None¶

sans_ip: frozenset[str] | None = None¶

sans_oid: frozenset[str] | None = None¶

state_or_province_name: str | None = None¶

raw: str¶

common_name: str¶

class CertificatesRequirerCharmEvents( parent: Object | None = None, key: str | None = None, )¶

Bases: CharmEvents

List of events that the TLS Certificates requirer charm can leverage.

certificate_available¶

EventSource wraps an event type with a descriptor to facilitate observing and emitting.

It is generally used as:

class SomethingHappened(ops.EventBase):
    pass

class SomeObject(Object):
    something_happened = ops.EventSource(SomethingHappened)

With that, instances of that type will offer the someobj.something_happened attribute which is a BoundEvent, and may be used to emit and observe the event.

exception DataValidationError¶

Bases: TLSCertificatesError

Raised when data validation fails.

class Mode(*values)¶

Bases: Enum

Enum representing the mode of the certificate request.

UNIT (default): Request a certificate for the unit.: Each unit will manage its private key, certificate signing request and certificate.
APP: Request a certificate for the application.: Only the leader unit will manage the private key, certificate signing request and certificate.

UNIT = 1¶

APP = 2¶

class PrivateKey(raw: str)¶

Bases: object

This class represents a private key.

classmethod from_string( private_key: str, ) → PrivateKey¶: Create a PrivateKey object from a private key.

is_valid() → bool¶: Validate that the private key is PEM-formatted, RSA, and at least 2048 bits.

raw: str¶

class ProviderCertificate( relation_id: int, certificate: Certificate, certificate_signing_request: CertificateSigningRequest, ca: Certificate, chain: list[Certificate], revoked: bool | None = None, )¶

Bases: object

This class represents a certificate provided by the TLS provider.

revoked: bool | None = None¶

to_json() → str¶

Return the object as a JSON string.

Returns:: JSON representation of the object
Return type:: str

relation_id: int¶

certificate: Certificate¶

certificate_signing_request: CertificateSigningRequest¶

ca: Certificate¶

chain: list[Certificate]¶

class RequirerCertificateRequest( relation_id: int, certificate_signing_request: CertificateSigningRequest, is_ca: bool, )¶

Bases: object

This class represents a certificate signing request requested by a specific TLS requirer.

relation_id: int¶

certificate_signing_request: CertificateSigningRequest¶

is_ca: bool¶

exception TLSCertificatesError¶

Bases: Exception

Base class for custom errors raised by this library.

class TLSCertificatesProvidesV4(charm: CharmBase, relationship_name: str)¶

Bases: Object

TLS certificates provider class to be instantiated by TLS certificates providers.

get_certificate_requests( relation_id: int | None = None, ) → list[RequirerCertificateRequest]¶: Load certificate requests from the relation data.

get_issued_certificates( relation_id: int | None = None, ) → list[ProviderCertificate]¶

Return a List of issued (non revoked) certificates.

Returns:: List of ProviderCertificate objects
Return type:: List

get_outstanding_certificate_requests( relation_id: int | None = None, ) → list[RequirerCertificateRequest]¶

Return CSR’s for which no certificate has been issued.

Parameters:: relation_id (int) – Relation id
Returns:: List of RequirerCertificateRequest objects.
Return type:: list

get_provider_certificates( relation_id: int | None = None, ) → list[ProviderCertificate]¶: Return a List of issued certificates.

get_unsolicited_certificates( relation_id: int | None = None, ) → list[ProviderCertificate]¶

Return provider certificates for which no certificate requests exists.

Those certificates should be revoked.

revoke_all_certificates() → None¶

Revoke all certificates of this provider.

This method is meant to be used when the Root CA has changed.

set_relation_certificate( provider_certificate: ProviderCertificate, ) → None¶

Add certificates to relation data.

Parameters:: provider_certificate (ProviderCertificate) – ProviderCertificate object
Returns:: None

class TLSCertificatesRequiresV4( charm: CharmBase, relationship_name: str, certificate_requests: list[CertificateRequestAttributes], mode: Mode = Mode.UNIT, refresh_events: list[BoundEvent] | None = None, private_key: PrivateKey | None = None, renewal_relative_time: float = 0.9, )¶

Bases: Object

A class to manage the TLS certificates interface for a unit or app.

get_assigned_certificate( certificate_request: CertificateRequestAttributes, ) → tuple[ProviderCertificate | None, PrivateKey | None]¶: Get the certificate that was assigned to the given certificate request.

get_assigned_certificates() → tuple[list[ProviderCertificate], PrivateKey | None]¶: Get a list of certificates that were assigned to this or app.

get_csrs_from_requirer_relation_data() → list[RequirerCertificateRequest]¶: Return list of requirer’s CSRs from relation data.

get_provider_certificates() → list[ProviderCertificate]¶: Return list of certificates from the provider’s relation data.

on¶: List of events that the TLS Certificates requirer charm can leverage.

property private_key: PrivateKey | None¶: Return the private key.

regenerate_private_key() → None¶

Regenerate the private key.

Generate a new private key, remove old certificate requests and send new ones.

Raises:: TLSCertificatesError – If the private key is passed by the charm using the private_key parameter.

renew_certificate( certificate: ProviderCertificate, ) → None¶: Request the renewal of the provided certificate.

sync() → None¶

Sync TLS Certificates Relation Data.

This method allows the requirer to sync the TLS certificates relation data without waiting for the refresh events to be triggered.

calculate_relative_datetime( target_time: datetime, fraction: float, ) → datetime¶

Calculate a datetime that is a given percentage from now to a target time.

Parameters:

target_time (datetime) – The future datetime to interpolate towards.
fraction (float) – Fraction of the interval from now to target_time (0.0-1.0). 1.0 means return target_time, 0.9 means return the time after 90% of the interval has passed, and 0.0 means return now.

chain_has_valid_order(chain: list[str]) → bool¶

Check if the chain has a valid order.

Validates that each certificate in the chain is properly signed by the next certificate. The chain should be ordered from leaf to root, where each certificate is signed by the next one in the chain.

Parameters:: chain (List[str]) – List of certificates in PEM format, ordered from leaf to root
Returns:: True if the chain has a valid order, False otherwise.
Return type:: bool

generate_ca( private_key: PrivateKey, validity: timedelta, common_name: str, sans_dns: frozenset[str] | None = frozenset({}), sans_ip: frozenset[str] | None = frozenset({}), sans_oid: frozenset[str] | None = frozenset({}), organization: str | None = None, organizational_unit: str | None = None, email_address: str | None = None, country_name: str | None = None, state_or_province_name: str | None = None, locality_name: str | None = None, ) → Certificate¶

Generate a self signed CA Certificate.

Parameters:

private_key (PrivateKey) – Private key
validity (timedelta) – Certificate validity time
common_name (str) – Common Name that can be an IP or a Full Qualified Domain Name (FQDN).
sans_dns (FrozenSet[str]) – DNS Subject Alternative Names
sans_ip (FrozenSet[str]) – IP Subject Alternative Names
sans_oid (FrozenSet[str]) – OID Subject Alternative Names
organization (Optional[str]) – Organization name
organizational_unit (Optional[str]) – Organizational unit name
email_address (Optional[str]) – Email address
country_name (str) – Certificate Issuing country
state_or_province_name (str) – Certificate Issuing state or province
locality_name (str) – Certificate Issuing locality

Returns:

CA Certificate.

Return type:

Certificate

generate_certificate( csr: CertificateSigningRequest, ca: Certificate, ca_private_key: PrivateKey, validity: timedelta, is_ca: bool = False, ) → Certificate¶

Generate a TLS certificate based on a CSR.

Parameters:

csr (CertificateSigningRequest) – CSR
ca (Certificate) – CA Certificate
ca_private_key (PrivateKey) – CA private key
validity (timedelta) – Certificate validity time
is_ca (bool) – Whether the certificate is a CA certificate

Returns:

Certificate

Return type:

Certificate

generate_csr( private_key: PrivateKey, common_name: str, sans_dns: frozenset[str] | None = frozenset({}), sans_ip: frozenset[str] | None = frozenset({}), sans_oid: frozenset[str] | None = frozenset({}), organization: str | None = None, organizational_unit: str | None = None, email_address: str | None = None, country_name: str | None = None, locality_name: str | None = None, state_or_province_name: str | None = None, add_unique_id_to_subject_name: bool = True, ) → CertificateSigningRequest¶

Generate a CSR using private key and subject.

Parameters:

private_key (PrivateKey) – Private key
common_name (str) – Common name
sans_dns (FrozenSet[str]) – DNS Subject Alternative Names
sans_ip (FrozenSet[str]) – IP Subject Alternative Names
sans_oid (FrozenSet[str]) – OID Subject Alternative Names
organization (Optional[str]) – Organization name
organizational_unit (Optional[str]) – Organizational unit name
email_address (Optional[str]) – Email address
country_name (Optional[str]) – Country name
state_or_province_name (Optional[str]) – State or province name
locality_name (Optional[str]) – Locality name
add_unique_id_to_subject_name (bool) – Whether a unique ID must be added to the CSR’s subject name. Always leave to “True” when the CSR is used to request certificates using the tls-certificates relation.

Returns:

CSR

Return type:

CertificateSigningRequest

generate_private_key( key_size: int = 2048, public_exponent: int = 65537, ) → PrivateKey¶

Generate a private key with the RSA algorithm.

Parameters:

key_size (int) – Key size in bits, must be at least 2048 bits
public_exponent – Public exponent.

Returns:

Private Key

Return type:

PrivateKey