"certbot.client"
****************

Certbot client API.

certbot.client.acme_from_config_key(config, key, regr=None)

   Wrangle ACME client construction

certbot.client.determine_user_agent(config)

   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)

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

class certbot.client.DummyConfig

   Bases: "object"

   Shim for computing a sample user agent.

certbot.client.sample_user_agent()

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

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

   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:
      * **certbot.errors.Error** – In case of any client problems,
        in particular registration failure, or unaccepted Terms of
        Service.

      * **acme.errors.Error** – In case of any protocol problems.

   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, tos_cb)

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

   Parameters:
      * **client** (*acme.client.Client*) – ACME client object.

      * **config** (*IConfig*) – Client configuration.

      * **tos_cb** (*Callable*) – a callback to handle Term of
        Service agreement.

   Returns:
      Registration Resource.

   Return type:
      "acme.messages.RegistrationResource"

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

   Bases: "object"

   Certbot’s client.

   Variables:
      * **config** (*IConfig*) – Client configuration.

      * **account** (*Account*) – Account registered with
        "register".

      * **auth_handler** (*AuthHandler*) – Authorizations handler
        that will dispatch DV challenges to appropriate authenticators
        (providing "IAuthenticator" interface).

      * **auth** (*IAuthenticator*) – Prepared
        ("IAuthenticator.prepare") authenticator that can solve ACME
        challenges.

      * **installer** (*IInstaller*) – Installer.

      * **acme** (*acme.client.BackwardsCompatibleClientV2*) –
        Optional ACME client API handle. You might already have one
        from "register".

   obtain_certificate_from_csr(csr, orderr=None)

      Obtain certificate.

      Parameters:
         * **csr** (*util.CSR*) – PEM-encoded Certificate Signing
           Request. The key used to generate this CSR can be different
           than "authkey".

         * **orderr** (*acme.messages.OrderResource*) – contains
           authzrs

      Returns:
         certificate and chain as PEM byte strings

      Return type:
         tuple

   obtain_certificate(domains, old_keypath=None)

      Obtains a certificate from the ACME server.

      "register" must be called before "obtain_certificate"

      Parameters:
         **domains** (*list*) – domains to get a certificate

      Returns:
         certificate as PEM string, chain as PEM string, newly
         generated private key ("util.Key"), and DER-encoded
         Certificate Signing Request ("util.CSR").

      Return type:
         tuple

   _get_order_and_authorizations(csr_pem, best_effort)

      Request a new order and complete its authorizations.

      Parameters:
         * **csr_pem** (*str*) – A CSR in PEM format.

         * **best_effort** (*bool*) – True if failing to complete
           all authorizations should not raise an exception

      Returns:
         order resource containing its completed authorizations

      Return type:
         acme.messages.OrderResource

   obtain_and_enroll_certificate(domains, certname)

      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" of "str") – domains to request a
           certificate for

         * **certname** ("str" or "None") – requested name of
           lineage

      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.

   _choose_lineagename(domains, certname)

      Chooses a name for the new lineage.

      Parameters:
         * **domains** ("list" of "str") – domains in certificate
           request

         * **certname** ("str" or "None") – requested name of
           lineage

      Returns:
         lineage name that should be used

      Return type:
         str

   save_certificate(cert_pem, chain_pem, cert_path, chain_path, fullchain_path)

      Saves the certificate received from the ACME server.

      Parameters:
         * **cert_pem** (*str*) –

         * **chain_pem** (*str*) –

         * **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)

      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, ask_redirect=True)

      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)

      Applies an enhancement on all domains.

      Parameters:
         * **domains** (*list*) – list of ssl_vhosts (as strings)

         * **enhancement** (*str*) – name of enhancement, e.g.
           ensure- http-header

         * **options** (*str*) –

           options to enhancement, e.g. Strict-Transport-Security

           Note: When more "options" are needed, make options a
             list.

      Raises:
         **errors.PluginError** – If Enhancement is not supported, or
         if there is any other problem with the enhancement.

   _recovery_routine_with_msg(success_msg)

      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)

      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)

   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:
      * **privkey** ("certbot.util.Key") – Key associated with CSR

      * **csr** (*util.CSR*) – CSR

   Raises:
      **errors.Error** – when validation fails

certbot.client.rollback(default_installer, checkpoints, config, plugins)

   Revert configuration the specified number of checkpoints.

   Parameters:
      * **checkpoints** (*int*) – Number of checkpoints to revert.

      * **config** ("certbot.interfaces.IConfig") – Configuration.

certbot.client.view_config_changes(config, num=None)

   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)

   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)

   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
