certbot.interfaces

Certbot client interfaces.

class certbot.interfaces.AccountStorage[source]

Bases: object

Accounts storage interface.

find_all()[source]

Find all accounts.

Returns:All found accounts.
Return type:list
load(account_id)[source]

Load an account by its id.

Raises:
  • .AccountNotFound – if account could not be found
  • .AccountStorageError – if account could not be loaded
save(account)[source]

Save account.

Raises:.AccountStorageError – if account could not be saved
interface certbot.interfaces.IPluginFactory[source]

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

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[source]

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[source]

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[source]

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.

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.

interface certbot.interfaces.IInstaller[source]

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[source]

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='OK', cancel_label='Cancel', help_label='', 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
  • cancel_label (str) – label for Cancel button
  • help_label (str) – label for Help button
  • 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_state, 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_status (bool) – If True, items are in a selected state by default.
  • 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[source]

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[source]

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.