ansible-collections/community.general
1
0
Fork 0
mirror of https://github.com/ansible-collections/community.general.git synced 2025-07-22 21:00:22 -07:00
Code Issues Projects Releases Packages Wiki Activity Actions 2

ACME: improve documentation (#44691)

Browse source 
* Override description for account_key_src and account_key_content to also mention private_key_*.

* Convert generic OpenSSL/cryptography remark from description to note.

This avoids the whole description list to be sorted alphabetically, which will be done by plugin_docs.py in case description is mentioned in both module fragment and module itself.

* Moving more notes to the notes: section.

* Uniformization of first paragraph. Mainly mention ACME supporting CAs, and only then mention Let's Encrypt as one of them.

* Adjusting to current drafts.

* Adjusting to updated drafts.

* Harmonizing short module descriptions.

* Referencing helper modules.

* Move general Let's Encrypt remark to doc fragment.

* Changing some Let's Encrypt references to more generic statements.
This commit is contained in:
Felix Fontein 2018-08-26 22:46:55 +02:00 • committed by René Moser
commit fadf8a2d09
6 changed files with 86 additions and 56 deletions
Download patch file Download diff file Expand all files Collapse all files

27
lib/ansible/modules/crypto/acme/acme_account.py
View file

@ -18,16 +18,19 @@ DOCUMENTATION = '''
module: acme_account
author: "Felix Fontein (@felixfontein)"
version_added: "2.6"
short_description: Create, modify or delete accounts with Let's Encrypt
short_description: Create, modify or delete ACME accounts
description:
- "Allows to create, modify or delete accounts with Let's Encrypt.
Let's Encrypt is a free, automated, and open certificate authority
(CA), run for the public's benefit. For details see U(https://letsencrypt.org)."
- "Allows to create, modify or delete accounts with a CA supporting the
L(ACME protocol,https://tools.ietf.org/html/draft-ietf-acme-acme-14),
such as L(Let's Encrypt,https://letsencrypt.org/)."
- "This module only works with the ACME v2 protocol."
notes:
- "Facts about an ACME account can be retrieved with the M(acme_account_facts)
module."
- "The M(acme_certificate) module also allows to do basic account management.
When using both modules, it is recommended to disable account management
for M(acme_certificate). For that, use the C(modify_account) option of
M(acme_certificate)."
- "This module only works with the ACME v2 protocol."
extends_documentation_fragment:
- acme
options:
@ -52,7 +55,7 @@ options:
description:
- "A list of contact URLs."
- "Email addresses must be prefixed with C(mailto:)."
- "See https://tools.ietf.org/html/draft-ietf-acme-acme-12#section-7.1.2
- "See https://tools.ietf.org/html/draft-ietf-acme-acme-14#section-7.1.2
for what is allowed."
- "Must be specified when state is C(present). Will be ignored
if state is C(absent) or C(changed_key)."
@ -65,14 +68,13 @@ options:
type: bool
new_account_key_src:
description:
- "Path to a file containing the Let's Encrypt account RSA or Elliptic Curve
key to change to."
- "Path to a file containing the ACME account RSA or Elliptic Curve key to change to."
- "Same restrictions apply as to C(account_key_src)."
- "Mutually exclusive with C(new_account_key_content)."
- "Required if C(new_account_key_content) is not used and state is C(changed_key)."
new_account_key_content:
description:
- "Content of the Let's Encrypt account RSA or Elliptic Curve key to change to."
- "Content of the ACME account RSA or Elliptic Curve key to change to."
- "Same restrictions apply as to C(account_key_content)."
- "Mutually exclusive with C(new_account_key_src)."
- "Required if C(new_account_key_src) is not used and state is C(changed_key)."
@ -221,7 +223,7 @@ def main():
# Now we can start the account key rollover
if not module.check_mode:
# Compose inner signed message
# https://tools.ietf.org/html/draft-ietf-acme-acme-12#section-7.3.6
# https://tools.ietf.org/html/draft-ietf-acme-acme-14#section-7.3.6
url = account.directory['keyChange']
protected = {
"alg": new_key_data['alg'],
@ -230,9 +232,8 @@ def main():
}
payload = {
"account": account.uri,
"newKey": new_key_data['jwk'], # specified in draft 12
"oldKey": account.jwk, # discussed in https://github.com/ietf-wg-acme/acme/pull/425,
# might be required in draft 13
"newKey": new_key_data['jwk'], # specified in draft 12 and older
"oldKey": account.jwk, # specified in draft 13 and newer
}
data = account.sign_request(protected, payload, new_key_data)
# Send request and verify result