certbot.client
¶
Certbot client API.
-
certbot.client.
acme_from_config_key
(config, key, regr=None)[source]¶ Wrangle ACME client construction
-
certbot.client.
determine_user_agent
(config)[source]¶ 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
-
certbot.client.
ua_flags
(config)[source]¶ Turn some very important CLI flags into clues in the user agent.
-
certbot.client.
sample_user_agent
()[source]¶ Document what this Certbot’s user agent string will be like.
-
certbot.client.
register
(config, account_storage, tos_cb=None)[source]¶ 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 iftos_cb
returnsFalse
. - 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 acceptRegistrationResource
and return abool
:True
iff the Terms of Service present in the containedRegistration.terms_of_service
is accepted by the client, andFalse
otherwise.tos_cb
will be called only if the client action is necessary, i.e. whenterms_of_service is not None
. This argument is optional, if not supplied it will default to automatic acceptance!
Raises: - certbot.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
ofAccount
andacme.client.Client
-
certbot.client.
perform_registration
(acme, config, tos_cb)[source]¶ Actually register new account, trying repeatedly if there are email problems
Parameters: - client (acme.client.Client) – ACME client object.
- config (IConfig) – Client configuration.
- tos_cb (Callable) – a callback to handle Term of Service agreement.
Returns: Registration Resource.
Return type: acme.messages.RegistrationResource
-
class
certbot.client.
Client
(config, account_, auth, installer, acme=None)[source]¶ Bases:
object
Certbot’s client.
Variables: - config (IConfig) – Client configuration.
- account (Account) – Account registered with
register
. - auth_handler (AuthHandler) – Authorizations handler that will
dispatch DV challenges to appropriate authenticators
(providing
IAuthenticator
interface). - auth (IAuthenticator) – Prepared (
IAuthenticator.prepare
) authenticator that can solve ACME challenges. - installer (IInstaller) – Installer.
- acme (acme.client.BackwardsCompatibleClientV2) – Optional ACME
client API handle. You might already have one from
register
.
-
obtain_certificate_from_csr
(csr, orderr=None)[source]¶ Obtain certificate.
Parameters: - csr (util.CSR) – PEM-encoded Certificate Signing
Request. The key used to generate this CSR can be different
than
authkey
. - orderr (acme.messages.OrderResource) – contains authzrs
Returns: certificate and chain as PEM byte strings
Return type: tuple
- csr (util.CSR) – PEM-encoded Certificate Signing
Request. The key used to generate this CSR can be different
than
-
obtain_certificate
(domains, old_keypath=None)[source]¶ Obtains a certificate from the ACME server.
register
must be called beforeobtain_certificate
Parameters: domains (list) – domains to get a certificate Returns: certificate as PEM string, chain as PEM string, newly generated private key ( util.Key
), and DER-encoded Certificate Signing Request (util.CSR
).Return type: tuple
Request a new order and complete its authorizations.
Parameters: - csr_pem (str) – A CSR in PEM format.
- best_effort (bool) – True if failing to complete all authorizations should not raise an exception
Returns: order resource containing its completed authorizations
Return type: acme.messages.OrderResource
-
obtain_and_enroll_certificate
(domains, certname)[source]¶ 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
ofstr
) – domains to request a certificate for - certname (
str
orNone
) – requested name of lineage
Returns: A new
certbot.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.- domains (
-
_choose_lineagename
(domains, certname)[source]¶ Chooses a name for the new lineage.
Parameters: - domains (
list
ofstr
) – domains in certificate request - certname (
str
orNone
) – requested name of lineage
Returns: lineage name that should be used
Return type: str
- domains (
-
save_certificate
(cert_pem, chain_pem, cert_path, chain_path, fullchain_path)[source]¶ Saves the certificate received from the ACME server.
Parameters: - cert_pem (str) –
- chain_pem (str) –
- 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
ofstr
Raises: IOError – If unable to find room to write the cert files
-
deploy_certificate
(domains, privkey_path, cert_path, chain_path, fullchain_path)[source]¶ 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, chain_path, ask_redirect=True)[source]¶ Enhance the configuration.
Parameters: - domains (list) – list of domains to configure
- chain_path (
str
orNone
) – chain file path
Raises: errors.Error – if no installer is specified in the client.
-
apply_enhancement
(domains, enhancement, options=None)[source]¶ Applies an enhancement on all domains.
Parameters: - domains (list) – list of ssl_vhosts (as strings)
- enhancement (str) – name of enhancement, e.g. ensure-http-header
- options (str) –
options to enhancement, e.g. Strict-Transport-Security
Note
When more
options
are needed, make options a list.
Raises: errors.PluginError – If Enhancement is not supported, or if there is any other problem with the enhancement.
-
certbot.client.
validate_key_csr
(privkey, csr=None)[source]¶ 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 (
certbot.util.Key
) – Key associated with CSR - csr (util.CSR) – CSR
Raises: errors.Error – when validation fails
- privkey (
-
certbot.client.
rollback
(default_installer, checkpoints, config, plugins)[source]¶ Revert configuration the specified number of checkpoints.
Parameters: - checkpoints (int) – Number of checkpoints to revert.
- config (
certbot.interfaces.IConfig
) – Configuration.
-
certbot.client.
view_config_changes
(config, num=None)[source]¶ View checkpoints and associated configuration changes.
Note
This assumes that the installation is using a Reverter object.
Parameters: config ( certbot.interfaces.IConfig
) – Configuration.
-
certbot.client.
_open_pem_file
(cli_arg_path, pem_path)[source]¶ Open a pem file.
If cli_arg_path was set by the client, open that. Otherwise, uniquify the file path.
Parameters: - cli_arg_path (str) – the cli arg name, e.g. cert_path
- pem_path (str) – the pem file path to open
Returns: a tuple of file object and its absolute file path