`letsencrypt.interfaces`¶

Let’s Encrypt client interfaces.

class letsencrypt.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 letsencrypt.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={
        'letsencrypt.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 letsencrypt.interfaces.IPlugin[source]¶

Let’s Encrypt 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 letsencrypt.interfaces.IAuthenticator[source]¶

Extends: letsencrypt.interfaces.IPlugin

Generic Let’s Encrypt Authenticator.

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

get_chall_pref(domain)¶

Return list of challenge preferences.

Parameters:	domain (str) – Domain for which challenge preferences are sought.
Returns:	List 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:	list

perform(achalls)¶

Perform the given challenge.

Raises .PluginError:
Parameters:	achalls (list) – Non-empty (guaranteed) list of `AnnotatedChallenge` instances, such that it contains types found within `get_chall_pref()` only.
Returns:	List 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:	`list` of `acme.challenges.ChallengeResponse`
	If challenges cannot be performed

cleanup(achalls)¶

Revert changes and shutdown after challenges complete.

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

interface letsencrypt.interfaces.IConfig[source]¶

Let’s Encrypt 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.

rsa_key_size¶: Size of the RSA key.

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.

renewer_config_file¶: Location of renewal configuration file.

no_verify_ssl¶: Disable SSL certificate verification.

tls_sni_01_port¶: Port number to perform tls-sni-01 challenge. Boulder in testing mode defaults to 5001.

http01_port¶: Port used in the SimpleHttp challenge.

interface letsencrypt.interfaces.IInstaller[source]¶

Extends: letsencrypt.interfaces.IPlugin

Generic Let’s Encrypt Installer Interface.

Represents any server that an X509 certificate can be placed.

get_all_names()¶

Returns all names that may be authenticated.

Return type:	`list` of `str`

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

Deploy certificate.

Raises .PluginError:
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)
	when cert cannot be deployed

enhance(domain, enhancement, options=None)¶

Perform a configuration enhancement.

Raises .PluginError:
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.
	If Enhancement is not supported, or if an error occurs during the enhancement.

supported_enhancements()¶

Returns a list of supported enhancements.

Returns:	supported enhancements which should be a subset of `ENHANCEMENTS`
Return type:	`list` of `str`

get_all_certs_keys()¶

Retrieve all certs and keys set in configuration.

Returns:	tuples with form `[(cert, key, path)]`, where: `cert` - str path to certificate file `key` - str path to associated key file `path` - file path to configuration file
Return type:	list

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. If an exception is raised, it is assumed a new checkpoint was not created.

Raises .PluginError:
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)
	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 letsencrypt.interfaces.IDisplay[source]¶

Generic display.

notification(message, height, pause)¶

Displays a string message

Parameters:	message (str) – Message to display height (int) – Height of dialog box if applicable pause (bool) – Whether or not the application should pause for confirmation (if available)

menu(message, choices, ok_label='OK', cancel_label='Cancel', help_label='')¶

Displays a generic menu.

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
Returns:	tuple of (`code`, `index`) where `code` - str display exit code `index` - int index of the user’s selection

input(message)¶

Accept input from the user.

Parameters:	message (str) – message to display to the user
Returns:	tuple of (`code`, `input`) where `code` - str display exit code `input` - str of the user’s input
Return type:	tuple

yesno(message, yes_label='Yes', no_label='No')¶

Query the user with a yes/no question.

Yes and No label must begin with different letters.

Parameters:	message (str) – question for the user
Returns:	True for “Yes”, False for “No”
Return type:	bool

checklist(message, tags, default_state)¶

Allow for multiple selections from a menu.

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.

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

letsencrypt.interfaces¶

`letsencrypt.interfaces`¶