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:	bytes

is_automated_renewal_supported¶

Check is current CA supports automated renewal

Returns:	True, if this CA implementation supports automated renewal
Return type:	bool

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:	bytes

is_automated_renewal_supported¶

Check is current CA supports automated renewal

Returns:	True, if this CA implementation supports automated renewal
Return type:	bool

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:	bytes

is_automated_renewal_supported¶

Check is current CA supports automated renewal

Returns:	True, if this CA implementation supports automated renewal
Return type:	bool

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

is_same(common_name=None, sans=None, exact_match=False)[source]¶

Check if current certificate deployed on server is covering all specified domains

Parameters:	common_name (str) – Common name sans (list) – list of Subject Alternate Names exact_match (bool) – if True, certificate must exactly match input domains if False, input domain will also match wilcard certificate and additional domains in certificate will be ignored
Returns:	True is certificate is already covering all domains

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

get_description()[source]¶

Get description of this server

Returns:	server description
Return type:	str

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:	bytes
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:	bytes
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:	bytes
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.storage.gitscm.git_url_with_username_password(git_url, username, password)[source]¶

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:	str

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:	bytes

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

update(message)[source]¶

Update tracking record

Parameters:	message (str) – text to add to tracking record

class autossl.tracking.base.TrackingType[source]¶

Bases: enum.Enum

list of tracking types supported.

Renewal = 'renewal'¶

Synchronize = 'synchronize'¶

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.credential.get_api_key_and_id(name, credentials=None, separator=None)[source]¶

autossl.credential.get_credentials(name, global_config, credentials, extra_parameters=None)[source]¶

Get structured form of specified credential based on its type and ready to be passed to any api

Parameters:	name (str) – name of the credential global_config (dict) – credential global configuration credentials (dict) – structured credentials dict extra_parameters (dict) – extra parameters to add to current credential
Returns:	structured credentials
Return type:	dict

autossl.credential.get_user_password(name, credentials=None, separator=None)[source]¶

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.HttpCodeException(request_exception)[source]¶: Bases: autossl.exception.AutoSslException

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:	tuple(pathlib.Path, pathlib.Path)

get_ca_manager_api()[source]¶

get_ca_storage_api()[source]¶

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:	pathlib.Path

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

get_server_api(server_parameters)[source]¶

get_storage_api()[source]¶

get_tracking_api()[source]¶

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_acme_api(staging=False)[source]¶

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

is_acme_supported()[source]¶

Check if CA supports ACME protocol

Returns:	True if CA supports ACME protocol
Return type:	bool

is_certificate_supported(cert_type)[source]¶

Check if specified certificate type is supported by CA

Parameters:	cert_type (str) – type of certificate to check (ex: DV)
Returns:	True if CA supports this certificate type
Return type:	bool

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

domains¶

Get domains covered by this blueprint

Returns:	list of domains in blueprint
Return type:	set

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

get_config(name, path=None, default=None)[source]¶

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

is_same(common_name=None, sans=None, exact_match=False)[source]¶

Check if current certificate is covering all specified domains

Parameters:	common_name (str) – Common name sans (list) – list of Subject Alternate Names exact_match (bool) – if True, certificate must exactly match input domains if False, input domain will also match wilcard certificate and additional domains in certificate will be ignored
Returns:	True is certificate is already covering all domains

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¶

set_attr_if_not_none(attr_name, value)[source]¶

Set attribute value if value is not None

Parameters:	attr_name (str) – attribute name value – attribute value

validate(ca_config)[source]¶

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:	bool

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:	tuple(bytes, pathlib.Path)

autossl.ssl.get_domains(common_name=None, sans=None)[source]¶

Get unique list of domains for input criteria

Parameters:	common_name (str or None) – Certificate common name sans (list(str) or None) – Certificate SANs List
Returns:	unique list of domains
Return type:	set(str)

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:	set

autossl.ssl.get_expiration(crt_path)[source]¶

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:	bool

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:	bool

autossl.ssl.sign(csr, ca_key, ca_cert, validity_days)[source]¶

Sign a certificate request with a key (CA)

Parameters:	csr (bytes, PEM encoded) – certificate request to sign ca_key (bytes, PEM encoded) – the signing key ca_cert (bytes, PEM encoded) – the signing certificate validity_days (int) – certificate validity duration (in days)
Returns:	the signed certificate
Return type:	bytes, PEM encoded

autossl.util¶

class autossl.util.TempDir(path=None)[source]¶: Bases: object

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:	type
Raises:	ImportError – if module does not exist AttributeError – if class not found in specified module