# `certbot.interfaces`

Certbot client interfaces.

class `certbot.interfaces.``AccountStorage`

  Bases: `object`

  Accounts storage interface.

  `find_all`()

    Find all accounts.

    Returns: | All found accounts.
    Return type: | list

  `load`(account_id)

    Load an account by its id.

    Raises:

    - AccountNotFound – if account could not be found
    - AccountStorageError – if account could not be loaded

  `save`(account, client)

    Save account.

    Raises: | AccountStorageError – if account could not be saved

interface `certbot.interfaces.``IPluginFactory`

  IPlugin factory.

  Objects providing this interface will be called without satisfying any entry point “extras” (extra dependencies) you might have defined for your plugin, e.g (excerpt from `setup.py` script):

      setup(
          ...
          entry_points={
              'certbot.plugins': [
                  'name=example_project.plugin[plugin_deps]',
              ],
          },
          extras_require={
              'plugin_deps': ['dep1', 'dep2'],
          }
      )

  Therefore, make sure such objects are importable and usable without extras. This is necessary, because CLI does the following operations (in order):

  > - loads an entry point,
  > - calls `inject_parser_options`,
  > - requires an entry point,
  > - creates plugin instance (`__call__`).

  `description`

    Short plugin description

  `__call__`(config, name)

    Create new `IPlugin`.

    Parameters:

    - config (IConfig) – Configuration.
    - name (str) – Unique plugin name.

  `inject_parser_options`(parser, name)

    Inject argument parser options (flags).

    1. Be nice and prepend all options and destinations with `option_namespace` and `dest_namespace`.

    2. Inject options (flags) only. Positional arguments are not allowed, as this would break the CLI.

    Parameters:

    - parser (ArgumentParser) – (Almost) top-level CLI parser.
    - name (str) – Unique plugin name.

interface `certbot.interfaces.``IPlugin`

  Certbot plugin.

  `prepare`()

    Prepare the plugin.

    Finish up any additional initialization.

    Raises:

    - PluginError – when full initialization cannot be completed.
    - MisconfigurationError – when full initialization cannot be completed. Plugin will be displayed on a list of available plugins.
    - NoInstallationError – when the necessary programs/files cannot be located. Plugin will NOT be displayed on a list of available plugins.
    - NotSupportedError – when the installation is recognized, but the version is not currently supported.

  `more_info`()

    Human-readable string to help the user.

    Should describe the steps taken and any relevant info to help the user decide which plugin to use.

    Rtype str: |

interface `certbot.interfaces.``IAuthenticator`

  Extends: `certbot.interfaces.IPlugin`

  Generic Certbot Authenticator.

  Class represents all possible tools processes that have the ability to perform challenges and attain a certificate.

  `get_chall_pref`(domain)

    Return `collections.Iterable` of challenge preferences.

    Parameters: | domain (str) – Domain for which challenge preferences are sought.
    Returns: | `collections.Iterable` of challenge types (subclasses of `acme.challenges.Challenge`) with the most preferred challenges first. If a type is not specified, it means the Authenticator cannot perform the challenge.
    Return type: | `collections.Iterable`

  `perform`(achalls)

    Perform the given challenge.

    Parameters: | achalls (list) – Non-empty (guaranteed) list of `AnnotatedChallenge` instances, such that it contains types found within `get_chall_pref()` only.

    Returns:

    `collections.Iterable` of ACME `ChallengeResponse` instances or if the `Challenge` cannot be fulfilled then:
    `None`
      Authenticator can perform challenge, but not at this time.
    `False`
      Authenticator will never be able to perform (error).

    Return type: | `collections.Iterable` of `acme.challenges.ChallengeResponse`, where responses are required to be returned in the same order as corresponding input challenges
    Raises: | PluginError – If challenges cannot be performed

  `cleanup`(achalls)

    Revert changes and shutdown after challenges complete.

    This method should be able to revert all changes made by perform, even if perform exited abnormally.

    Parameters: | achalls (list) – Non-empty (guaranteed) list of `AnnotatedChallenge` instances, a subset of those previously passed to `perform()`.
    Raises: | PluginError – if original configuration cannot be restored

interface `certbot.interfaces.``IConfig`

  Certbot user-supplied configuration.

  Warning

  The values stored in the configuration have not been filtered, stripped or sanitized.

  `server`

    ACME Directory Resource URI.

  `email`

    Email used for registration and recovery contact. (default: Ask)

  `rsa_key_size`

    Size of the RSA key.

  `must_staple`

    Adds the OCSP Must Staple extension to the certificate. Autoconfigures OCSP Stapling for supported setups (Apache version >= 2.3.3 ).

  `config_dir`

    Configuration directory.

  `work_dir`

    Working directory.

  `accounts_dir`

    Directory where all account information is stored.

  `backup_dir`

    Configuration backups directory.

  `csr_dir`

    Directory where newly generated Certificate Signing Requests (CSRs) are saved.

  `in_progress_dir`

    Directory used before a permanent checkpoint is finalized.

  `key_dir`

    Keys storage.

  `temp_checkpoint_dir`

    Temporary checkpoint directory.

  `no_verify_ssl`

    Disable verification of the ACME server’s certificate.

  `tls_sni_01_port`

    Port used during tls-sni-01 challenge. This only affects the port Certbot listens on. A conforming ACME server will still attempt to connect on port 443.

  `tls_sni_01_address`

    The address the server listens to during tls-sni-01 challenge.

  `http01_port`

    Port used in the http-01 challenge. This only affects the port Certbot listens on. A conforming ACME server will still attempt to connect on port 80.

  `http01_address`

    The address the server listens to during http-01 challenge.

  `pref_challs`

    Sorted user specified preferred challengestype strings with the most preferred challenge listed first

  `allow_subset_of_names`

    When performing domain validation, do not consider it a failure if authorizations can not be obtained for a strict subset of the requested domains. This may be useful for allowing renewals for multiple domains to succeed even if some domains no longer point at this system. This is a boolean

  `strict_permissions`

    Require that all configuration files are owned by the current user; only needed if your config is somewhere unsafe like /tmp/.This is a boolean

interface `certbot.interfaces.``IInstaller`

  Extends: `certbot.interfaces.IPlugin`

  Generic Certbot Installer Interface.

  Represents any server that an X509 certificate can be placed.

  It is assumed that `save()` is the only method that finalizes a checkpoint. This is important to ensure that checkpoints are restored in a consistent manner if requested by the user or in case of an error.

  Using `certbot.reverter.Reverter` to implement checkpoints, rollback, and recovery can dramatically simplify plugin development.

  `get_all_names`()

    Returns all names that may be authenticated.

    Return type: | `collections.Iterable` of `str`

  `deploy_cert`(domain, cert_path, key_path, chain_path, fullchain_path)

    Deploy certificate.

    Parameters:

    - domain (str) – domain to deploy certificate file
    - cert_path (str) – absolute path to the certificate file
    - key_path (str) – absolute path to the private key file
    - chain_path (str) – absolute path to the certificate chain file
    - fullchain_path (str) – absolute path to the certificate fullchain file (cert plus chain)

    Raises: | PluginError – when cert cannot be deployed

  `enhance`(domain, enhancement, options=None)

    Perform a configuration enhancement.

    Parameters:

    - domain (str) – domain for which to provide enhancement
    - enhancement (str) – An enhancement as defined in `ENHANCEMENTS`
    - options – Flexible options parameter for enhancement. Check documentation of `ENHANCEMENTS` for expected options for each enhancement.

    Raises: | PluginError – If Enhancement is not supported, or if an error occurs during the enhancement.

  `supported_enhancements`()

    Returns a `collections.Iterable` of supported enhancements.

    Returns: | supported enhancements which should be a subset of `ENHANCEMENTS`
    Return type: | `collections.Iterable` of `str`

  `save`(title=None, temporary=False)

    Saves all changes to the configuration files.

    Both title and temporary are needed because a save may be intended to be permanent, but the save is not ready to be a full checkpoint.

    It is assumed that at most one checkpoint is finalized by this method. Additionally, if an exception is raised, it is assumed a new checkpoint was not finalized.

    Parameters:

    - title (str) – The title of the save. If a title is given, the configuration will be saved as a new checkpoint and put in a timestamped directory. `title` has no effect if temporary is true.
    - temporary (bool) – Indicates whether the changes made will be quickly reversed in the future (challenges)

    Raises: | PluginError – when save is unsuccessful

  `rollback_checkpoints`(rollback=1)

    Revert `rollback` number of configuration checkpoints.

    Raises: | PluginError – when configuration cannot be fully reverted

  `recovery_routine`()

    Revert configuration to most recent finalized checkpoint.

    Remove all changes (temporary and permanent) that have not been finalized. This is useful to protect against crashes and other execution interruptions.

    Raises: | errors.PluginError – If unable to recover the configuration

  `view_config_changes`()

    Display all of the LE config changes.

    Raises: | PluginError – when config changes cannot be parsed

  `config_test`()

    Make sure the configuration is valid.

    Raises: | MisconfigurationError – when the config is not in a usable state

  `restart`()

    Restart or refresh the server content.

    Raises: | PluginError – when server cannot be restarted

interface `certbot.interfaces.``IDisplay`

  Generic display.

  `notification`(message, pause, wrap=True, force_interactive=False)

    Displays a string message

    Parameters:

    - message (str) – Message to display
    - pause (bool) – Whether or not the application should pause for confirmation (if available)
    - wrap (bool) – Whether or not the application should wrap text
    - force_interactive (bool) – True if it’s safe to prompt the user because it won’t cause any workflow regressions

  `menu`(message, choices, ok_label=None, cancel_label=None, help_label=None, default=None, cli_flag=None, force_interactive=False)

    Displays a generic menu.

    When not setting force_interactive=True, you must provide a default value.

    Parameters:

    - message (str) – message to display
    - choices (`list` of `tuple()` or `str`) – choices
    - ok_label (str) – label for OK button (UNUSED)
    - cancel_label (str) – label for Cancel button (UNUSED)
    - help_label (str) – label for Help button (UNUSED)
    - default (int) – default (non-interactive) choice from the menu
    - cli_flag (str) – to automate choice from the menu, eg “–keep”
    - force_interactive (bool) – True if it’s safe to prompt the user because it won’t cause any workflow regressions

    Returns: | tuple of (`code`, `index`) where `code` - str display exit code `index` - int index of the user’s selection
    Raises: | errors.MissingCommandlineFlag – if called in non-interactive mode without a default set

  `input`(message, default=None, cli_args=None, force_interactive=False)

    Accept input from the user.

    When not setting force_interactive=True, you must provide a default value.

    Parameters:

    - message (str) – message to display to the user
    - default (str) – default (non-interactive) response to prompt
    - force_interactive (bool) – True if it’s safe to prompt the user because it won’t cause any workflow regressions

    Returns: | tuple of (`code`, `input`) where `code` - str display exit code `input` - str of the user’s input
    Return type: | tuple
    Raises: | errors.MissingCommandlineFlag – if called in non-interactive mode without a default set

  `yesno`(message, yes_label='Yes', no_label='No', default=None, cli_args=None, force_interactive=False)

    Query the user with a yes/no question.

    Yes and No label must begin with different letters.

    When not setting force_interactive=True, you must provide a default value.

    Parameters:

    - message (str) – question for the user
    - default (str) – default (non-interactive) choice from the menu
    - cli_flag (str) – to automate choice from the menu, eg “–redirect / –no-redirect”
    - force_interactive (bool) – True if it’s safe to prompt the user because it won’t cause any workflow regressions

    Returns: | True for “Yes”, False for “No”
    Return type: | bool
    Raises: | errors.MissingCommandlineFlag – if called in non-interactive mode without a default set

  `checklist`(message, tags, default=None, cli_args=None, force_interactive=False)

    Allow for multiple selections from a menu.

    When not setting force_interactive=True, you must provide a default value.

    Parameters:

    - message (str) – message to display to the user
    - tags (list) – where each is of type `str` len(tags) > 0
    - default (str) – default (non-interactive) state of the checklist
    - cli_flag (str) – to automate choice from the menu, eg “–domains”
    - force_interactive (bool) – True if it’s safe to prompt the user because it won’t cause any workflow regressions

    Returns: | tuple of the form (code, list_tags) where `code` - int display exit code `list_tags` - list of str tags selected by the user
    Return type: | tuple
    Raises: | errors.MissingCommandlineFlag – if called in non-interactive mode without a default set

  `directory_select`(self, message, default=None, cli_flag=None, force_interactive=False)

    Display a directory selection screen.

    When not setting force_interactive=True, you must provide a default value.

    Parameters:

    - message (str) – prompt to give the user
    - default – the default value to return, if one exists, when using the NoninteractiveDisplay
    - cli_flag (str) – option used to set this value with the CLI, if one exists, to be included in error messages given by NoninteractiveDisplay
    - force_interactive (bool) – True if it’s safe to prompt the user because it won’t cause any workflow regressions

    Returns: | tuple of the form (`code`, `string`) where `code` - int display exit code `string` - input entered by the user

interface `certbot.interfaces.``IValidator`

  Configuration validator.

  `certificate`(cert, name, alt_host=None, port=443)

    Verifies the certificate presented at name is cert

    Parameters:

    - cert (OpenSSL.crypto.X509) – Expected certificate
    - name (str) – Server’s domain name
    - alt_host (bytes) – Host to connect to instead of the IP address of host
    - port (int) – Port to connect to

    Returns: | True if the certificate was verified successfully
    Return type: | bool

  `redirect`(name, port=80, headers=None)

    Verify redirect to HTTPS

    Parameters:

    - name (str) – Server’s domain name
    - port (int) – Port to connect to
    - headers (dict) – HTTP headers to include in request

    Returns: | True if redirect is successfully enabled
    Return type: | bool

  `hsts`(name)

    Verify HSTS header is enabled

    Parameters: | name (str) – Server’s domain name
    Returns: | True if HSTS header is successfully enabled
    Return type: | bool

  `ocsp_stapling`(name)

    Verify ocsp stapling for domain

    Parameters: | name (str) – Server’s domain name
    Returns: | True if ocsp stapling is successfully enabled
    Return type: | bool

interface `certbot.interfaces.``IReporter`

  Interface to collect and display information to the user.

  `HIGH_PRIORITY`

    Used to denote high priority messages

  `MEDIUM_PRIORITY`

    Used to denote medium priority messages

  `LOW_PRIORITY`

    Used to denote low priority messages

  `add_message`(self, msg, priority, on_crash=True)

    Adds msg to the list of messages to be printed.

    Parameters:

    - msg (str) – Message to be displayed to the user.
    - priority (int) – One of HIGH_PRIORITY, MEDIUM_PRIORITY, or LOW_PRIORITY.
    - on_crash (bool) – Whether or not the message should be printed if the program exits abnormally.

  `print_messages`(self)

    Prints messages to the user and clears the message queue.