certbot.client

Certbot client API.

certbot.client.acme_from_config_key(config, key)[source]

Wrangle ACME client construction

certbot.client.determine_user_agent(config)[source]

Set a user_agent string in the config based on the choice of plugins. (this wasn’t knowable at construction time)

Returns:the client’s User-Agent string
Return type:str
certbot.client.ua_flags(config)[source]

Turn some very important CLI flags into clues in the user agent.

class certbot.client.DummyConfig[source]

Bases: object

Shim for computing a sample user agent.

certbot.client.sample_user_agent()[source]

Document what this Certbot’s user agent string will be like.

certbot.client.register(config, account_storage, tos_cb=None)[source]

Register new account with an ACME CA.

This function takes care of generating fresh private key, registering the account, optionally accepting CA Terms of Service and finally saving the account. It should be called prior to initialization of Client, unless account has already been created.

Parameters:
  • config (IConfig) – Client configuration.
  • account_storage (AccountStorage) – Account storage where newly registered account will be saved to. Save happens only after TOS acceptance step, so any account private keys or RegistrationResource will not be persisted if tos_cb returns False.
  • tos_cb – If ACME CA requires the user to accept a Terms of Service before registering account, client action is necessary. For example, a CLI tool would prompt the user acceptance. tos_cb must be a callable that should accept RegistrationResource and return a bool: True iff the Terms of Service present in the contained Registration.terms_of_service is accepted by the client, and False otherwise. tos_cb will be called only if the client action is necessary, i.e. when terms_of_service is not None. This argument is optional, if not supplied it will default to automatic acceptance!
Raises:
Returns:

Newly registered and saved account, as well as protocol API handle (should be used in Client initialization).

Return type:

tuple of Account and acme.client.Client

certbot.client.perform_registration(acme, config)[source]

Actually register new account, trying repeatedly if there are email problems

Parameters:
Returns:

Registration Resource.

Return type:

acme.messages.RegistrationResource

class certbot.client.Client(config, account_, auth, installer, acme=None)[source]

Bases: object

Certbot’s client.

Variables:
obtain_certificate_from_csr(domains, csr, authzr=None)[source]

Obtain certificate.

Internal function with precondition that domains are consistent with identifiers present in the csr.

Parameters:
Returns:

CertificateResource and certificate chain (as returned by fetch_chain).

Return type:

tuple

obtain_certificate(domains)[source]

Obtains a certificate from the ACME server.

register must be called before obtain_certificate

Parameters:domains (list) – domains to get a certificate
Returns:CertificateResource, certificate chain (as returned by fetch_chain), and newly generated private key (util.Key) and DER-encoded Certificate Signing Request (util.CSR).
Return type:tuple
obtain_and_enroll_certificate(domains, certname)[source]

Obtain and enroll certificate.

Get a new certificate for the specified domains using the specified authenticator and installer, and then create a new renewable lineage containing it.

Parameters:
  • domains (list) – Domains to request.
  • plugins – A PluginsFactory object.
  • certname (str) – Name of new cert
Returns:

A new certbot.storage.RenewableCert instance referred to the enrolled cert lineage, False if the cert could not be obtained, or None if doing a successful dry run.

save_certificate(certr, chain_cert, cert_path, chain_path, fullchain_path)[source]

Saves the certificate received from the ACME server.

Parameters:
  • certr (acme.messages.Certificate) – ACME “certificate” resource.
  • chain_cert (list) –
  • cert_path (str) – Candidate path to a certificate.
  • chain_path (str) – Candidate path to a certificate chain.
  • fullchain_path (str) – Candidate path to a full cert chain.
Returns:

cert_path, chain_path, and fullchain_path as absolute paths to the actual files

Return type:

tuple of str

Raises:

IOError – If unable to find room to write the cert files

deploy_certificate(domains, privkey_path, cert_path, chain_path, fullchain_path)[source]

Install certificate

Parameters:
  • domains (list) – list of domains to install the certificate
  • privkey_path (str) – path to certificate private key
  • cert_path (str) – certificate file path (optional)
  • chain_path (str) – chain file path
enhance_config(domains, chain_path)[source]

Enhance the configuration.

Parameters:
  • domains (list) – list of domains to configure
  • chain_path (str or None) – chain file path
Raises:

errors.Error – if no installer is specified in the client.

apply_enhancement(domains, enhancement, options=None)[source]

Applies an enhancement on all domains.

Parameters:domains – list of ssl_vhosts

:type list of str

Parameters:enhancement – name of enhancement, e.g. ensure-http-header

:type str

Note

when more options are need make options a list.

Parameters:options – options to enhancement, e.g. Strict-Transport-Security

:type str

Raises:errors.PluginError – If Enhancement is not supported, or if there is any other problem with the enhancement.
_recovery_routine_with_msg(success_msg)[source]

Calls the installer’s recovery routine and prints success_msg

Parameters:success_msg (str) – message to show on successful recovery
_rollback_and_restart(success_msg)[source]

Rollback the most recent checkpoint and restart the webserver

Parameters:success_msg (str) – message to show on successful rollback
certbot.client.validate_key_csr(privkey, csr=None)[source]

Validate Key and CSR files.

Verifies that the client key and csr arguments are valid and correspond to one another. This does not currently check the names in the CSR due to the inability to read SANs from CSRs in python crypto libraries.

If csr is left as None, only the key will be validated.

Parameters:
Raises:

errors.Error – when validation fails

certbot.client.rollback(default_installer, checkpoints, config, plugins)[source]

Revert configuration the specified number of checkpoints.

Parameters:
certbot.client.view_config_changes(config, num=None)[source]

View checkpoints and associated configuration changes.

Note

This assumes that the installation is using a Reverter object.

Parameters:config (certbot.interfaces.IConfig) – Configuration.
certbot.client._open_pem_file(cli_arg_path, pem_path)[source]

Open a pem file.

If cli_arg_path was set by the client, open that. Otherwise, uniquify the file path.

Parameters:
  • cli_arg_path (str) – the cli arg name, e.g. cert_path
  • pem_path (str) – the pem file path to open
Returns:

a tuple of file object and its absolute file path

certbot.client._save_chain(chain_pem, chain_file)[source]

Saves chain_pem at a unique path based on chain_path.

Parameters:
  • chain_pem (str) – certificate chain in PEM format
  • chain_file (str) – chain file object