# `letsencrypt.client`

Let’s Encrypt client API.

`letsencrypt.client.``acme_from_config_key`(config, key)

  Wrangle ACME client construction

`letsencrypt.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`

`letsencrypt.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 acction 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:

  - letsencrypt.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`

`letsencrypt.client.``perform_registration`(acme, config)

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

  Parameters:

  - config (IConfig) – Client configuration.
  - client (acme.client.Client) – ACME client object.

  Returns: | Registration Resource.
  Return type: | `acme.messages.RegistrationResource`
  Raises: | .UnexpectedUpdate –

class `letsencrypt.client.``Client`(config, account_, dv_auth, installer, acme=None)

  Bases: `object`

  ACME protocol client.

  Variables:

  - config (IConfig) – Client configuration.
  - account (Account) – Account registered with `register`.
  - auth_handler (AuthHandler) – Authorizations handler that will dispatch DV and Continuity challenges to appropriate authenticators (providing `IAuthenticator` interface).
  - dv_auth (IAuthenticator) – Prepared (`IAuthenticator.prepare`) authenticator that can solve the `constants.DV_CHALLENGES`.
  - installer (IInstaller) – Installer.
  - acme (acme.client.Client) – Optional ACME client API handle. You might already have one from `register`.

  `obtain_certificate_from_csr`(domains, csr, typ=2)

    Obtain certificate.

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

    Parameters:

    - domains (list) – Domain names.
    - csr (le_util.CSR) – DER-encoded Certificate Signing Request. The key used to generate this CSR can be different than `authkey`.

    Returns: | `CertificateResource` and certificate chain (as returned by `fetch_chain`).
    Return type: | tuple

  `obtain_certificate`(domains)

    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 (`le_util.Key`) and DER-encoded Certificate Signing Request (`le_util.CSR`).
    Return type: | tuple

  `obtain_and_enroll_certificate`(domains)

    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.

    Returns: | A new `letsencrypt.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)

    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)

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

    Enhance the configuration.

    Parameters: | domains (list) – list of domains to configure
    Variables: | config – Namespace typically produced by `argparse.ArgumentParser.parse_args()`. it must have the redirect, hsts and uir attributes.
    Raises: | .errors.Error – if no installer is specified in the client.

  `apply_enhancement`(domains, enhancement, options=None)

    Applies an enhacement 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)

    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

`letsencrypt.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 (`letsencrypt.le_util.Key`) – Key associated with CSR
  - csr (le_util.CSR) – CSR

  Raises: | .errors.Error – when validation fails

`letsencrypt.client.``rollback`(default_installer, checkpoints, config, plugins)

  Revert configuration the specified number of checkpoints.

  Parameters:

  - checkpoints (int) – Number of checkpoints to revert.
  - config (`letsencrypt.interfaces.IConfig`) – Configuration.

`letsencrypt.client.``view_config_changes`(config)

  View checkpoints and associated configuration changes.

  Note

  This assumes that the installation is using a Reverter object.

  Parameters: | config (`letsencrypt.interfaces.IConfig`) – Configuration.

`letsencrypt.client.``_save_chain`(chain_pem, chain_path)

  Saves chain_pem at a unique path based on chain_path.

  Parameters:

  - chain_pem (str) – certificate chain in PEM format
  - chain_path (str) – candidate path for the cert chain

  Returns: | absolute path to saved cert chain
  Return type: | str