TLS Certificates Interface
- Canonical Telco
| Channel | Revision | Published | Runs on |
|---|---|---|---|
| latest/edge | 139 | 19 Dec 2024 | |
| 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 19 Dec 2024
- Revision Library version 4.5
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
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 have its own private key and certificate. APP: Request a certificate for the application. The private key and certificate will be shared by all units.
class PrivateKey
Description
This class represents a private key. None
Methods
PrivateKey. __str__( self )
Description
Return the private key as a string. None
PrivateKey. from_string( cls , private_key: str )
Description
Create a PrivateKey object from a private key. None
class Certificate
Description
This class represents a certificate. None
Methods
Certificate. __str__( self )
Description
Return the certificate as a string. 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.
class CertificateSigningRequest
Description
This class represents a certificate signing request. None
Methods
CertificateSigningRequest. __eq__( self , other: object )
Description
Check if two CertificateSigningRequest objects are equal. 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. 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. matches_certificate( self , certificate: Certificate )
Check if a CSR matches a certificate.
Arguments
Certificate
Returns
True/False depending on whether the CSR matches the certificate.
CertificateSigningRequest. get_sha256_hex( self )
Description
Calculate the hash of the provided data and return the hexadecimal representation. None
class CertificateRequestAttributes
A representation of the certificate request attributes.
Description
This class should be used inside the requirer charm to specify the requested attributes for the certificate.
Methods
CertificateRequestAttributes. is_valid( self )
Description
Check whether the certificate request is valid. None
CertificateRequestAttributes. generate_csr( self , private_key: PrivateKey )
Generate a CSR using private key and subject.
Arguments
Private key
Returns
CSR
CertificateRequestAttributes. from_csr( cls , csr: CertificateSigningRequest , is_ca: bool )
Description
Create a CertificateRequestAttributes object from a CSR. None
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 bytes
Public exponent.
Returns
Private Key
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 )
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.
A list of events to trigger a refresh of the certificates.
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.