TLS Certificates Interface
| Channel | Revision | Published | Runs on |
|---|---|---|---|
| latest/edge | 202 | 06 Nov 2025 | |
| latest/edge | 19 | 10 Feb 2023 |
juju deploy tls-certificates-interface --channel edge
Deploy Kubernetes operators easily with Juju, the Universal Operator Lifecycle Manager. Need a Kubernetes cluster? Install MicroK8s to create a full CNCF-certified Kubernetes system in under 60 seconds.
Platform:
charms.tls_certificates_interface.v4.tls_certificates
-
- Last updated 05 Nov 2025
- Revision Library version 4.25
Legacy Charmhub-hosted lib, deprecated in favour of charmlibs.interfaces.tls_certificates.
WARNING: This library is deprecated.
It will not receive feature updates or bugfixes.
charmlibs.interfaces.tls_certificates 1.0 is a bug-for-bug compatible migration of this library.
To migrate:
- Add 'charmlibs-interfaces-tls-certificates~=1.0' to your charm's dependencies, and remove this Charmhub-hosted library from your charm.
- You can also remove any dependencies added to your charm only because of this library.
- Replace
from charms.tls_certificates_interface.v4 import tls_certificateswithfrom charmlibs.interfaces import tls_certificates.
Read more:
- https://documentation.ubuntu.com/charmlibs
- https://pypi.org/project/charmlibs-interfaces-tls-certificates
Charm library for managing TLS certificates (V4).
This library contains the Requires and Provides classes for handling the tls-certificates interface.
Pre-requisites:
- Juju >= 3.0
- cryptography >= 43.0.0
- pydantic >= 1.0
Learn more on how-to use the TLS Certificates interface library by reading the documentation:
- https://charmhub.io/tls-certificates-interface/
class TLSCertificatesError
Description
Base class for custom errors raised by this library. None
class DataValidationError
Description
Raised when data validation fails. None
class Mode
Enum representing the mode of the certificate request.
Description
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.
class PrivateKey
Description
This class represents a private key. None
Methods
PrivateKey. __init__( self , raw , x509_object )
Initialize the PrivateKey object.
Description
If both raw and x509_object are provided, x509_object takes precedence.
PrivateKey. raw( self )
Description
Return the PEM-formatted string representation of the private key. None
PrivateKey. __str__( self )
Description
Return the private key as a string in PEM format. None
PrivateKey. from_string( cls , private_key: str )
Description
Create a PrivateKey object from a private key. None
PrivateKey. is_valid( self )
Description
Validate that the private key is PEM-formatted, RSA, and at least 2048 bits. None
PrivateKey. generate( cls , key_size: int , public_exponent: int )
Generate a new RSA private key.
Arguments
The size of the key in bits.
The public exponent of the key.
Returns
The generated private key.
PrivateKey. __eq__( self , other: object )
Description
Check if two PrivateKey objects are equal. None
class Certificate
Description
This class represents a certificate. None
Methods
Certificate. __init__( self , raw , common_name , expiry_time , validity_start_time , is_ca , sans_dns , sans_ip , sans_oid , email_address , organization , organizational_unit , country_name , state_or_province_name , locality_name , x509_object )
Initialize the Certificate object.
Description
This initializer must maintain the old interface while also allowing instantiation from an existing x509_object. It ignores all fields other than raw and x509_object, preferring x509_object.
Certificate. raw( self )
Description
Return the PEM-formatted string representation of the certificate. None
Certificate. common_name( self )
Description
Return the common name of the certificate. None
Certificate. expiry_time( self )
Description
Return the expiry time of the certificate. None
Certificate. validity_start_time( self )
Description
Return the validity start time of the certificate. None
Certificate. is_ca( self )
Description
Return whether the certificate is a CA certificate. None
Certificate. sans_dns( self )
Description
Return the DNS Subject Alternative Names of the certificate. None
Certificate. sans_ip( self )
Description
Return the IP Subject Alternative Names of the certificate. None
Certificate. sans_oid( self )
Description
Return the OID Subject Alternative Names of the certificate. None
Certificate. email_address( self )
Description
Return the email address of the certificate. None
Certificate. organization( self )
Description
Return the organization name of the certificate. None
Certificate. organizational_unit( self )
Description
Return the organizational unit name of the certificate. None
Certificate. country_name( self )
Description
Return the country name of the certificate. None
Certificate. state_or_province_name( self )
Description
Return the state or province name of the certificate. None
Certificate. locality_name( self )
Description
Return the locality name of the certificate. None
Certificate. __str__( self )
Description
Return the certificate as a string. None
Certificate. __eq__( self , other: object )
Description
Check if two Certificate objects are equal. None
Certificate. from_string( cls , certificate: str )
Description
Create a Certificate object from a certificate. None
Certificate. matches_private_key( self , private_key: PrivateKey )
Check if this certificate matches a given private key.
Arguments
The private key to validate against.
Returns
True if the certificate matches the private key, False otherwise.
Certificate. generate( cls , csr , ca , ca_private_key , validity: timedelta , is_ca: bool )
Generate a certificate from a CSR signed by the given CA and CA private key.
Arguments
The certificate signing request.
The CA certificate.
The CA private key.
The validity period of the certificate.
Whether the generated certificate is a CA certificate.
Returns
The generated certificate.
Certificate. generate_self_signed_ca( cls , attributes , private_key: PrivateKey , validity: timedelta )
Generate a self-signed CA certificate.
Arguments
The certificate request attributes.
The private key to sign the CA certificate.
The validity period of the CA certificate.
Returns
The generated CA certificate.
class CertificateSigningRequest
Description
A representation of the certificate signing request. None
Methods
CertificateSigningRequest. __init__( self , raw , common_name , sans_dns , sans_ip , sans_oid , email_address , organization , organizational_unit , country_name , state_or_province_name , locality_name , has_unique_identifier , x509_object )
Initialize the CertificateSigningRequest object.
Description
This initializer must maintain the old interface while also allowing instantiation from an existing x509_object. It ignores all fields other than raw and x509_object, preferring x509_object.
CertificateSigningRequest. common_name( self )
Description
Return the common name of the CSR. None
CertificateSigningRequest. sans_dns( self )
Description
Return the DNS Subject Alternative Names of the CSR. None
CertificateSigningRequest. sans_ip( self )
Description
Return the IP Subject Alternative Names of the CSR. None
CertificateSigningRequest. sans_oid( self )
Description
Return the OID Subject Alternative Names of the CSR. None
CertificateSigningRequest. email_address( self )
Description
Return the email address of the CSR. None
CertificateSigningRequest. organization( self )
Description
Return the organization name of the CSR. None
CertificateSigningRequest. organizational_unit( self )
Description
Return the organizational unit name of the CSR. None
CertificateSigningRequest. country_name( self )
Description
Return the country name of the CSR. None
CertificateSigningRequest. state_or_province_name( self )
Description
Return the state or province name of the CSR. None
CertificateSigningRequest. locality_name( self )
Description
Return the locality name of the CSR. None
CertificateSigningRequest. has_unique_identifier( self )
Description
Return whether the CSR has a unique identifier. None
CertificateSigningRequest. raw( self )
Description
Return the PEM-formatted string representation of the CSR. None
CertificateSigningRequest. __str__( self )
Description
Return the CSR as a string. None
CertificateSigningRequest. from_string( cls , csr: str )
Description
Create a CertificateSigningRequest object from a CSR. None
CertificateSigningRequest. from_csr( cls , csr )
Description
Create a CertificateSigningRequest object from a CSR. None
CertificateSigningRequest. __eq__( self , other: object )
Description
Check if two CertificateSigningRequest objects are equal. None
CertificateSigningRequest. matches_certificate( self , certificate: Certificate )
Check if this CSR matches a given certificate.
Arguments
The certificate to validate against.
Returns
True if the CSR matches the certificate, False otherwise.
CertificateSigningRequest. matches_private_key( self , key: PrivateKey )
Check if a CSR matches a private key.
Arguments
Private key
Returns
True/False depending on whether the CSR matches the private key.
Description
This function only works with RSA keys.
CertificateSigningRequest. get_sha256_hex( self )
Description
Calculate the hash of the provided data and return the hexadecimal representation. None
CertificateSigningRequest. sign( self , ca: Certificate , ca_private_key: PrivateKey , validity: timedelta , is_ca: bool )
Sign this CSR with the given CA and CA private key.
Arguments
The CA certificate.
The CA private key.
The validity period of the certificate.
Whether the generated certificate is a CA certificate.
Returns
The signed certificate.
CertificateSigningRequest. generate( cls , attributes , private_key: PrivateKey )
Generate a CSR using the supplied attributes and private key.
Arguments
Certificate request attributes
Private key
Returns
CSR
class CertificateRequestAttributes
Description
A representation of the certificate request attributes. None
Methods
CertificateRequestAttributes. __init__( self , common_name , sans_dns , sans_ip , sans_oid , email_address , organization , organizational_unit , country_name , state_or_province_name , locality_name , is_ca: bool , add_unique_id_to_subject_name: bool )
CertificateRequestAttributes. common_name( self )
Description
Return the common name. None
CertificateRequestAttributes. sans_dns( self )
Description
Return the DNS Subject Alternative Names. None
CertificateRequestAttributes. sans_ip( self )
Description
Return the IP Subject Alternative Names. None
CertificateRequestAttributes. sans_oid( self )
Description
Return the OID Subject Alternative Names. None
CertificateRequestAttributes. email_address( self )
Description
Return the email address. None
CertificateRequestAttributes. organization( self )
Description
Return the organization name. None
CertificateRequestAttributes. organizational_unit( self )
Description
Return the organizational unit name. None
CertificateRequestAttributes. country_name( self )
Description
Return the country name. None
CertificateRequestAttributes. state_or_province_name( self )
Description
Return the state or province name. None
CertificateRequestAttributes. locality_name( self )
Description
Return the locality name. None
CertificateRequestAttributes. is_ca( self )
Description
Return whether the certificate is a CA certificate. None
CertificateRequestAttributes. add_unique_id_to_subject_name( self )
Description
Return whether to add a unique identifier to the subject name. None
CertificateRequestAttributes. from_csr( cls , csr: CertificateSigningRequest , is_ca: bool )
Create CertificateRequestAttributes from a CertificateSigningRequest.
Arguments
The CSR to extract attributes from.
Whether a CA certificate is being requested.
Returns
The extracted attributes.
CertificateRequestAttributes. __eq__( self , other: object )
Description
Check if two CertificateRequestAttributes objects are equal. None
CertificateRequestAttributes. is_valid( self )
Validate the attributes of the certificate request.
Returns
True if the attributes are valid, False otherwise.
CertificateRequestAttributes. generate_csr( self , private_key: PrivateKey )
Generate a CSR using the current attributes and a private key.
Arguments
Private key to sign the CSR.
Returns
The generated CSR.
class ProviderCertificate
Description
This class represents a certificate provided by the TLS provider. None
Methods
ProviderCertificate. to_json( self )
Return the object as a JSON string.
Returns
JSON representation of the object
class RequirerCertificateRequest
Description
This class represents a certificate signing request requested by a specific TLS requirer. None
class CertificateAvailableEvent
Description
Charm Event triggered when a TLS certificate is available. None
Methods
CertificateAvailableEvent. __init__( self , handle: Handle , certificate: Certificate , certificate_signing_request: CertificateSigningRequest , ca: Certificate , chain )
CertificateAvailableEvent. snapshot( self )
Description
Return snapshot. None
CertificateAvailableEvent. restore( self , snapshot: dict )
Description
Restore snapshot. None
CertificateAvailableEvent. chain_as_pem( self )
Description
Return full certificate chain as a PEM string. None
def
generate_private_key(
key_size: int,
public_exponent: int
)
Generate a private key with the RSA algorithm.
Arguments
Key size in bits, must be at least 2048 bits
Public exponent.
Returns
Private Key
def
calculate_relative_datetime(
target_time: datetime,
fraction: float
)
Calculate a datetime that is a given percentage from now to a target time.
Arguments
The future datetime to interpolate towards.
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.
def chain_has_valid_order(chain)
Check if the chain has a valid order.
Arguments
List of certificates in PEM format, ordered from leaf to root
Returns
True if the chain has a valid order, False otherwise.
Description
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.
def
generate_csr(
private_key: PrivateKey,
common_name: str,
sans_dns,
sans_ip,
sans_oid,
organization,
organizational_unit,
email_address,
country_name,
locality_name,
state_or_province_name,
add_unique_id_to_subject_name: bool
)
Generate a CSR using private key and subject.
Arguments
Private key
Common name
DNS Subject Alternative Names
IP Subject Alternative Names
OID Subject Alternative Names
Organization name
Organizational unit name
Email address
Country name
State or province name
Locality name
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
def
generate_ca(
private_key: PrivateKey,
validity: timedelta,
common_name: str,
sans_dns,
sans_ip,
sans_oid,
organization,
organizational_unit,
email_address,
country_name,
state_or_province_name,
locality_name
)
Generate a self signed CA Certificate.
Arguments
Private key
Certificate validity time
Common Name that can be an IP or a Full Qualified Domain Name (FQDN).
DNS Subject Alternative Names
IP Subject Alternative Names
OID Subject Alternative Names
Organization name
Organizational unit name
Email address
Certificate Issuing country
Certificate Issuing state or province
Certificate Issuing locality
Returns
CA Certificate.
def
generate_certificate(
csr: CertificateSigningRequest,
ca: Certificate,
ca_private_key: PrivateKey,
validity: timedelta,
is_ca: bool
)
Generate a TLS certificate based on a CSR.
Arguments
CSR
CA Certificate
CA private key
Certificate validity time
Whether the certificate is a CA certificate
Returns
Certificate
class CertificatesRequirerCharmEvents
Description
List of events that the TLS Certificates requirer charm can leverage. None
class TLSCertificatesRequiresV4
Description
A class to manage the TLS certificates interface for a unit or app. None
Methods
TLSCertificatesRequiresV4. __init__( self , charm: CharmBase , relationship_name: str , certificate_requests , mode: Mode , refresh_events , private_key , renewal_relative_time: float )
Create a new instance of the TLSCertificatesRequiresV4 class.
Arguments
The charm instance to relate to.
The name of the relation that provides the certificates.
A list with the attributes of the certificate requests.
Whether to use unit or app certificates mode. Default is Mode.UNIT. In UNIT mode the requirer will place the csr in the unit relation data. Each unit will manage its private key, certificate signing request and certificate. UNIT mode is for use cases where each unit has its own identity. If you don't know which mode to use, you likely need UNIT. In APP mode the leader unit will place the csr in the app relation databag. APP mode is for use cases where the underlying application needs the certificate for example using it as an intermediate CA to sign other certificates. The certificate can only be accessed by the leader unit.
A list of events to trigger a refresh of the certificates.
The private key to use for the certificates. If provided, it will be used instead of generating a new one. If the key is not valid an exception will be raised. Using this parameter is discouraged, having to pass around private keys manually can be a security concern. Allowing the library to generate and manage the key is the more secure approach.
The time to renew the certificate relative to its expiry. Default is 0.9, meaning 90% of the validity period. The minimum value is 0.5, meaning 50% of the validity period. If an invalid value is provided, an exception will be raised.
TLSCertificatesRequiresV4. sync( self )
Sync TLS Certificates Relation Data.
Description
This method allows the requirer to sync the TLS certificates relation data without waiting for the refresh events to be triggered.
TLSCertificatesRequiresV4. renew_certificate( self , certificate: ProviderCertificate )
Description
Request the renewal of the provided certificate. None
TLSCertificatesRequiresV4. private_key( self )
Description
Return the private key. None
TLSCertificatesRequiresV4. regenerate_private_key( self )
Regenerate the private key.
Description
Generate a new private key, remove old certificate requests and send new ones.
TLSCertificatesRequiresV4. get_csrs_from_requirer_relation_data( self )
Description
Return list of requirer's CSRs from relation data. None
TLSCertificatesRequiresV4. get_provider_certificates( self )
Description
Return list of certificates from the provider's relation data. None
TLSCertificatesRequiresV4. get_assigned_certificate( self , certificate_request: CertificateRequestAttributes )
Description
Get the certificate that was assigned to the given certificate request. None
TLSCertificatesRequiresV4. get_assigned_certificates( self )
Description
Get a list of certificates that were assigned to this or app. None
class TLSCertificatesProvidesV4
Description
TLS certificates provider class to be instantiated by TLS certificates providers. None
Methods
TLSCertificatesProvidesV4. __init__( self , charm: CharmBase , relationship_name: str )
TLSCertificatesProvidesV4. get_certificate_requests( self , relation_id )
Description
Load certificate requests from the relation data. None
TLSCertificatesProvidesV4. revoke_all_certificates( self )
Revoke all certificates of this provider.
Description
This method is meant to be used when the Root CA has changed.
TLSCertificatesProvidesV4. set_relation_certificate( self , provider_certificate: ProviderCertificate )
Add certificates to relation data.
Arguments
ProviderCertificate object
Returns
None
TLSCertificatesProvidesV4. get_issued_certificates( self , relation_id )
Return a List of issued (non revoked) certificates.
Returns
List of ProviderCertificate objects
TLSCertificatesProvidesV4. get_provider_certificates( self , relation_id )
Description
Return a List of issued certificates. None
TLSCertificatesProvidesV4. get_unsolicited_certificates( self , relation_id )
Return provider certificates for which no certificate requests exists.
Description
Those certificates should be revoked.
TLSCertificatesProvidesV4. get_outstanding_certificate_requests( self , relation_id )
Return CSR's for which no certificate has been issued.
Arguments
Relation id
Returns
List of RequirerCertificateRequest objects.