<!DOCTYPE html>
<!--[if IE 8]><html class="no-js lt-ie9" lang="en" > <![endif]-->
<!--[if gt IE 8]><!--> <html class="no-js" lang="en" > <!--<![endif]-->
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>certbot.interfaces — Certbot 0.14.2 documentation</title>
<link rel="stylesheet" href="../../_static/css/theme.css" type="text/css" />
<link rel="index" title="Index"
href="../../genindex.html"/>
<link rel="search" title="Search" href="../../search.html"/>
<link rel="top" title="Certbot 0.14.2 documentation" href="../../index.html"/>
<link rel="up" title="Module code" href="../index.html"/>
<script src="../../_static/js/modernizr.min.js"></script>
</head>
<body class="wy-body-for-nav" role="document">
<div class="wy-grid-for-nav">
<nav data-toggle="wy-nav-shift" class="wy-nav-side">
<div class="wy-side-scroll">
<div class="wy-side-nav-search">
<a href="../../index.html" class="icon icon-home"> Certbot
</a>
<div class="version">
0.14
</div>
<div role="search">
<form id="rtd-search-form" class="wy-form" action="../../search.html" method="get">
<input type="text" name="q" placeholder="Search docs" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div>
<div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="main navigation">
<ul>
<li class="toctree-l1"><a class="reference internal" href="../../intro.html">Introduction</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../install.html">Get Certbot</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../using.html">User Guide</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../contributing.html">Developer Guide</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../packaging.html">Packaging Guide</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../resources.html">Resources</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../../api.html">API Documentation</a></li>
</ul>
</div>
</div>
</nav>
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap">
<nav class="wy-nav-top" role="navigation" aria-label="top navigation">
<i data-toggle="wy-nav-top" class="fa fa-bars"></i>
<a href="../../index.html">Certbot</a>
</nav>
<div class="wy-nav-content">
<div class="rst-content">
<div role="navigation" aria-label="breadcrumbs navigation">
<ul class="wy-breadcrumbs">
<li><a href="../../index.html">Docs</a> »</li>
<li><a href="../index.html">Module code</a> »</li>
<li>certbot.interfaces</li>
<li class="wy-breadcrumbs-aside">
</li>
</ul>
<hr/>
</div>
<div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
<div itemprop="articleBody">
<h1>Source code for certbot.interfaces</h1><div class="highlight"><pre>
<span></span><span class="sd">"""Certbot client interfaces."""</span>
<span class="kn">import</span> <span class="nn">abc</span>
<span class="kn">import</span> <span class="nn">zope.interface</span>
<span class="c1"># pylint: disable=no-self-argument,no-method-argument,no-init,inherit-non-class</span>
<span class="c1"># pylint: disable=too-few-public-methods</span>
<div class="viewcode-block" id="AccountStorage"><a class="viewcode-back" href="../../api/interfaces.html#certbot.interfaces.AccountStorage">[docs]</a><span class="k">class</span> <span class="nc">AccountStorage</span><span class="p">(</span><span class="nb">object</span><span class="p">):</span>
<span class="sd">"""Accounts storage interface."""</span>
<span class="n">__metaclass__</span> <span class="o">=</span> <span class="n">abc</span><span class="o">.</span><span class="n">ABCMeta</span>
<span class="nd">@abc</span><span class="o">.</span><span class="n">abstractmethod</span>
<div class="viewcode-block" id="AccountStorage.find_all"><a class="viewcode-back" href="../../api/interfaces.html#certbot.interfaces.AccountStorage.find_all">[docs]</a> <span class="k">def</span> <span class="nf">find_all</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span> <span class="c1"># pragma: no cover</span>
<span class="sd">"""Find all accounts.</span>
<span class="sd"> :returns: All found accounts.</span>
<span class="sd"> :rtype: list</span>
<span class="sd"> """</span>
<span class="k">raise</span> <span class="ne">NotImplementedError</span><span class="p">()</span></div>
<span class="nd">@abc</span><span class="o">.</span><span class="n">abstractmethod</span>
<div class="viewcode-block" id="AccountStorage.load"><a class="viewcode-back" href="../../api/interfaces.html#certbot.interfaces.AccountStorage.load">[docs]</a> <span class="k">def</span> <span class="nf">load</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">account_id</span><span class="p">):</span> <span class="c1"># pragma: no cover</span>
<span class="sd">"""Load an account by its id.</span>
<span class="sd"> :raises .AccountNotFound: if account could not be found</span>
<span class="sd"> :raises .AccountStorageError: if account could not be loaded</span>
<span class="sd"> """</span>
<span class="k">raise</span> <span class="ne">NotImplementedError</span><span class="p">()</span></div>
<span class="nd">@abc</span><span class="o">.</span><span class="n">abstractmethod</span>
<div class="viewcode-block" id="AccountStorage.save"><a class="viewcode-back" href="../../api/interfaces.html#certbot.interfaces.AccountStorage.save">[docs]</a> <span class="k">def</span> <span class="nf">save</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">account</span><span class="p">,</span> <span class="n">client</span><span class="p">):</span> <span class="c1"># pragma: no cover</span>
<span class="sd">"""Save account.</span>
<span class="sd"> :raises .AccountStorageError: if account could not be saved</span>
<span class="sd"> """</span>
<span class="k">raise</span> <span class="ne">NotImplementedError</span><span class="p">()</span></div></div>
<div class="viewcode-block" id="IPluginFactory"><a class="viewcode-back" href="../../api/interfaces.html#certbot.interfaces.IPluginFactory">[docs]</a><span class="k">class</span> <span class="nc">IPluginFactory</span><span class="p">(</span><span class="n">zope</span><span class="o">.</span><span class="n">interface</span><span class="o">.</span><span class="n">Interface</span><span class="p">):</span>
<span class="sd">"""IPlugin factory.</span>
<span class="sd"> Objects providing this interface will be called without satisfying</span>
<span class="sd"> any entry point "extras" (extra dependencies) you might have defined</span>
<span class="sd"> for your plugin, e.g (excerpt from ``setup.py`` script)::</span>
<span class="sd"> setup(</span>
<span class="sd"> ...</span>
<span class="sd"> entry_points={</span>
<span class="sd"> 'certbot.plugins': [</span>
<span class="sd"> 'name=example_project.plugin[plugin_deps]',</span>
<span class="sd"> ],</span>
<span class="sd"> },</span>
<span class="sd"> extras_require={</span>
<span class="sd"> 'plugin_deps': ['dep1', 'dep2'],</span>
<span class="sd"> }</span>
<span class="sd"> )</span>
<span class="sd"> Therefore, make sure such objects are importable and usable without</span>
<span class="sd"> extras. This is necessary, because CLI does the following operations</span>
<span class="sd"> (in order):</span>
<span class="sd"> - loads an entry point,</span>
<span class="sd"> - calls `inject_parser_options`,</span>
<span class="sd"> - requires an entry point,</span>
<span class="sd"> - creates plugin instance (`__call__`).</span>
<span class="sd"> """</span>
<span class="n">description</span> <span class="o">=</span> <span class="n">zope</span><span class="o">.</span><span class="n">interface</span><span class="o">.</span><span class="n">Attribute</span><span class="p">(</span><span class="s2">"Short plugin description"</span><span class="p">)</span>
<span class="k">def</span> <span class="nf">__call__</span><span class="p">(</span><span class="n">config</span><span class="p">,</span> <span class="n">name</span><span class="p">):</span>
<span class="sd">"""Create new `IPlugin`.</span>
<span class="sd"> :param IConfig config: Configuration.</span>
<span class="sd"> :param str name: Unique plugin name.</span>
<span class="sd"> """</span>
<span class="k">def</span> <span class="nf">inject_parser_options</span><span class="p">(</span><span class="n">parser</span><span class="p">,</span> <span class="n">name</span><span class="p">):</span>
<span class="sd">"""Inject argument parser options (flags).</span>
<span class="sd"> 1. Be nice and prepend all options and destinations with</span>
<span class="sd"> `~.common.option_namespace` and `~common.dest_namespace`.</span>
<span class="sd"> 2. Inject options (flags) only. Positional arguments are not</span>
<span class="sd"> allowed, as this would break the CLI.</span>
<span class="sd"> :param ArgumentParser parser: (Almost) top-level CLI parser.</span>
<span class="sd"> :param str name: Unique plugin name.</span>
<span class="sd"> """</span></div>
<div class="viewcode-block" id="IPlugin"><a class="viewcode-back" href="../../api/interfaces.html#certbot.interfaces.IPlugin">[docs]</a><span class="k">class</span> <span class="nc">IPlugin</span><span class="p">(</span><span class="n">zope</span><span class="o">.</span><span class="n">interface</span><span class="o">.</span><span class="n">Interface</span><span class="p">):</span>
<span class="sd">"""Certbot plugin."""</span>
<span class="k">def</span> <span class="nf">prepare</span><span class="p">():</span> <span class="c1"># type: ignore</span>
<span class="sd">"""Prepare the plugin.</span>
<span class="sd"> Finish up any additional initialization.</span>
<span class="sd"> :raises .PluginError:</span>
<span class="sd"> when full initialization cannot be completed.</span>
<span class="sd"> :raises .MisconfigurationError:</span>
<span class="sd"> when full initialization cannot be completed. Plugin will</span>
<span class="sd"> be displayed on a list of available plugins.</span>
<span class="sd"> :raises .NoInstallationError:</span>
<span class="sd"> when the necessary programs/files cannot be located. Plugin</span>
<span class="sd"> will NOT be displayed on a list of available plugins.</span>
<span class="sd"> :raises .NotSupportedError:</span>
<span class="sd"> when the installation is recognized, but the version is not</span>
<span class="sd"> currently supported.</span>
<span class="sd"> """</span>
<span class="k">def</span> <span class="nf">more_info</span><span class="p">():</span> <span class="c1"># type: ignore</span>
<span class="sd">"""Human-readable string to help the user.</span>
<span class="sd"> Should describe the steps taken and any relevant info to help the user</span>
<span class="sd"> decide which plugin to use.</span>
<span class="sd"> :rtype str:</span>
<span class="sd"> """</span></div>
<div class="viewcode-block" id="IAuthenticator"><a class="viewcode-back" href="../../api/interfaces.html#certbot.interfaces.IAuthenticator">[docs]</a><span class="k">class</span> <span class="nc">IAuthenticator</span><span class="p">(</span><span class="n">IPlugin</span><span class="p">):</span>
<span class="sd">"""Generic Certbot Authenticator.</span>
<span class="sd"> Class represents all possible tools processes that have the</span>
<span class="sd"> ability to perform challenges and attain a certificate.</span>
<span class="sd"> """</span>
<span class="k">def</span> <span class="nf">get_chall_pref</span><span class="p">(</span><span class="n">domain</span><span class="p">):</span>
<span class="sd">"""Return `collections.Iterable` of challenge preferences.</span>
<span class="sd"> :param str domain: Domain for which challenge preferences are sought.</span>
<span class="sd"> :returns: `collections.Iterable` of challenge types (subclasses of</span>
<span class="sd"> :class:`acme.challenges.Challenge`) with the most</span>
<span class="sd"> preferred challenges first. If a type is not specified, it means the</span>
<span class="sd"> Authenticator cannot perform the challenge.</span>
<span class="sd"> :rtype: `collections.Iterable`</span>
<span class="sd"> """</span>
<span class="k">def</span> <span class="nf">perform</span><span class="p">(</span><span class="n">achalls</span><span class="p">):</span>
<span class="sd">"""Perform the given challenge.</span>
<span class="sd"> :param list achalls: Non-empty (guaranteed) list of</span>
<span class="sd"> :class:`~certbot.achallenges.AnnotatedChallenge`</span>
<span class="sd"> instances, such that it contains types found within</span>
<span class="sd"> :func:`get_chall_pref` only.</span>
<span class="sd"> :returns: `collections.Iterable` of ACME</span>
<span class="sd"> :class:`~acme.challenges.ChallengeResponse` instances</span>
<span class="sd"> or if the :class:`~acme.challenges.Challenge` cannot</span>
<span class="sd"> be fulfilled then:</span>
<span class="sd"> ``None``</span>
<span class="sd"> Authenticator can perform challenge, but not at this time.</span>
<span class="sd"> ``False``</span>
<span class="sd"> Authenticator will never be able to perform (error).</span>
<span class="sd"> :rtype: :class:`collections.Iterable` of</span>
<span class="sd"> :class:`acme.challenges.ChallengeResponse`,</span>
<span class="sd"> where responses are required to be returned in</span>
<span class="sd"> the same order as corresponding input challenges</span>
<span class="sd"> :raises .PluginError: If challenges cannot be performed</span>
<span class="sd"> """</span>
<span class="k">def</span> <span class="nf">cleanup</span><span class="p">(</span><span class="n">achalls</span><span class="p">):</span>
<span class="sd">"""Revert changes and shutdown after challenges complete.</span>
<span class="sd"> This method should be able to revert all changes made by</span>
<span class="sd"> perform, even if perform exited abnormally.</span>
<span class="sd"> :param list achalls: Non-empty (guaranteed) list of</span>
<span class="sd"> :class:`~certbot.achallenges.AnnotatedChallenge`</span>
<span class="sd"> instances, a subset of those previously passed to :func:`perform`.</span>
<span class="sd"> :raises PluginError: if original configuration cannot be restored</span>
<span class="sd"> """</span></div>
<div class="viewcode-block" id="IConfig"><a class="viewcode-back" href="../../api/interfaces.html#certbot.interfaces.IConfig">[docs]</a><span class="k">class</span> <span class="nc">IConfig</span><span class="p">(</span><span class="n">zope</span><span class="o">.</span><span class="n">interface</span><span class="o">.</span><span class="n">Interface</span><span class="p">):</span>
<span class="sd">"""Certbot user-supplied configuration.</span>
<span class="sd"> .. warning:: The values stored in the configuration have not been</span>
<span class="sd"> filtered, stripped or sanitized.</span>
<span class="sd"> """</span>
<span class="n">server</span> <span class="o">=</span> <span class="n">zope</span><span class="o">.</span><span class="n">interface</span><span class="o">.</span><span class="n">Attribute</span><span class="p">(</span><span class="s2">"ACME Directory Resource URI."</span><span class="p">)</span>
<span class="n">email</span> <span class="o">=</span> <span class="n">zope</span><span class="o">.</span><span class="n">interface</span><span class="o">.</span><span class="n">Attribute</span><span class="p">(</span>
<span class="s2">"Email used for registration and recovery contact. (default: Ask)"</span><span class="p">)</span>
<span class="n">rsa_key_size</span> <span class="o">=</span> <span class="n">zope</span><span class="o">.</span><span class="n">interface</span><span class="o">.</span><span class="n">Attribute</span><span class="p">(</span><span class="s2">"Size of the RSA key."</span><span class="p">)</span>
<span class="n">must_staple</span> <span class="o">=</span> <span class="n">zope</span><span class="o">.</span><span class="n">interface</span><span class="o">.</span><span class="n">Attribute</span><span class="p">(</span>
<span class="s2">"Adds the OCSP Must Staple extension to the certificate. "</span>
<span class="s2">"Autoconfigures OCSP Stapling for supported setups "</span>
<span class="s2">"(Apache version >= 2.3.3 )."</span><span class="p">)</span>
<span class="n">config_dir</span> <span class="o">=</span> <span class="n">zope</span><span class="o">.</span><span class="n">interface</span><span class="o">.</span><span class="n">Attribute</span><span class="p">(</span><span class="s2">"Configuration directory."</span><span class="p">)</span>
<span class="n">work_dir</span> <span class="o">=</span> <span class="n">zope</span><span class="o">.</span><span class="n">interface</span><span class="o">.</span><span class="n">Attribute</span><span class="p">(</span><span class="s2">"Working directory."</span><span class="p">)</span>
<span class="n">accounts_dir</span> <span class="o">=</span> <span class="n">zope</span><span class="o">.</span><span class="n">interface</span><span class="o">.</span><span class="n">Attribute</span><span class="p">(</span>
<span class="s2">"Directory where all account information is stored."</span><span class="p">)</span>
<span class="n">backup_dir</span> <span class="o">=</span> <span class="n">zope</span><span class="o">.</span><span class="n">interface</span><span class="o">.</span><span class="n">Attribute</span><span class="p">(</span><span class="s2">"Configuration backups directory."</span><span class="p">)</span>
<span class="n">csr_dir</span> <span class="o">=</span> <span class="n">zope</span><span class="o">.</span><span class="n">interface</span><span class="o">.</span><span class="n">Attribute</span><span class="p">(</span>
<span class="s2">"Directory where newly generated Certificate Signing Requests "</span>
<span class="s2">"(CSRs) are saved."</span><span class="p">)</span>
<span class="n">in_progress_dir</span> <span class="o">=</span> <span class="n">zope</span><span class="o">.</span><span class="n">interface</span><span class="o">.</span><span class="n">Attribute</span><span class="p">(</span>
<span class="s2">"Directory used before a permanent checkpoint is finalized."</span><span class="p">)</span>
<span class="n">key_dir</span> <span class="o">=</span> <span class="n">zope</span><span class="o">.</span><span class="n">interface</span><span class="o">.</span><span class="n">Attribute</span><span class="p">(</span><span class="s2">"Keys storage."</span><span class="p">)</span>
<span class="n">temp_checkpoint_dir</span> <span class="o">=</span> <span class="n">zope</span><span class="o">.</span><span class="n">interface</span><span class="o">.</span><span class="n">Attribute</span><span class="p">(</span>
<span class="s2">"Temporary checkpoint directory."</span><span class="p">)</span>
<span class="n">no_verify_ssl</span> <span class="o">=</span> <span class="n">zope</span><span class="o">.</span><span class="n">interface</span><span class="o">.</span><span class="n">Attribute</span><span class="p">(</span>
<span class="s2">"Disable verification of the ACME server's certificate."</span><span class="p">)</span>
<span class="n">tls_sni_01_port</span> <span class="o">=</span> <span class="n">zope</span><span class="o">.</span><span class="n">interface</span><span class="o">.</span><span class="n">Attribute</span><span class="p">(</span>
<span class="s2">"Port used during tls-sni-01 challenge. "</span>
<span class="s2">"This only affects the port Certbot listens on. "</span>
<span class="s2">"A conforming ACME server will still attempt to connect on port 443."</span><span class="p">)</span>
<span class="n">http01_port</span> <span class="o">=</span> <span class="n">zope</span><span class="o">.</span><span class="n">interface</span><span class="o">.</span><span class="n">Attribute</span><span class="p">(</span>
<span class="s2">"Port used in the http-01 challenge. "</span>
<span class="s2">"This only affects the port Certbot listens on. "</span>
<span class="s2">"A conforming ACME server will still attempt to connect on port 80."</span><span class="p">)</span>
<span class="n">pref_challs</span> <span class="o">=</span> <span class="n">zope</span><span class="o">.</span><span class="n">interface</span><span class="o">.</span><span class="n">Attribute</span><span class="p">(</span>
<span class="s2">"Sorted user specified preferred challenges"</span>
<span class="s2">"type strings with the most preferred challenge listed first"</span><span class="p">)</span>
<span class="n">allow_subset_of_names</span> <span class="o">=</span> <span class="n">zope</span><span class="o">.</span><span class="n">interface</span><span class="o">.</span><span class="n">Attribute</span><span class="p">(</span>
<span class="s2">"When performing domain validation, do not consider it a failure "</span>
<span class="s2">"if authorizations can not be obtained for a strict subset of "</span>
<span class="s2">"the requested domains. This may be useful for allowing renewals for "</span>
<span class="s2">"multiple domains to succeed even if some domains no longer point "</span>
<span class="s2">"at this system. This is a boolean"</span><span class="p">)</span>
<span class="n">strict_permissions</span> <span class="o">=</span> <span class="n">zope</span><span class="o">.</span><span class="n">interface</span><span class="o">.</span><span class="n">Attribute</span><span class="p">(</span>
<span class="s2">"Require that all configuration files are owned by the current "</span>
<span class="s2">"user; only needed if your config is somewhere unsafe like /tmp/."</span>
<span class="s2">"This is a boolean"</span><span class="p">)</span></div>
<div class="viewcode-block" id="IInstaller"><a class="viewcode-back" href="../../api/interfaces.html#certbot.interfaces.IInstaller">[docs]</a><span class="k">class</span> <span class="nc">IInstaller</span><span class="p">(</span><span class="n">IPlugin</span><span class="p">):</span>
<span class="sd">"""Generic Certbot Installer Interface.</span>
<span class="sd"> Represents any server that an X509 certificate can be placed.</span>
<span class="sd"> It is assumed that :func:`save` is the only method that finalizes a</span>
<span class="sd"> checkpoint. This is important to ensure that checkpoints are</span>
<span class="sd"> restored in a consistent manner if requested by the user or in case</span>
<span class="sd"> of an error.</span>
<span class="sd"> Using :class:`certbot.reverter.Reverter` to implement checkpoints,</span>
<span class="sd"> rollback, and recovery can dramatically simplify plugin development.</span>
<span class="sd"> """</span>
<span class="k">def</span> <span class="nf">get_all_names</span><span class="p">():</span> <span class="c1"># type: ignore</span>
<span class="sd">"""Returns all names that may be authenticated.</span>
<span class="sd"> :rtype: `collections.Iterable` of `str`</span>
<span class="sd"> """</span>
<span class="k">def</span> <span class="nf">deploy_cert</span><span class="p">(</span><span class="n">domain</span><span class="p">,</span> <span class="n">cert_path</span><span class="p">,</span> <span class="n">key_path</span><span class="p">,</span> <span class="n">chain_path</span><span class="p">,</span> <span class="n">fullchain_path</span><span class="p">):</span>
<span class="sd">"""Deploy certificate.</span>
<span class="sd"> :param str domain: domain to deploy certificate file</span>
<span class="sd"> :param str cert_path: absolute path to the certificate file</span>
<span class="sd"> :param str key_path: absolute path to the private key file</span>
<span class="sd"> :param str chain_path: absolute path to the certificate chain file</span>
<span class="sd"> :param str fullchain_path: absolute path to the certificate fullchain</span>
<span class="sd"> file (cert plus chain)</span>
<span class="sd"> :raises .PluginError: when cert cannot be deployed</span>
<span class="sd"> """</span>
<span class="k">def</span> <span class="nf">enhance</span><span class="p">(</span><span class="n">domain</span><span class="p">,</span> <span class="n">enhancement</span><span class="p">,</span> <span class="n">options</span><span class="o">=</span><span class="kc">None</span><span class="p">):</span>
<span class="sd">"""Perform a configuration enhancement.</span>
<span class="sd"> :param str domain: domain for which to provide enhancement</span>
<span class="sd"> :param str enhancement: An enhancement as defined in</span>
<span class="sd"> :const:`~certbot.constants.ENHANCEMENTS`</span>
<span class="sd"> :param options: Flexible options parameter for enhancement.</span>
<span class="sd"> Check documentation of</span>
<span class="sd"> :const:`~certbot.constants.ENHANCEMENTS`</span>
<span class="sd"> for expected options for each enhancement.</span>
<span class="sd"> :raises .PluginError: If Enhancement is not supported, or if</span>
<span class="sd"> an error occurs during the enhancement.</span>
<span class="sd"> """</span>
<span class="k">def</span> <span class="nf">supported_enhancements</span><span class="p">():</span> <span class="c1"># type: ignore</span>
<span class="sd">"""Returns a `collections.Iterable` of supported enhancements.</span>
<span class="sd"> :returns: supported enhancements which should be a subset of</span>
<span class="sd"> :const:`~certbot.constants.ENHANCEMENTS`</span>
<span class="sd"> :rtype: :class:`collections.Iterable` of :class:`str`</span>
<span class="sd"> """</span>
<span class="k">def</span> <span class="nf">save</span><span class="p">(</span><span class="n">title</span><span class="o">=</span><span class="kc">None</span><span class="p">,</span> <span class="n">temporary</span><span class="o">=</span><span class="kc">False</span><span class="p">):</span>
<span class="sd">"""Saves all changes to the configuration files.</span>
<span class="sd"> Both title and temporary are needed because a save may be</span>
<span class="sd"> intended to be permanent, but the save is not ready to be a full</span>
<span class="sd"> checkpoint.</span>
<span class="sd"> It is assumed that at most one checkpoint is finalized by this</span>
<span class="sd"> method. Additionally, if an exception is raised, it is assumed a</span>
<span class="sd"> new checkpoint was not finalized.</span>
<span class="sd"> :param str title: The title of the save. If a title is given, the</span>
<span class="sd"> configuration will be saved as a new checkpoint and put in a</span>
<span class="sd"> timestamped directory. `title` has no effect if temporary is true.</span>
<span class="sd"> :param bool temporary: Indicates whether the changes made will</span>
<span class="sd"> be quickly reversed in the future (challenges)</span>
<span class="sd"> :raises .PluginError: when save is unsuccessful</span>
<span class="sd"> """</span>
<span class="k">def</span> <span class="nf">rollback_checkpoints</span><span class="p">(</span><span class="n">rollback</span><span class="o">=</span><span class="mi">1</span><span class="p">):</span>
<span class="sd">"""Revert `rollback` number of configuration checkpoints.</span>
<span class="sd"> :raises .PluginError: when configuration cannot be fully reverted</span>
<span class="sd"> """</span>
<span class="k">def</span> <span class="nf">recovery_routine</span><span class="p">():</span> <span class="c1"># type: ignore</span>
<span class="sd">"""Revert configuration to most recent finalized checkpoint.</span>
<span class="sd"> Remove all changes (temporary and permanent) that have not been</span>
<span class="sd"> finalized. This is useful to protect against crashes and other</span>
<span class="sd"> execution interruptions.</span>
<span class="sd"> :raises .errors.PluginError: If unable to recover the configuration</span>
<span class="sd"> """</span>
<span class="k">def</span> <span class="nf">view_config_changes</span><span class="p">():</span> <span class="c1"># type: ignore</span>
<span class="sd">"""Display all of the LE config changes.</span>
<span class="sd"> :raises .PluginError: when config changes cannot be parsed</span>
<span class="sd"> """</span>
<span class="k">def</span> <span class="nf">config_test</span><span class="p">():</span> <span class="c1"># type: ignore</span>
<span class="sd">"""Make sure the configuration is valid.</span>
<span class="sd"> :raises .MisconfigurationError: when the config is not in a usable state</span>
<span class="sd"> """</span>
<span class="k">def</span> <span class="nf">restart</span><span class="p">():</span> <span class="c1"># type: ignore</span>
<span class="sd">"""Restart or refresh the server content.</span>
<span class="sd"> :raises .PluginError: when server cannot be restarted</span>
<span class="sd"> """</span></div>
<div class="viewcode-block" id="IDisplay"><a class="viewcode-back" href="../../api/interfaces.html#certbot.interfaces.IDisplay">[docs]</a><span class="k">class</span> <span class="nc">IDisplay</span><span class="p">(</span><span class="n">zope</span><span class="o">.</span><span class="n">interface</span><span class="o">.</span><span class="n">Interface</span><span class="p">):</span>
<span class="sd">"""Generic display."""</span>
<span class="c1"># pylint: disable=too-many-arguments</span>
<span class="c1"># see https://github.com/certbot/certbot/issues/3915</span>
<span class="k">def</span> <span class="nf">notification</span><span class="p">(</span><span class="n">message</span><span class="p">,</span> <span class="n">pause</span><span class="p">,</span> <span class="n">wrap</span><span class="o">=</span><span class="kc">True</span><span class="p">,</span> <span class="n">force_interactive</span><span class="o">=</span><span class="kc">False</span><span class="p">):</span>
<span class="sd">"""Displays a string message</span>
<span class="sd"> :param str message: Message to display</span>
<span class="sd"> :param bool pause: Whether or not the application should pause for</span>
<span class="sd"> confirmation (if available)</span>
<span class="sd"> :param bool wrap: Whether or not the application should wrap text</span>
<span class="sd"> :param bool force_interactive: True if it's safe to prompt the user</span>
<span class="sd"> because it won't cause any workflow regressions</span>
<span class="sd"> """</span>
<span class="k">def</span> <span class="nf">menu</span><span class="p">(</span><span class="n">message</span><span class="p">,</span> <span class="n">choices</span><span class="p">,</span> <span class="n">ok_label</span><span class="o">=</span><span class="s2">"OK"</span><span class="p">,</span>
<span class="n">cancel_label</span><span class="o">=</span><span class="s2">"Cancel"</span><span class="p">,</span> <span class="n">help_label</span><span class="o">=</span><span class="s2">""</span><span class="p">,</span>
<span class="n">default</span><span class="o">=</span><span class="kc">None</span><span class="p">,</span> <span class="n">cli_flag</span><span class="o">=</span><span class="kc">None</span><span class="p">,</span> <span class="n">force_interactive</span><span class="o">=</span><span class="kc">False</span><span class="p">):</span>
<span class="sd">"""Displays a generic menu.</span>
<span class="sd"> When not setting force_interactive=True, you must provide a</span>
<span class="sd"> default value.</span>
<span class="sd"> :param str message: message to display</span>
<span class="sd"> :param choices: choices</span>
<span class="sd"> :type choices: :class:`list` of :func:`tuple` or :class:`str`</span>
<span class="sd"> :param str ok_label: label for OK button</span>
<span class="sd"> :param str cancel_label: label for Cancel button</span>
<span class="sd"> :param str help_label: label for Help button</span>
<span class="sd"> :param int default: default (non-interactive) choice from the menu</span>
<span class="sd"> :param str cli_flag: to automate choice from the menu, eg "--keep"</span>
<span class="sd"> :param bool force_interactive: True if it's safe to prompt the user</span>
<span class="sd"> because it won't cause any workflow regressions</span>
<span class="sd"> :returns: tuple of (`code`, `index`) where</span>
<span class="sd"> `code` - str display exit code</span>
<span class="sd"> `index` - int index of the user's selection</span>
<span class="sd"> :raises errors.MissingCommandlineFlag: if called in non-interactive</span>
<span class="sd"> mode without a default set</span>
<span class="sd"> """</span>
<span class="k">def</span> <span class="nf">input</span><span class="p">(</span><span class="n">message</span><span class="p">,</span> <span class="n">default</span><span class="o">=</span><span class="kc">None</span><span class="p">,</span> <span class="n">cli_args</span><span class="o">=</span><span class="kc">None</span><span class="p">,</span> <span class="n">force_interactive</span><span class="o">=</span><span class="kc">False</span><span class="p">):</span>
<span class="sd">"""Accept input from the user.</span>
<span class="sd"> When not setting force_interactive=True, you must provide a</span>
<span class="sd"> default value.</span>
<span class="sd"> :param str message: message to display to the user</span>
<span class="sd"> :param str default: default (non-interactive) response to prompt</span>
<span class="sd"> :param bool force_interactive: True if it's safe to prompt the user</span>
<span class="sd"> because it won't cause any workflow regressions</span>
<span class="sd"> :returns: tuple of (`code`, `input`) where</span>
<span class="sd"> `code` - str display exit code</span>
<span class="sd"> `input` - str of the user's input</span>
<span class="sd"> :rtype: tuple</span>
<span class="sd"> :raises errors.MissingCommandlineFlag: if called in non-interactive</span>
<span class="sd"> mode without a default set</span>
<span class="sd"> """</span>
<span class="k">def</span> <span class="nf">yesno</span><span class="p">(</span><span class="n">message</span><span class="p">,</span> <span class="n">yes_label</span><span class="o">=</span><span class="s2">"Yes"</span><span class="p">,</span> <span class="n">no_label</span><span class="o">=</span><span class="s2">"No"</span><span class="p">,</span> <span class="n">default</span><span class="o">=</span><span class="kc">None</span><span class="p">,</span>
<span class="n">cli_args</span><span class="o">=</span><span class="kc">None</span><span class="p">,</span> <span class="n">force_interactive</span><span class="o">=</span><span class="kc">False</span><span class="p">):</span>
<span class="sd">"""Query the user with a yes/no question.</span>
<span class="sd"> Yes and No label must begin with different letters.</span>
<span class="sd"> When not setting force_interactive=True, you must provide a</span>
<span class="sd"> default value.</span>
<span class="sd"> :param str message: question for the user</span>
<span class="sd"> :param str default: default (non-interactive) choice from the menu</span>
<span class="sd"> :param str cli_flag: to automate choice from the menu, eg "--redirect / --no-redirect"</span>
<span class="sd"> :param bool force_interactive: True if it's safe to prompt the user</span>
<span class="sd"> because it won't cause any workflow regressions</span>
<span class="sd"> :returns: True for "Yes", False for "No"</span>
<span class="sd"> :rtype: bool</span>
<span class="sd"> :raises errors.MissingCommandlineFlag: if called in non-interactive</span>
<span class="sd"> mode without a default set</span>
<span class="sd"> """</span>
<span class="k">def</span> <span class="nf">checklist</span><span class="p">(</span><span class="n">message</span><span class="p">,</span> <span class="n">tags</span><span class="p">,</span> <span class="n">default_state</span><span class="p">,</span>
<span class="n">default</span><span class="o">=</span><span class="kc">None</span><span class="p">,</span> <span class="n">cli_args</span><span class="o">=</span><span class="kc">None</span><span class="p">,</span> <span class="n">force_interactive</span><span class="o">=</span><span class="kc">False</span><span class="p">):</span>
<span class="sd">"""Allow for multiple selections from a menu.</span>
<span class="sd"> When not setting force_interactive=True, you must provide a</span>
<span class="sd"> default value.</span>
<span class="sd"> :param str message: message to display to the user</span>
<span class="sd"> :param list tags: where each is of type :class:`str` len(tags) > 0</span>
<span class="sd"> :param bool default_status: If True, items are in a selected state by default.</span>
<span class="sd"> :param str default: default (non-interactive) state of the checklist</span>
<span class="sd"> :param str cli_flag: to automate choice from the menu, eg "--domains"</span>
<span class="sd"> :param bool force_interactive: True if it's safe to prompt the user</span>
<span class="sd"> because it won't cause any workflow regressions</span>
<span class="sd"> :returns: tuple of the form (code, list_tags) where</span>
<span class="sd"> `code` - int display exit code</span>
<span class="sd"> `list_tags` - list of str tags selected by the user</span>
<span class="sd"> :rtype: tuple</span>
<span class="sd"> :raises errors.MissingCommandlineFlag: if called in non-interactive</span>
<span class="sd"> mode without a default set</span>
<span class="sd"> """</span>
<span class="k">def</span> <span class="nf">directory_select</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">message</span><span class="p">,</span> <span class="n">default</span><span class="o">=</span><span class="kc">None</span><span class="p">,</span>
<span class="n">cli_flag</span><span class="o">=</span><span class="kc">None</span><span class="p">,</span> <span class="n">force_interactive</span><span class="o">=</span><span class="kc">False</span><span class="p">):</span>
<span class="sd">"""Display a directory selection screen.</span>
<span class="sd"> When not setting force_interactive=True, you must provide a</span>
<span class="sd"> default value.</span>
<span class="sd"> :param str message: prompt to give the user</span>
<span class="sd"> :param default: the default value to return, if one exists, when</span>
<span class="sd"> using the NoninteractiveDisplay</span>
<span class="sd"> :param str cli_flag: option used to set this value with the CLI,</span>
<span class="sd"> if one exists, to be included in error messages given by</span>
<span class="sd"> NoninteractiveDisplay</span>
<span class="sd"> :param bool force_interactive: True if it's safe to prompt the user</span>
<span class="sd"> because it won't cause any workflow regressions</span>
<span class="sd"> :returns: tuple of the form (`code`, `string`) where</span>
<span class="sd"> `code` - int display exit code</span>
<span class="sd"> `string` - input entered by the user</span>
<span class="sd"> """</span></div>
<div class="viewcode-block" id="IValidator"><a class="viewcode-back" href="../../api/interfaces.html#certbot.interfaces.IValidator">[docs]</a><span class="k">class</span> <span class="nc">IValidator</span><span class="p">(</span><span class="n">zope</span><span class="o">.</span><span class="n">interface</span><span class="o">.</span><span class="n">Interface</span><span class="p">):</span>
<span class="sd">"""Configuration validator."""</span>
<span class="k">def</span> <span class="nf">certificate</span><span class="p">(</span><span class="n">cert</span><span class="p">,</span> <span class="n">name</span><span class="p">,</span> <span class="n">alt_host</span><span class="o">=</span><span class="kc">None</span><span class="p">,</span> <span class="n">port</span><span class="o">=</span><span class="mi">443</span><span class="p">):</span>
<span class="sd">"""Verifies the certificate presented at name is cert</span>
<span class="sd"> :param OpenSSL.crypto.X509 cert: Expected certificate</span>
<span class="sd"> :param str name: Server's domain name</span>
<span class="sd"> :param bytes alt_host: Host to connect to instead of the IP</span>
<span class="sd"> address of host</span>
<span class="sd"> :param int port: Port to connect to</span>
<span class="sd"> :returns: True if the certificate was verified successfully</span>
<span class="sd"> :rtype: bool</span>
<span class="sd"> """</span>
<span class="k">def</span> <span class="nf">redirect</span><span class="p">(</span><span class="n">name</span><span class="p">,</span> <span class="n">port</span><span class="o">=</span><span class="mi">80</span><span class="p">,</span> <span class="n">headers</span><span class="o">=</span><span class="kc">None</span><span class="p">):</span>
<span class="sd">"""Verify redirect to HTTPS</span>
<span class="sd"> :param str name: Server's domain name</span>
<span class="sd"> :param int port: Port to connect to</span>
<span class="sd"> :param dict headers: HTTP headers to include in request</span>
<span class="sd"> :returns: True if redirect is successfully enabled</span>
<span class="sd"> :rtype: bool</span>
<span class="sd"> """</span>
<span class="k">def</span> <span class="nf">hsts</span><span class="p">(</span><span class="n">name</span><span class="p">):</span>
<span class="sd">"""Verify HSTS header is enabled</span>
<span class="sd"> :param str name: Server's domain name</span>
<span class="sd"> :returns: True if HSTS header is successfully enabled</span>
<span class="sd"> :rtype: bool</span>
<span class="sd"> """</span>
<span class="k">def</span> <span class="nf">ocsp_stapling</span><span class="p">(</span><span class="n">name</span><span class="p">):</span>
<span class="sd">"""Verify ocsp stapling for domain</span>
<span class="sd"> :param str name: Server's domain name</span>
<span class="sd"> :returns: True if ocsp stapling is successfully enabled</span>
<span class="sd"> :rtype: bool</span>
<span class="sd"> """</span></div>
<div class="viewcode-block" id="IReporter"><a class="viewcode-back" href="../../api/interfaces.html#certbot.interfaces.IReporter">[docs]</a><span class="k">class</span> <span class="nc">IReporter</span><span class="p">(</span><span class="n">zope</span><span class="o">.</span><span class="n">interface</span><span class="o">.</span><span class="n">Interface</span><span class="p">):</span>
<span class="sd">"""Interface to collect and display information to the user."""</span>
<span class="n">HIGH_PRIORITY</span> <span class="o">=</span> <span class="n">zope</span><span class="o">.</span><span class="n">interface</span><span class="o">.</span><span class="n">Attribute</span><span class="p">(</span>
<span class="s2">"Used to denote high priority messages"</span><span class="p">)</span>
<span class="n">MEDIUM_PRIORITY</span> <span class="o">=</span> <span class="n">zope</span><span class="o">.</span><span class="n">interface</span><span class="o">.</span><span class="n">Attribute</span><span class="p">(</span>
<span class="s2">"Used to denote medium priority messages"</span><span class="p">)</span>
<span class="n">LOW_PRIORITY</span> <span class="o">=</span> <span class="n">zope</span><span class="o">.</span><span class="n">interface</span><span class="o">.</span><span class="n">Attribute</span><span class="p">(</span>
<span class="s2">"Used to denote low priority messages"</span><span class="p">)</span>
<span class="k">def</span> <span class="nf">add_message</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">msg</span><span class="p">,</span> <span class="n">priority</span><span class="p">,</span> <span class="n">on_crash</span><span class="o">=</span><span class="kc">True</span><span class="p">):</span>
<span class="sd">"""Adds msg to the list of messages to be printed.</span>
<span class="sd"> :param str msg: Message to be displayed to the user.</span>
<span class="sd"> :param int priority: One of HIGH_PRIORITY, MEDIUM_PRIORITY, or</span>
<span class="sd"> LOW_PRIORITY.</span>
<span class="sd"> :param bool on_crash: Whether or not the message should be printed if</span>
<span class="sd"> the program exits abnormally.</span>
<span class="sd"> """</span>
<span class="k">def</span> <span class="nf">print_messages</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
<span class="sd">"""Prints messages to the user and clears the message queue."""</span></div>
</pre></div>
</div>
</div>
<footer>
<hr/>
<div role="contentinfo">
<p>
© Copyright 2014-2016 - The Certbot software and documentation are licensed under the Apache 2.0 license as described at https://eff.org/cb-license .
</p>
</div>
Built with <a href="http://sphinx-doc.org/">Sphinx</a> using a <a href="https://github.com/snide/sphinx_rtd_theme">theme</a> provided by <a href="https://readthedocs.org">Read the Docs</a>.
</footer>
</div>
</div>
</section>
</div>
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT:'../../',
VERSION:'0.14.2',
COLLAPSE_INDEX:false,
FILE_SUFFIX:'.html',
HAS_SOURCE: true
};
</script>
<script type="text/javascript" src="../../_static/jquery.js"></script>
<script type="text/javascript" src="../../_static/underscore.js"></script>
<script type="text/javascript" src="../../_static/doctools.js"></script>
<script type="text/javascript" src="../../_static/js/theme.js"></script>
<script type="text/javascript">
jQuery(function () {
SphinxRtdTheme.StickyNav.enable();
});
</script>
</body>
</html>
