Api reference¶
autossl.ca_manager¶
-
class
autossl.ca_manager.base.
CaManager
(ca_config, staging=True, storage_api=None, **kwargs)[source]¶ Bases:
object
-
get_signed_certificate
(ssl_blueprint=None, csr_path=None, servers_api=None)[source]¶ Get PEM encoded certificate using current Certificate Authority implementation
Parameters: - ssl_blueprint (ssl.SslBlueprint) –
- csr_path (pathlib.Path) – path to CSR file
- servers_api (list(server.base.Server)) – list of api instances to each server
Returns: PEM encoded signed certificate as bytes
Return type:
-
-
class
autossl.ca_manager.acme_v2_http01.
AcmeHttp01
(ca_config, staging=True, storage_api=None, **kwargs)[source]¶ Bases:
autossl.ca_manager.base.CaManager
-
get_signed_certificate
(ssl_blueprint=None, csr_path=None, servers_api=None)[source]¶ Get PEM encoded certificate using current Certificate Authority implementation
Parameters: - ssl_blueprint (ssl.SslBlueprint) –
- csr_path (pathlib.Path) – path to CSR file
- servers_api (list(server.base.Server)) – list of api instances to each server
Returns: PEM encoded signed certificate as bytes
Return type:
-
-
class
autossl.ca_manager.local.
LocalCa
(ca_config, staging=True, storage_api=None, ca_private_key=None, ca_certificate=None, certificate_validity_days=90, **kwargs)[source]¶ Bases:
autossl.ca_manager.base.CaManager
Class implementing a certificate authority based on a private key retrieved from CA storage
-
get_signed_certificate
(ssl_blueprint=None, csr_path=None, servers_api=None)[source]¶ Get PEM encoded certificate using current Certificate Authority implementation
Parameters: - ssl_blueprint (ssl.SslBlueprint) –
- csr_path (pathlib.Path) – path to CSR file
- servers_api (list(server.base.Server)) – list of api instances to each server
Returns: PEM encoded signed certificate as bytes
Return type:
-
autossl.server¶
-
class
autossl.server.base.
Server
(crt_name, deploy_full_chain=False, **kwargs)[source]¶ Bases:
object
-
create_acme_challenge
(token, key_authorization)[source]¶ Create token on server with specified value
Parameters: - token – challenge key
- key_authorization – challenge value
-
delete_acme_challenge
(token)[source]¶ Delete challenge created on server
Parameters: token (str) – challenge key to delete from server
-
deploy_cert
(key, cert, **kwargs)[source]¶ Deploy input certificate on server
Parameters: - key (pathlib.Path) – path to local private key
- cert (pathlib.Path) – path to local public certificate
Raises: exception.DeployCertificateError – if unexpected error occurred during deployment on server
-
get_certificate_information
()[source]¶ Retrieve certificate information from server.
Must be implemented for each type of server.
Returns: SSL certificate information Return type: autossl.ssl.SslCertificate Raises: autossl.exception.CertificateNotFound – if certificate does not exist yet on server
-
get_description
()[source]¶ Get description of this server
Returns: server description Return type: str
-
is_expired
(expiration_delay=0)[source]¶ Check for expiration of specified certificate
Parameters: expiration_delay (int) – Number of days before real expiration we consider a renewal needed Returns: True is certificate is going to expire in less than expiration_delay days Return type: bool
-
-
class
autossl.server.local.
LocalServer
(crt_name, path, acme_dir=None, **kwargs)[source]¶ Bases:
autossl.server.base.Server
-
create_acme_challenge
(token, key_authorization)[source]¶ Create token on server with specified value
Parameters: - token – challenge key
- key_authorization – challenge value
-
delete_acme_challenge
(token)[source]¶ Delete challenge created on server
Parameters: token (str) – challenge key to delete from server
-
deploy_cert
(key, cert, **kwargs)[source]¶ Deploy input certificate on server
Parameters: - key (pathlib.Path) – path to local private key
- cert (pathlib.Path) – path to local public certificate
Raises: exception.DeployCertificateError – if unexpected error occurred during deployment on server
-
get_certificate_information
()[source]¶ Retrieve certificate information from server.
Must be implemented for each type of server.
Returns: SSL certificate information Return type: autossl.ssl.SslCertificate Raises: autossl.exception.CertificateNotFound – if certificate does not exist yet on server
-
autossl.storage¶
-
class
autossl.storage.base.
Storage
(tracking_record_id=None, **kwargs)[source]¶ Bases:
object
-
retrieve_data
(name, data_type, **kwargs)[source]¶ Retrieve data from storage
Parameters: - name (str) – identifier of data to retrieve
- data_type (ssl.DataType) – type of data to retrieve
- **kwargs (dict) – optional key/value parameters from blueprint to retrieve data
Returns: requested data
Return type: Raises: exception.NotFound – when requested data are missing in storage
-
save_data
(name, data_type, content=None, local_path=None, **kwargs)[source]¶ Save specified content in storage
Parameters: - name (str) – name of the content to be stored on server side
- data_type (ssl.DataType) – type of data to save
- content (bytes) – content to be stored on server side
- local_path (pathlib.Path or str) – local path to a file to store
- **kwargs (dict) – optional key/value parameters from blueprint to save data
Either one of content or local_path must be specified but not both
-
-
class
autossl.storage.local.
LocalFileStorage
(path, tracking_record_id=None, **kwargs)[source]¶ Bases:
autossl.storage.base.Storage
-
retrieve_data
(name, **kwargs)[source]¶ Retrieve data from storage
Parameters: - name (str) – identifier of data to retrieve
- data_type (ssl.DataType) – type of data to retrieve
- **kwargs (dict) – optional key/value parameters from blueprint to retrieve data
Returns: requested data
Return type: Raises: exception.NotFound – when requested data are missing in storage
-
save_data
(name, content=None, local_path=None, **kwargs)[source]¶ Save specified content in storage
Parameters: - name (str) – name of the content to be stored on server side
- data_type (ssl.DataType) – type of data to save
- content (bytes) – content to be stored on server side
- local_path (pathlib.Path or str) – local path to a file to store
- **kwargs (dict) – optional key/value parameters from blueprint to save data
Either one of content or local_path must be specified but not both
-
-
class
autossl.storage.gitscm.
GitStorage
(git_url, folder=None, tracking_record_id=None, config_user_name=None, config_user_email=None, **kwargs)[source]¶ Bases:
autossl.storage.base.Storage
-
retrieve_data
(name, **kwargs)[source]¶ Retrieve data from storage
Parameters: - name (str) – identifier of data to retrieve
- data_type (ssl.DataType) – type of data to retrieve
- **kwargs (dict) – optional key/value parameters from blueprint to retrieve data
Returns: requested data
Return type: Raises: exception.NotFound – when requested data are missing in storage
-
save_data
(name, content=None, local_path=None, **kwargs)[source]¶ Save specified content in storage
Parameters: - name (str) – name of the content to be stored on server side
- data_type (ssl.DataType) – type of data to save
- content (bytes) – content to be stored on server side
- local_path (pathlib.Path or str) – local path to a file to store
- **kwargs (dict) – optional key/value parameters from blueprint to save data
Either one of content or local_path must be specified but not both
-
autossl.tracking¶
-
class
autossl.tracking.base.
Tracking
(ssl_blueprint_path, **kwargs)[source]¶ Bases:
object
-
close_for_failure
(message)[source]¶ Specify action is completed with a failed status
Parameters: message (str) – custom message
-
close_for_success
(message)[source]¶ Specify action is completed with a success status
Parameters: message (str) – custom message
-
create
(tracking_type, servers=None)[source]¶ Create a tracking record with details of current SSL blueprint
Parameters: - tracking_type (TrackingType) – Type of tracking. Can be used to customized tracking record content.
- servers (list) – List of servers in scope of the action. All servers from config if None specified here.
Returns: Identifier for the created record
Return type:
-
refresh
(record_id)[source]¶ Update current tracking instance with last changes from tracking record on server side
Parameters: record_id – identifier of the record to refresh
-
retrieve_data
(name=None, data_type=None, **kwargs)[source]¶ Retrieve specified data from tracking system
Parameters: - name (str) – Name of file/data to retrieve
- data_type (ssl.DataType) – type of data to retrieve
- **kwargs – generic key/value parameters
Returns: file content
Return type:
-
save_data
(name, data_type, local_path=None, content=None, **kwargs)[source]¶ Save input data in tracking system
Parameters: - name (str) – name of the file to attach to the tracking record
- data_type (ssl.DataType) – type of data to save
- local_path (pathlib.Path) – local path to file to attach to the tracking record
- content (bytes) – content of the file to attach to the tracking record
- **kwargs – generic key/value parameters
-
autossl.credential¶
-
class
autossl.credential.
CredentialType
[source]¶ Bases:
enum.Enum
list of credentials types supported
-
ApiKeyAndId
= 'api_key_and_api_id'¶
-
UserPassword
= 'user_password'¶
-
autossl.exception¶
-
exception
autossl.exception.
AutoSslException
(msg, original_exception=None)[source]¶ Bases:
Exception
Generic exception for autossl
Allow to chain exceptions keeping track of origin exception
-
exception
autossl.exception.
CertificateNotFound
(msg, original_exception=None)[source]¶ Bases:
autossl.exception.NotFound
Requested certificate not present on server
-
exception
autossl.exception.
DefinitionMismatch
(msg, original_exception=None)[source]¶ Bases:
autossl.exception.InvalidCertificate
Certificate is not matching blueprint definition
-
exception
autossl.exception.
DeployCertificateError
(msg, original_exception=None)[source]¶ Bases:
autossl.exception.AutoSslException
Unexpected error when trying to deploy new certificate
-
exception
autossl.exception.
ExpiredCertificate
(msg, original_exception=None)[source]¶ Bases:
autossl.exception.InvalidCertificate
Certificate is expiring
-
exception
autossl.exception.
InvalidCertificate
(msg, original_exception=None)[source]¶ Bases:
autossl.exception.AutoSslException
Certificate is not matching expected criteria
-
exception
autossl.exception.
InvalidTrustChain
(msg, original_exception=None)[source]¶ Bases:
autossl.exception.InvalidCertificate
Certificate is not compatible with CA certificate specified
-
exception
autossl.exception.
KeyMismatch
(msg, original_exception=None)[source]¶ Bases:
autossl.exception.InvalidCertificate
Certificate does not match private key
-
exception
autossl.exception.
NotFound
(msg, original_exception=None)[source]¶ Bases:
autossl.exception.AutoSslException
Requested data not found
-
exception
autossl.exception.
SslBlueprintInconsistency
(msg, original_exception=None)[source]¶ Bases:
autossl.exception.AutoSslException
SSL blueprint definition contains inconsistencies
autossl.manager¶
Script to check and renew automatically SSL certificates on a server
-
class
autossl.manager.
SslManager
(global_config=None, blueprint_path=None, credentials=None, staging=True)[source]¶ Bases:
object
-
deploy
(tracking_record_id=None, certificate_path=None, private_key_path=None, all_servers=False)[source]¶ Deploy certificate/key on servers
if certificate/key file are specified in input, they will be used, else they will be retrieved from configured storage.
If tracking record identifier is specified, certificate can also be retrieved from there, and this record will be used to track the change. If no tracking record specified, a new one will be created
Parameters: - tracking_record_id (str) – tracking record identifier
- certificate_path (pathlib.Path) – local path to SSL certificate file
- private_key_path (pathlib.Path) – local path to SSL certificate private key
- all_servers (bool) – if True, deploy certificate/key on all configured servers, else only out of synch servers will be updated.
-
deploy_certificate
(key_path, crt_path, servers_list)[source]¶ Deploy input SSL certificate on servers
Parameters: - key_path (pathlib.Path) – path to private key This is optional, if not provided, private key will be automatically retrieved from SecretServer
- crt_path (pathlib.Path) – path to certificate
- servers_list – list of server configuration on which to deploy the certificate.
-
get_and_check_artifacts
(tracking_record_id=None, certificate_path=None, private_key_path=None, folder=None)[source]¶ Retrieve currently stored certificate/key and check if valid for deployment
Parameters: - tracking_record_id (str or None) – tracking record identifier
- certificate_path (pathlib.Path or None) – local path to SSL certificate file. Automatically retrieved if not specified.
- private_key_path (pathlib.Path or None) – local path to SSL certificate private key. Automatically retrieved if not specified.
- folder (pathlib.Path or None) – folder where artifacts will be stored.
Returns: tuple of (certificate path, private key path)
Return type:
-
get_certificate_information
(working_directory)[source]¶ Retrieve certificate information for the blueprint.
Parameters: working_directory (pathlib.Path) – directory in which the ssl certificate will be downloaded Returns: SSL certificate information Return type: autossl.ssl.SslCertificate Raises: autossl.exception.NotFound – if certificate does not exist in storage
-
get_file
(file_type, file_identifier, output_folder, output_filename=None, api_names=None)[source]¶ Retrieve specified stored data
Parameters: - file_type (ssl.DataType) – type of data to retrieve
- file_identifier (str) – identifier of the data to retrieve
- output_folder (pathlib.Path) – which folder content will be written
- output_filename (str) – name of file to write (default: same than ‘file_identifier’ parameter)
- api_names (list) – list of api in which to search data
Returns: local file path to the retrieved content
Return type:
-
get_renewal_status
()[source]¶ Get details status of the certificate for each server from blueprint: expired, modified, missing, …
Returns: a 2-tuple with (Boolean renewal needed, Array servers to update) Return type: tuple - The checks performed are the following
- it is a new certificate
- cert is close to expiration
- cert definition has been modified (ex: new san)
- new server has been added
-
renew
(force=False)[source]¶ Request a renewal and proceed with automated renewal right after (if applicable)
Parameters: force (bool) – request renewal even if not needed
-
renew_certificate
()[source]¶ Perform automated renewal of the certificate using ACME protocol
Will interact with the CA to validate ownership of the domains using ACME protocol. In case of any error, input TR will be automatically closed as rejected and exception logged in that TR In case of success, certificate is directly attached to the TR
-
request_renewal
(force=False)[source]¶ Request renewal of the certificate for specified blueprint
it is first checking that a renewal is needed. Then it is generating a new CSR for the specified blueprint. A new tracking record is created with CSR and blueprint attached If automated renewal is supported, certificate is generated automatically with CA and attached to TR Else, TR is simply sent to ‘SSL Certificate Service’ team
Parameters: force (bool) – request renewal even if not needed Returns: True if a renewal is needed Return type: bool
-
save_file
(file_type, file_path=None, file_content=None, api_names=None)[source]¶ Save specified content wherever it is configured in blueprint
Parameters: - file_type (ssl.DataType) – type of data to save
- file_path (pathlib.Path) – path to a local file to save
- file_content (bytes) – content to save
- api_names (list) – list of api in which to save data
Raises: IOError – if none of ‘file_path’ or ‘file_content’ parameter are specified
-
autossl.ssl¶
-
class
autossl.ssl.
CertificateAuthorityConfig
(certificate_authorities, certificate_authority_key)[source]¶ Bases:
object
-
get_chain_of_trust
()[source]¶ Return list of certificate to have full chain of trust: intermediate, root :return: list of certificate starting intermediate until root certificate :rtype: list
-
get_storage_config
()[source]¶ Get configuration of CA storage api
Returns: CA storage configuration Return type: dict
-
get_supported_certificate_types
()[source]¶ Get list of certificate types currently supported by CA
Returns: list of certificate types currently supported by CA Return type: list
-
-
class
autossl.ssl.
DataType
[source]¶ Bases:
enum.Enum
list of data types supported
-
Blueprint
= 'yaml'¶
-
Certificate
= 'crt'¶
-
CertificateSigningRequest
= 'csr'¶
-
PrivateKey
= 'key'¶
-
-
class
autossl.ssl.
SslBlueprint
(yaml_path=None, global_config_path=None)[source]¶ Bases:
object
-
get_chain_of_trust
()[source]¶ Return list of certificates to have full chain of trust: intermediate, root :return: list of certificates starting intermediate until root certificate :rtype: list
-
validate
()[source]¶ Validate data extracted from blueprint
Raises: ValueError – if content of specified blueprint is not valid
-
-
class
autossl.ssl.
SslCertificate
(x509_path=None, common_name=None, sans=None, expiration=None)[source]¶ Bases:
object
-
domains
¶
-
init_from_x509
(x509_path)[source]¶ Parameters: x509_path (pathlib.Path) – path to PEM certificate
-
is_expired
(expiration_delay=0)[source]¶ Check for expiration
Parameters: expiration_delay (int) – Number of days before real expiration we consider a renewal needed Returns: True is certificate is going to expire in less than expiration_delay days Return type: bool
-
-
class
autossl.ssl.
SslCertificateConfig
(certificate_type, certificate_authority, common_name=None, sans=None, organization=None, chain_of_trust=None, exact_match=False, private_key_reuse=False, private_key_size=2048, renewal_delay=30, is_ca=False)[source]¶ Bases:
object
-
domains
¶
-
-
autossl.ssl.
check_certificate_with_key
(key_path, crt_path)[source]¶ Check whether a private key matches a certificate
For this, we compare RSAPublicNumbers from public key in certificate with the RSAPublicNumbers which makes up the RSA public key associated with this RSA private key.
Parameters: - key_path (pathlib.Path) – path to private key
- crt_path (pathlib.Path) – path to SSL certificate
Returns: True, if certificate matches private key
Return type:
-
autossl.ssl.
check_chain_of_trust
(chain_of_trust, crt_path)[source]¶ Check that input certificate matches chain of trust
Parameters: - chain_of_trust (list) – list of certificates of the chain of trust (intermediate CA, root CA)
- crt_path (pathlib.Path) – local path to certificate to verify
Raises: exception.InvalidTrustChain – if input certificate does not match chain of trust specified
-
autossl.ssl.
generate_csr
(name, common_name=None, company_name=None, street_address=None, city=None, state=None, postal_code=None, country_code=None, email_address=None, sans=None, key_content=None, key_size=2048, output_path=None, is_ca=False)[source]¶ Generate a CSR for specified parameters
if a private key is given, it will be used to generate CSR, else a new one will be created
Parameters: - name – name of file generated (without extension)
- common_name – common name
- company_name – company name
- street_address – company street address
- city – company city
- state – company state
- postal_code – company postal code
- country_code – company country
- email_address – contact email
- sans – list of SANs to be covered
- key_content (byte) – optional private key content to generate CSR
- key_size – size of private key to generate CSR, if no key in input
- output_path – local path where to generate files
- is_ca – True if the requested certificate is for a CA
Returns: tuple(key_content, csr_path) with content of private key and path to csr file
Return type:
-
autossl.ssl.
get_domains
(common_name=None, sans=None)[source]¶ Get unique list of domains for input criteria
Parameters: Returns: unique list of domains
Return type:
-
autossl.ssl.
get_domains_from_x509
(file_path, file_type)[source]¶ Retrieve the list of domains covered by specified x509 file (CSR or CRT)
Parameters: - file_path (pathlib.Path) – path to x509 file
- file_type (DataType) – type of x509 file. Supported types: [DataType.CertificateSigningRequest, DataType.Certificate]
Returns: list of domain
Return type:
-
autossl.ssl.
is_domain_list_matching
(domains_to_check, reference_domains, exact_match=False)[source]¶ Check if a list of domains are covered by another list of domains
For example, test.example.com and test2.example.com are covered by *.example.com
Parameters: - domains_to_check – list of domains to check
- reference_domains – list of reference domains to compare with
- exact_match – If True, domains_to_check and reference_domains must be the same If False, domains_to_check can be only a subset of reference_domains
Returns: True if domains_to_check are covered by reference_domains
Return type:
-
autossl.ssl.
is_domain_matching
(domain_to_check, reference_domain, exact_match=False)[source]¶ Check if a domain is matching another domain
For example, test.example.com is matching by *.example.com
Parameters: - domain_to_check – the domain to check
- reference_domain – the reference domain to compare with
- exact_match – If True, domain_to_check and reference_domain must be the same If False, domain_to_check can be only a subset of reference_domain
Returns: True if domain_to_check is matching reference_domain
Return type:
autossl.util¶
-
autossl.util.
check_http_response_ok
(response)[source]¶ Validate http response code
all codes not in 2xx will raise an exception
Parameters: response (requests.Response) – requests Http response Returns: same http response Return type: requests.Response Raises: exception.HttpCodeException – if http status code in not in 2xx
-
autossl.util.
str_to_class
(class_path)[source]¶ Dynamically import and return class type from full module and class path
Parameters: class_path (str) –
Returns: Type of the class to instantiate
Return type: Raises: - ImportError – if module does not exist
- AttributeError – if class not found in specified module