From 0671b492d677be2f5d287fa66817d701ea593c06 Mon Sep 17 00:00:00 2001 From: Zach Shepherd Date: Wed, 7 Jun 2017 13:53:16 -0700 Subject: [PATCH 01/16] Fix warning in Cloudflare docs --- certbot-dns-cloudflare/docs/api/dns_cloudflare.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/certbot-dns-cloudflare/docs/api/dns_cloudflare.rst b/certbot-dns-cloudflare/docs/api/dns_cloudflare.rst index 939d4c0b4..35f525201 100644 --- a/certbot-dns-cloudflare/docs/api/dns_cloudflare.rst +++ b/certbot-dns-cloudflare/docs/api/dns_cloudflare.rst @@ -1,5 +1,5 @@ :mod:`certbot_dns_cloudflare.dns_cloudflare` --------------------------------------- +-------------------------------------------- .. automodule:: certbot_dns_cloudflare.dns_cloudflare :members: From 215c85d7bed0de619de6921ffc45a595c4e9cc12 Mon Sep 17 00:00:00 2001 From: Zach Shepherd Date: Wed, 7 Jun 2017 14:40:55 -0700 Subject: [PATCH 02/16] Provide basic Cloudflare documentation --- .../certbot_dns_cloudflare/__init__.py | 18 +++++++++++++++++- 1 file changed, 17 insertions(+), 1 deletion(-) diff --git a/certbot-dns-cloudflare/certbot_dns_cloudflare/__init__.py b/certbot-dns-cloudflare/certbot_dns_cloudflare/__init__.py index f4820e1ca..7a9fa105c 100644 --- a/certbot-dns-cloudflare/certbot_dns_cloudflare/__init__.py +++ b/certbot-dns-cloudflare/certbot_dns_cloudflare/__init__.py @@ -1 +1,17 @@ -"""Cloudflare DNS Authenticator""" +"""Cloudflare DNS Authenticator + +This plugin automates the process of completing a dns-01 challenge +(`~acme.challenges.DNS01`) using the Cloudflare API. + +Use of this plugin requires a configuration file containing Cloudflare API +credentials, obtained from your Cloudflare +`account page `_. + +Example: + +.. code-block:: ini + + dns_cloudflare_email = cloudflare@example.com + dns_cloudflare_api_key = 0123456789abcdef0123456789abcdef01234567 + +""" From 9f7c9decce2fa657aed3f28a8a8286178296c274 Mon Sep 17 00:00:00 2001 From: Zach Shepherd Date: Wed, 7 Jun 2017 15:55:28 -0700 Subject: [PATCH 03/16] Expand documentation --- .../certbot_dns_cloudflare/__init__.py | 32 +++++++++++++++---- 1 file changed, 25 insertions(+), 7 deletions(-) diff --git a/certbot-dns-cloudflare/certbot_dns_cloudflare/__init__.py b/certbot-dns-cloudflare/certbot_dns_cloudflare/__init__.py index 7a9fa105c..6bb22fce2 100644 --- a/certbot-dns-cloudflare/certbot_dns_cloudflare/__init__.py +++ b/certbot-dns-cloudflare/certbot_dns_cloudflare/__init__.py @@ -1,17 +1,35 @@ -"""Cloudflare DNS Authenticator +""" +The `~certbot_dns_cloudflare.dns_cloudflare` plugin automates the process of +completing a `dns-01` challenge (`~acme.challenges.DNS01`) using the Cloudflare +API. -This plugin automates the process of completing a dns-01 challenge -(`~acme.challenges.DNS01`) using the Cloudflare API. + +Credentials +----------- Use of this plugin requires a configuration file containing Cloudflare API credentials, obtained from your Cloudflare `account page `_. -Example: - .. code-block:: ini + :name: credentials.ini + :caption: Example credentials file: + + # Cloudflare API credentials used by Certbot + dns_cloudflare_email = cloudflare@example.com + dns_cloudflare_api_key = 0123456789abcdef0123456789abcdef01234567 + +The path to this file can be provided interactively or using the +`--dns-cloudflare-credentials` command-line argument. Certbot records the path +to this file for use during renewal, but does not store the file's contents. + +.. caution:: + You should protect these API credentials as you would the password to your + Cloudflare account. Users who can read this file can use these credentials + to issue API calls on your behalf. Users who can cause Certbot to run using + these credentials can complete a `dns-01` challenge to acquire new + certificates or revoke existing certificates for associated domains. + - dns_cloudflare_email = cloudflare@example.com - dns_cloudflare_api_key = 0123456789abcdef0123456789abcdef01234567 """ From 1817cfe460a48d7d81334b2a7e77e78b0f6ed55a Mon Sep 17 00:00:00 2001 From: Zach Shepherd Date: Wed, 7 Jun 2017 15:56:09 -0700 Subject: [PATCH 04/16] Document arguments --- .../certbot_dns_cloudflare/__init__.py | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/certbot-dns-cloudflare/certbot_dns_cloudflare/__init__.py b/certbot-dns-cloudflare/certbot_dns_cloudflare/__init__.py index 6bb22fce2..779a1002a 100644 --- a/certbot-dns-cloudflare/certbot_dns_cloudflare/__init__.py +++ b/certbot-dns-cloudflare/certbot_dns_cloudflare/__init__.py @@ -4,6 +4,20 @@ completing a `dns-01` challenge (`~acme.challenges.DNS01`) using the Cloudflare API. +Named Arguments +--------------- + +====================================== ======= ============================== +Argument Default Description +====================================== ======= ============================== +`--dns-cloudflare-credentials` None Cloudflare credentials INI + file. (See Credentials_.) +`--dns-cloudflare-propagation-seconds` 10 The number of seconds to wait + for DNS to propagate before + asking the ACME server to + verify the DNS record. +====================================== ======= ============================== + Credentials ----------- From 0387031550dfacf6a5e64d5c709f18db851eb20e Mon Sep 17 00:00:00 2001 From: Zach Shepherd Date: Wed, 7 Jun 2017 16:32:25 -0700 Subject: [PATCH 05/16] Various improvements --- .../certbot_dns_cloudflare/__init__.py | 55 ++++++++++++++----- 1 file changed, 41 insertions(+), 14 deletions(-) diff --git a/certbot-dns-cloudflare/certbot_dns_cloudflare/__init__.py b/certbot-dns-cloudflare/certbot_dns_cloudflare/__init__.py index 779a1002a..dda05185f 100644 --- a/certbot-dns-cloudflare/certbot_dns_cloudflare/__init__.py +++ b/certbot-dns-cloudflare/certbot_dns_cloudflare/__init__.py @@ -1,22 +1,20 @@ """ The `~certbot_dns_cloudflare.dns_cloudflare` plugin automates the process of -completing a `dns-01` challenge (`~acme.challenges.DNS01`) using the Cloudflare -API. +completing a ``dns-01`` challenge (`~acme.challenges.DNS01`) using the +Cloudflare API. Named Arguments --------------- -====================================== ======= ============================== -Argument Default Description -====================================== ======= ============================== -`--dns-cloudflare-credentials` None Cloudflare credentials INI - file. (See Credentials_.) -`--dns-cloudflare-propagation-seconds` 10 The number of seconds to wait - for DNS to propagate before - asking the ACME server to - verify the DNS record. -====================================== ======= ============================== +======================================== ===================================== +``--dns-cloudflare-credentials`` Cloudflare credentials_ INI file. + (Required) +``--dns-cloudflare-propagation-seconds`` The number of seconds to wait for DNS + to propagate before asking the ACME + server to verify the DNS record. + (Default: 10) +======================================== ===================================== Credentials ----------- @@ -34,16 +32,45 @@ credentials, obtained from your Cloudflare dns_cloudflare_api_key = 0123456789abcdef0123456789abcdef01234567 The path to this file can be provided interactively or using the -`--dns-cloudflare-credentials` command-line argument. Certbot records the path +``--dns-cloudflare-credentials`` command-line argument. Certbot records the path to this file for use during renewal, but does not store the file's contents. .. caution:: You should protect these API credentials as you would the password to your Cloudflare account. Users who can read this file can use these credentials to issue API calls on your behalf. Users who can cause Certbot to run using - these credentials can complete a `dns-01` challenge to acquire new + these credentials can complete a ``dns-01`` challenge to acquire new certificates or revoke existing certificates for associated domains. +Examples +-------- +.. code-block:: bash + :caption: To acquire a certificate for ``example.com`` + + certbot certonly \\ + --dns-cloudflare \\ + --dns-cloudflare-credentials ~/.secrets/certbot/cloudflare.ini \\ + -d example.com + +.. code-block:: bash + :caption: To acquire a single certificate for both ``example.com`` and + ``www.example.com`` + + certbot certonly \\ + --dns-cloudflare \\ + --dns-cloudflare-credentials ~/.secrets/certbot/cloudflare.ini \\ + -d example.com \\ + -d www.example.com + +.. code-block:: bash + :caption: To acquire a certificate for ``example.com``, waiting 60 seconds + for DNS propagation + + certbot certonly \\ + --dns-cloudflare \\ + --dns-cloudflare-credentials ~/.secrets/certbot/cloudflare.ini \\ + --dns-cloudflare-propagation-seconds 60 \\ + -d example.com """ From 1ac7848ce65eeae4328cbaa92ca85b903cda1311 Mon Sep 17 00:00:00 2001 From: Zach Shepherd Date: Wed, 7 Jun 2017 17:02:03 -0700 Subject: [PATCH 06/16] Respond to review feedback * Clarify that the challenge involves TXT records * Clarify potential consequences of credential exposure --- .../certbot_dns_cloudflare/__init__.py | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/certbot-dns-cloudflare/certbot_dns_cloudflare/__init__.py b/certbot-dns-cloudflare/certbot_dns_cloudflare/__init__.py index dda05185f..b6a97c762 100644 --- a/certbot-dns-cloudflare/certbot_dns_cloudflare/__init__.py +++ b/certbot-dns-cloudflare/certbot_dns_cloudflare/__init__.py @@ -1,7 +1,7 @@ """ The `~certbot_dns_cloudflare.dns_cloudflare` plugin automates the process of -completing a ``dns-01`` challenge (`~acme.challenges.DNS01`) using the -Cloudflare API. +completing a ``dns-01`` challenge (`~acme.challenges.DNS01`) by creating, and +subsequently removing, TXT records using the Cloudflare API. Named Arguments @@ -38,9 +38,10 @@ to this file for use during renewal, but does not store the file's contents. .. caution:: You should protect these API credentials as you would the password to your Cloudflare account. Users who can read this file can use these credentials - to issue API calls on your behalf. Users who can cause Certbot to run using - these credentials can complete a ``dns-01`` challenge to acquire new - certificates or revoke existing certificates for associated domains. + to issue arbitrary API calls on your behalf. Users who can cause Certbot to + run using these credentials can complete a ``dns-01`` challenge to acquire + new certificates or revoke existing certificates for associated domains, + even if those domains aren't being managed by this server. Examples -------- From 9f56693ad4b7d517fc0db20cfc291116e91d646f Mon Sep 17 00:00:00 2001 From: Zach Shepherd Date: Thu, 8 Jun 2017 12:18:56 -0700 Subject: [PATCH 07/16] Add documentation for CloudXNS --- .../certbot_dns_cloudxns/__init__.py | 78 ++++++++++++++++++- 1 file changed, 77 insertions(+), 1 deletion(-) diff --git a/certbot-dns-cloudxns/certbot_dns_cloudxns/__init__.py b/certbot-dns-cloudxns/certbot_dns_cloudxns/__init__.py index 8df02d0fa..7260612cd 100644 --- a/certbot-dns-cloudxns/certbot_dns_cloudxns/__init__.py +++ b/certbot-dns-cloudxns/certbot_dns_cloudxns/__init__.py @@ -1 +1,77 @@ -"""CloudXNS DNS Authenticator""" +""" +The `~certbot_dns_cloudxns.dns_cloudxns` plugin automates the process of +completing a ``dns-01`` challenge (`~acme.challenges.DNS01`) by creating, and +subsequently removing, TXT records using the CloudXNS API. + + +Named Arguments +--------------- + +======================================== ===================================== +``--dns-cloudxns-credentials` ` CloudXNS credentials_ INI file. + (Required) +``--dns-cloudxns-propagation-seconds`` The number of seconds to wait for DNS + to propagate before asking the ACME + server to verify the DNS record. + (Default: 30) +======================================== ===================================== + +Credentials +----------- + +Use of this plugin requires a configuration file containing CloudXNS API +credentials, obtained from your CloudXNS +`API page `_. + +.. code-block:: ini + :name: credentials.ini + :caption: Example credentials file: + + # CloudXNS API credentials used by Certbot + dns_cloudxns_api_key = 1234567890abcdef1234567890abcdef + dns_cloudxns_secret_key = 1122334455667788 + +The path to this file can be provided interactively or using the +``--dns-cloudxns-credentials`` command-line argument. Certbot records the path +to this file for use during renewal, but does not store the file's contents. + +.. caution:: + You should protect these API credentials as you would the password to your + CloudXNS account. Users who can read this file can use these credentials to + issue arbitrary API calls on your behalf. Users who can cause Certbot to run + using these credentials can complete a ``dns-01`` challenge to acquire new + certificates or revoke existing certificates for associated domains, even if + those domains aren't being managed by this server. + +Examples +-------- + +.. code-block:: bash + :caption: To acquire a certificate for ``example.com`` + + certbot certonly \\ + --dns-cloudxns \\ + --dns-cloudxns-credentials ~/.secrets/certbot/cloudxns.ini \\ + -d example.com + +.. code-block:: bash + :caption: To acquire a single certificate for both ``example.com`` and + ``www.example.com`` + + certbot certonly \\ + --dns-cloudxns \\ + --dns-cloudxns-credentials ~/.secrets/certbot/cloudxns.ini \\ + -d example.com \\ + -d www.example.com + +.. code-block:: bash + :caption: To acquire a certificate for ``example.com``, waiting 60 seconds + for DNS propagation + + certbot certonly \\ + --dns-cloudxns \\ + --dns-cloudxns-credentials ~/.secrets/certbot/cloudxns.ini \\ + --dns-cloudxns-propagation-seconds 60 \\ + -d example.com + +""" From 502ea82ac432385bf4cb321866d261a4b18db42b Mon Sep 17 00:00:00 2001 From: Zach Shepherd Date: Thu, 8 Jun 2017 13:58:53 -0700 Subject: [PATCH 08/16] Add documentation for DigitalOcean --- .../certbot_dns_digitalocean/__init__.py | 78 ++++++++++++++++++- 1 file changed, 77 insertions(+), 1 deletion(-) diff --git a/certbot-dns-digitalocean/certbot_dns_digitalocean/__init__.py b/certbot-dns-digitalocean/certbot_dns_digitalocean/__init__.py index 40b2527f8..7565a3725 100644 --- a/certbot-dns-digitalocean/certbot_dns_digitalocean/__init__.py +++ b/certbot-dns-digitalocean/certbot_dns_digitalocean/__init__.py @@ -1 +1,77 @@ -"""DigitalOcean DNS Authenticator""" +""" +The `~certbot_dns_digitalocean.dns_digitalocean` plugin automates the process of +completing a ``dns-01`` challenge (`~acme.challenges.DNS01`) by creating, and +subsequently removing, TXT records using the DigitalOcean API. + + +Named Arguments +--------------- + +========================================== =================================== +``--dns-digitalocean-credentials`` DigitalOcean credentials_ INI file. + (Required) +``--dns-digitalocean-propagation-seconds`` The number of seconds to wait for + DNS to propagate before asking the + ACME server to verify the DNS + record. + (Default: 10) +========================================== =================================== + +Credentials +----------- + +Use of this plugin requires a configuration file containing DigitalOcean API +credentials, obtained from your DigitalOcean account's `Applications & API +Tokens page `_. + +.. code-block:: ini + :name: credentials.ini + :caption: Example credentials file: + + # DigitalOcean API credentials used by Certbot + dns_digitalocean_token = 0000111122223333444455556666777788889999aaaabbbbccccddddeeeeffff + +The path to this file can be provided interactively or using the +``--dns-digitalocean-credentials`` command-line argument. Certbot records the +path to this file for use during renewal, but does not store the file's contents. + +.. caution:: + You should protect these API credentials as you would the password to your + DigitalOcean account. Users who can read this file can use these credentials + to issue arbitrary API calls on your behalf. Users who can cause Certbot to + run using these credentials can complete a ``dns-01`` challenge to acquire + new certificates or revoke existing certificates for associated domains, + even if those domains aren't being managed by this server. + +Examples +-------- + +.. code-block:: bash + :caption: To acquire a certificate for ``example.com`` + + certbot certonly \\ + --dns-digitalocean \\ + --dns-digitalocean-credentials ~/.secrets/certbot/digitalocean.ini \\ + -d example.com + +.. code-block:: bash + :caption: To acquire a single certificate for both ``example.com`` and + ``www.example.com`` + + certbot certonly \\ + --dns-digitalocean \\ + --dns-digitalocean-credentials ~/.secrets/certbot/digitalocean.ini \\ + -d example.com \\ + -d www.example.com + +.. code-block:: bash + :caption: To acquire a certificate for ``example.com``, waiting 60 seconds + for DNS propagation + + certbot certonly \\ + --dns-digitalocean \\ + --dns-digitalocean-credentials ~/.secrets/certbot/digitalocean.ini \\ + --dns-digitalocean-propagation-seconds 60 \\ + -d example.com + +""" From 0325ad9244835fac724126f918b049a145f6cdb7 Mon Sep 17 00:00:00 2001 From: Zach Shepherd Date: Thu, 8 Jun 2017 14:18:52 -0700 Subject: [PATCH 09/16] Add documentation for DNSimple --- .../certbot_dns_dnsimple/__init__.py | 77 ++++++++++++++++++- 1 file changed, 76 insertions(+), 1 deletion(-) diff --git a/certbot-dns-dnsimple/certbot_dns_dnsimple/__init__.py b/certbot-dns-dnsimple/certbot_dns_dnsimple/__init__.py index 1d6747249..1f5a6cbe4 100644 --- a/certbot-dns-dnsimple/certbot_dns_dnsimple/__init__.py +++ b/certbot-dns-dnsimple/certbot_dns_dnsimple/__init__.py @@ -1 +1,76 @@ -"""DNSimple DNS Authenticator""" +""" +The `~certbot_dns_dnsimple.dns_dnsimple` plugin automates the process of +completing a ``dns-01`` challenge (`~acme.challenges.DNS01`) by creating, and +subsequently removing, TXT records using the DNSimple API. + + +Named Arguments +--------------- + +======================================== ===================================== +``--dns-dnsimple-credentials`` DNSimple credentials_ INI file. + (Required) +``--dns-dnsimple-propagation-seconds`` The number of seconds to wait for DNS + to propagate before asking the ACME + server to verify the DNS record. + (Default: 30) +======================================== ===================================== + +Credentials +----------- + +Use of this plugin requires a configuration file containing DNSimple API +credentials, obtained from your DNSimple +`account page `_. + +.. code-block:: ini + :name: credentials.ini + :caption: Example credentials file: + + # DNSimple API credentials used by Certbot + dns_dnsimple_token = MDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAw + +The path to this file can be provided interactively or using the +``--dns-dnsimple-credentials`` command-line argument. Certbot records the path +to this file for use during renewal, but does not store the file's contents. + +.. caution:: + You should protect these API credentials as you would the password to your + DNSimple account. Users who can read this file can use these credentials + to issue arbitrary API calls on your behalf. Users who can cause Certbot to + run using these credentials can complete a ``dns-01`` challenge to acquire + new certificates or revoke existing certificates for associated domains, + even if those domains aren't being managed by this server. + +Examples +-------- + +.. code-block:: bash + :caption: To acquire a certificate for ``example.com`` + + certbot certonly \\ + --dns-dnsimple \\ + --dns-dnsimple-credentials ~/.secrets/certbot/dnsimple.ini \\ + -d example.com + +.. code-block:: bash + :caption: To acquire a single certificate for both ``example.com`` and + ``www.example.com`` + + certbot certonly \\ + --dns-dnsimple \\ + --dns-dnsimple-credentials ~/.secrets/certbot/dnsimple.ini \\ + -d example.com \\ + -d www.example.com + +.. code-block:: bash + :caption: To acquire a certificate for ``example.com``, waiting 60 seconds + for DNS propagation + + certbot certonly \\ + --dns-dnsimple \\ + --dns-dnsimple-credentials ~/.secrets/certbot/dnsimple.ini \\ + --dns-dnsimple-propagation-seconds 60 \\ + -d example.com + +""" From c180a1065f3b526a209446767ff8fe18690499f0 Mon Sep 17 00:00:00 2001 From: Zach Shepherd Date: Thu, 8 Jun 2017 15:08:11 -0700 Subject: [PATCH 10/16] Add documentation for Google --- .../certbot_dns_google/__init__.py | 90 ++++++++++++++++++- certbot-dns-google/docs/conf.py | 7 +- 2 files changed, 93 insertions(+), 4 deletions(-) diff --git a/certbot-dns-google/certbot_dns_google/__init__.py b/certbot-dns-google/certbot_dns_google/__init__.py index 9e9096d83..362c6d8ce 100644 --- a/certbot-dns-google/certbot_dns_google/__init__.py +++ b/certbot-dns-google/certbot_dns_google/__init__.py @@ -1 +1,89 @@ -"""Google Cloud DNS Authenticator""" +""" +The `~certbot_dns_google.dns_google` plugin automates the process of +completing a ``dns-01`` challenge (`~acme.challenges.DNS01`) by creating, and +subsequently removing, TXT records using the Google Cloud DNS API. + + +Named Arguments +--------------- + +======================================== ===================================== +``--dns-google-credentials`` Google Cloud Platform credentials_ + JSON file. + (Required) +``--dns-google-propagation-seconds`` The number of seconds to wait for DNS + to propagate before asking the ACME + server to verify the DNS record. + (Default: 60) +======================================== ===================================== + +Credentials +----------- + +Use of this plugin requires a configuration file containing Google Cloud +Platform API credentials for an account with the following permissions: + +* ``dns.changes.create`` +* ``dns.changes.get`` +* ``dns.managedZones.list`` +* ``dns.resourceRecordSets.create`` +* ``dns.resourceRecordSets.delete`` + +Google provides instructions for +`creating a service account `_ +and +`information about the required permissions `_. + +.. code-block:: json + :name: credentials.json + :caption: Example credentials file: + + { + "type": "service_account", + ... + } + +The path to this file can be provided interactively or using the +``--dns-google-credentials`` command-line argument. Certbot records the path +to this file for use during renewal, but does not store the file's contents. + +.. caution:: + You should protect these API credentials as you would a password. Users who + can read this file can use these credentials to issue some types of API calls + on your behalf, limited by the permissions assigned to the account. Users who + can cause Certbot to run using these credentials can complete a ``dns-01`` + challenge to acquire new certificates or revoke existing certificates for + domains these credentials are authorized to manage. + +Examples +-------- + +.. code-block:: bash + :caption: To acquire a certificate for ``example.com`` + + certbot certonly \\ + --dns-google \\ + --dns-google-credentials ~/.secrets/certbot/google.json \\ + -d example.com + +.. code-block:: bash + :caption: To acquire a single certificate for both ``example.com`` and + ``www.example.com`` + + certbot certonly \\ + --dns-google \\ + --dns-google-credentials ~/.secrets/certbot/google.json \\ + -d example.com \\ + -d www.example.com + +.. code-block:: bash + :caption: To acquire a certificate for ``example.com``, waiting 120 seconds + for DNS propagation + + certbot certonly \\ + --dns-google \\ + --dns-google-credentials ~/.secrets/certbot/google.ini \\ + --dns-google-propagation-seconds 120 \\ + -d example.com + +""" diff --git a/certbot-dns-google/docs/conf.py b/certbot-dns-google/docs/conf.py index 4ff1af1d1..bbb343ee8 100644 --- a/certbot-dns-google/docs/conf.py +++ b/certbot-dns-google/docs/conf.py @@ -17,8 +17,8 @@ # documentation root, use os.path.abspath to make it absolute, like shown here. # import os -# import sys -# sys.path.insert(0, os.path.abspath('.')) +import sys +sys.path.insert(0, os.path.abspath('_ext')) # -- General configuration ------------------------------------------------ @@ -34,7 +34,8 @@ extensions = ['sphinx.ext.autodoc', 'sphinx.ext.intersphinx', 'sphinx.ext.todo', 'sphinx.ext.coverage', - 'sphinx.ext.viewcode'] + 'sphinx.ext.viewcode', + 'jsonlexer'] autodoc_member_order = 'bysource' autodoc_default_flags = ['show-inheritance', 'private-members'] From 14b1d2d72b2ea0c1d10ac9d5b81dd60e8aa5acc4 Mon Sep 17 00:00:00 2001 From: Zach Shepherd Date: Thu, 8 Jun 2017 15:44:38 -0700 Subject: [PATCH 11/16] Explicitly mention the permissions warning and chmod 600 --- .../certbot_dns_cloudflare/__init__.py | 9 +++++++++ certbot-dns-cloudxns/certbot_dns_cloudxns/__init__.py | 9 +++++++++ .../certbot_dns_digitalocean/__init__.py | 9 +++++++++ certbot-dns-dnsimple/certbot_dns_dnsimple/__init__.py | 9 +++++++++ certbot-dns-google/certbot_dns_google/__init__.py | 9 +++++++++ 5 files changed, 45 insertions(+) diff --git a/certbot-dns-cloudflare/certbot_dns_cloudflare/__init__.py b/certbot-dns-cloudflare/certbot_dns_cloudflare/__init__.py index b6a97c762..7e53f83ce 100644 --- a/certbot-dns-cloudflare/certbot_dns_cloudflare/__init__.py +++ b/certbot-dns-cloudflare/certbot_dns_cloudflare/__init__.py @@ -16,6 +16,7 @@ Named Arguments (Default: 10) ======================================== ===================================== + Credentials ----------- @@ -43,6 +44,14 @@ to this file for use during renewal, but does not store the file's contents. new certificates or revoke existing certificates for associated domains, even if those domains aren't being managed by this server. +Certbot will emit a warning if it detects that the credentials file can be +accessed by other users on your system. The warning reads "Unsafe permissions +on credentials configuration file", followed by the path to the credentials +file. This warning will be emitted each time Certbot uses the credentials file, +including for renewal, and cannot be silenced except by addressing the issue +(e.g., by using a command like ``chmod 600`` to restrict access to the file). + + Examples -------- diff --git a/certbot-dns-cloudxns/certbot_dns_cloudxns/__init__.py b/certbot-dns-cloudxns/certbot_dns_cloudxns/__init__.py index 7260612cd..6957b9cc3 100644 --- a/certbot-dns-cloudxns/certbot_dns_cloudxns/__init__.py +++ b/certbot-dns-cloudxns/certbot_dns_cloudxns/__init__.py @@ -16,6 +16,7 @@ Named Arguments (Default: 30) ======================================== ===================================== + Credentials ----------- @@ -43,6 +44,14 @@ to this file for use during renewal, but does not store the file's contents. certificates or revoke existing certificates for associated domains, even if those domains aren't being managed by this server. +Certbot will emit a warning if it detects that the credentials file can be +accessed by other users on your system. The warning reads "Unsafe permissions +on credentials configuration file", followed by the path to the credentials +file. This warning will be emitted each time Certbot uses the credentials file, +including for renewal, and cannot be silenced except by addressing the issue +(e.g., by using a command like ``chmod 600`` to restrict access to the file). + + Examples -------- diff --git a/certbot-dns-digitalocean/certbot_dns_digitalocean/__init__.py b/certbot-dns-digitalocean/certbot_dns_digitalocean/__init__.py index 7565a3725..3ab8df041 100644 --- a/certbot-dns-digitalocean/certbot_dns_digitalocean/__init__.py +++ b/certbot-dns-digitalocean/certbot_dns_digitalocean/__init__.py @@ -17,6 +17,7 @@ Named Arguments (Default: 10) ========================================== =================================== + Credentials ----------- @@ -43,6 +44,14 @@ path to this file for use during renewal, but does not store the file's contents new certificates or revoke existing certificates for associated domains, even if those domains aren't being managed by this server. +Certbot will emit a warning if it detects that the credentials file can be +accessed by other users on your system. The warning reads "Unsafe permissions +on credentials configuration file", followed by the path to the credentials +file. This warning will be emitted each time Certbot uses the credentials file, +including for renewal, and cannot be silenced except by addressing the issue +(e.g., by using a command like ``chmod 600`` to restrict access to the file). + + Examples -------- diff --git a/certbot-dns-dnsimple/certbot_dns_dnsimple/__init__.py b/certbot-dns-dnsimple/certbot_dns_dnsimple/__init__.py index 1f5a6cbe4..f8a2e83aa 100644 --- a/certbot-dns-dnsimple/certbot_dns_dnsimple/__init__.py +++ b/certbot-dns-dnsimple/certbot_dns_dnsimple/__init__.py @@ -16,6 +16,7 @@ Named Arguments (Default: 30) ======================================== ===================================== + Credentials ----------- @@ -42,6 +43,14 @@ to this file for use during renewal, but does not store the file's contents. new certificates or revoke existing certificates for associated domains, even if those domains aren't being managed by this server. +Certbot will emit a warning if it detects that the credentials file can be +accessed by other users on your system. The warning reads "Unsafe permissions +on credentials configuration file", followed by the path to the credentials +file. This warning will be emitted each time Certbot uses the credentials file, +including for renewal, and cannot be silenced except by addressing the issue +(e.g., by using a command like ``chmod 600`` to restrict access to the file). + + Examples -------- diff --git a/certbot-dns-google/certbot_dns_google/__init__.py b/certbot-dns-google/certbot_dns_google/__init__.py index 362c6d8ce..228adafcf 100644 --- a/certbot-dns-google/certbot_dns_google/__init__.py +++ b/certbot-dns-google/certbot_dns_google/__init__.py @@ -17,6 +17,7 @@ Named Arguments (Default: 60) ======================================== ===================================== + Credentials ----------- @@ -55,6 +56,14 @@ to this file for use during renewal, but does not store the file's contents. challenge to acquire new certificates or revoke existing certificates for domains these credentials are authorized to manage. +Certbot will emit a warning if it detects that the credentials file can be +accessed by other users on your system. The warning reads "Unsafe permissions +on credentials configuration file", followed by the path to the credentials +file. This warning will be emitted each time Certbot uses the credentials file, +including for renewal, and cannot be silenced except by addressing the issue +(e.g., by using a command like ``chmod 600`` to restrict access to the file). + + Examples -------- From 25d6369b04e9de0c9498af737d65c7aaeeec1cc3 Mon Sep 17 00:00:00 2001 From: Zach Shepherd Date: Thu, 8 Jun 2017 15:51:47 -0700 Subject: [PATCH 12/16] Add documentation for NS1 --- .../certbot_dns_nsone/__init__.py | 86 ++++++++++++++++++- 1 file changed, 85 insertions(+), 1 deletion(-) diff --git a/certbot-dns-nsone/certbot_dns_nsone/__init__.py b/certbot-dns-nsone/certbot_dns_nsone/__init__.py index 8c061edf7..e59be74a7 100644 --- a/certbot-dns-nsone/certbot_dns_nsone/__init__.py +++ b/certbot-dns-nsone/certbot_dns_nsone/__init__.py @@ -1 +1,85 @@ -"""NS1 DNS Authenticator""" +""" +The `~certbot_dns_nsone.dns_nsone` plugin automates the process of completing +a ``dns-01`` challenge (`~acme.challenges.DNS01`) by creating, and subsequently +removing, TXT records using the NS1 API. + + +Named Arguments +--------------- + +======================================== ===================================== +``--dns-nsone-credentials`` NS1 credentials_ INI file. + (Required) +``--dns-nsone-propagation-seconds`` The number of seconds to wait for DNS + to propagate before asking the ACME + server to verify the DNS record. + (Default: 30) +======================================== ===================================== + + +Credentials +----------- + +Use of this plugin requires a configuration file containing NS1 API credentials, +obtained from your NS1 +`account page `_. + +.. code-block:: ini + :name: credentials.ini + :caption: Example credentials file: + + # NS1 API credentials used by Certbot + dns_nsone_api_key = MDAwMDAwMDAwMDAwMDAw + +The path to this file can be provided interactively or using the +``--dns-nsone-credentials`` command-line argument. Certbot records the path +to this file for use during renewal, but does not store the file's contents. + +.. caution:: + You should protect these API credentials as you would the password to your + NS1 account. Users who can read this file can use these credentials to issue + arbitrary API calls on your behalf. Users who can cause Certbot to run using + these credentials can complete a ``dns-01`` challenge to acquire new + certificates or revoke existing certificates for associated domains, even if + those domains aren't being managed by this server. + +Certbot will emit a warning if it detects that the credentials file can be +accessed by other users on your system. The warning reads "Unsafe permissions +on credentials configuration file", followed by the path to the credentials +file. This warning will be emitted each time Certbot uses the credentials file, +including for renewal, and cannot be silenced except by addressing the issue +(e.g., by using a command like ``chmod 600`` to restrict access to the file). + + +Examples +-------- + +.. code-block:: bash + :caption: To acquire a certificate for ``example.com`` + + certbot certonly \\ + --dns-nsone \\ + --dns-nsone-credentials ~/.secrets/certbot/nsone.ini \\ + -d example.com + +.. code-block:: bash + :caption: To acquire a single certificate for both ``example.com`` and + ``www.example.com`` + + certbot certonly \\ + --dns-nsone \\ + --dns-nsone-credentials ~/.secrets/certbot/nsone.ini \\ + -d example.com \\ + -d www.example.com + +.. code-block:: bash + :caption: To acquire a certificate for ``example.com``, waiting 60 seconds + for DNS propagation + + certbot certonly \\ + --dns-nsone \\ + --dns-nsone-credentials ~/.secrets/certbot/nsone.ini \\ + --dns-nsone-propagation-seconds 60 \\ + -d example.com + +""" From de7e55688fc895c6e6bab4eb02d18fdc91fcba45 Mon Sep 17 00:00:00 2001 From: Zach Shepherd Date: Thu, 8 Jun 2017 15:56:38 -0700 Subject: [PATCH 13/16] fixup! Add documentation for Google --- certbot-dns-google/docs/_ext/jsonlexer.py | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) create mode 100644 certbot-dns-google/docs/_ext/jsonlexer.py diff --git a/certbot-dns-google/docs/_ext/jsonlexer.py b/certbot-dns-google/docs/_ext/jsonlexer.py new file mode 100644 index 000000000..1ad004d2b --- /dev/null +++ b/certbot-dns-google/docs/_ext/jsonlexer.py @@ -0,0 +1,16 @@ +"""Copied from https://stackoverflow.com/a/16863232""" + +def setup(app): + # enable Pygments json lexer + try: + import pygments + if pygments.__version__ >= '1.5': + # use JSON lexer included in recent versions of Pygments + from pygments.lexers import JsonLexer + else: + # use JSON lexer from pygments-json if installed + from pygson.json_lexer import JSONLexer as JsonLexer + except ImportError: + pass # not fatal if we have old (or no) Pygments and no pygments-json + else: + app.add_lexer('json', JsonLexer()) From c353fd349aacc37427d3779572c580d8041bd03a Mon Sep 17 00:00:00 2001 From: Zach Shepherd Date: Thu, 8 Jun 2017 16:13:13 -0700 Subject: [PATCH 14/16] fixup! Add documentation for Google --- certbot-dns-google/certbot_dns_google/__init__.py | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/certbot-dns-google/certbot_dns_google/__init__.py b/certbot-dns-google/certbot_dns_google/__init__.py index 228adafcf..a3667ca2a 100644 --- a/certbot-dns-google/certbot_dns_google/__init__.py +++ b/certbot-dns-google/certbot_dns_google/__init__.py @@ -30,10 +30,10 @@ Platform API credentials for an account with the following permissions: * ``dns.resourceRecordSets.create`` * ``dns.resourceRecordSets.delete`` -Google provides instructions for -`creating a service account `_ -and -`information about the required permissions `_. +Google provides instructions for `creating a service account `_ and +`information about the required permissions `_. .. code-block:: json :name: credentials.json @@ -96,3 +96,4 @@ Examples -d example.com """ +# pylint: disable=line-too-long From 5ee47e921038a37228fbe2567cecdf5a9be3df31 Mon Sep 17 00:00:00 2001 From: Zach Shepherd Date: Thu, 8 Jun 2017 16:19:30 -0700 Subject: [PATCH 15/16] fixup! Add documentation for CloudXNS --- certbot-dns-cloudxns/certbot_dns_cloudxns/__init__.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/certbot-dns-cloudxns/certbot_dns_cloudxns/__init__.py b/certbot-dns-cloudxns/certbot_dns_cloudxns/__init__.py index 6957b9cc3..6ddbdfe5a 100644 --- a/certbot-dns-cloudxns/certbot_dns_cloudxns/__init__.py +++ b/certbot-dns-cloudxns/certbot_dns_cloudxns/__init__.py @@ -8,7 +8,7 @@ Named Arguments --------------- ======================================== ===================================== -``--dns-cloudxns-credentials` ` CloudXNS credentials_ INI file. +``--dns-cloudxns-credentials`` CloudXNS credentials_ INI file. (Required) ``--dns-cloudxns-propagation-seconds`` The number of seconds to wait for DNS to propagate before asking the ACME From 3b3c878b117b7d62f27fa818d282c1fe68cd8a76 Mon Sep 17 00:00:00 2001 From: Zach Shepherd Date: Fri, 9 Jun 2017 12:06:49 -0700 Subject: [PATCH 16/16] fixup! fixup! Add documentation for Google --- certbot-dns-google/certbot_dns_google/__init__.py | 1 - 1 file changed, 1 deletion(-) diff --git a/certbot-dns-google/certbot_dns_google/__init__.py b/certbot-dns-google/certbot_dns_google/__init__.py index a3667ca2a..26685206c 100644 --- a/certbot-dns-google/certbot_dns_google/__init__.py +++ b/certbot-dns-google/certbot_dns_google/__init__.py @@ -96,4 +96,3 @@ Examples -d example.com """ -# pylint: disable=line-too-long