[2.9] crypto modules: improve return value list documentation (#63409)

* crypto modules: improve return value list documentation (#62929)

* Improve return value documentation by allowing entry for return values.
* Add docs formatting, adjust styling.
* Fix sample return value. (Taken from https://tools.ietf.org/html/rfc7517#appendix-A.1.)
* Work around abuse of .

(cherry picked from commit 054285c34c)

* Add changelog.

changelogs/fragments/62929-module-return-value-elements.yml

@@ -0,0 +1,2 @@
+minor_changes:
+- "ansible-test - module validation now allows ``elements:`` for return value documentation."

docs/templates/plugin.rst.j2

@@ -288,7 +288,10 @@ Facts returned by this module are added/updated in the ``hostvars`` host facts a
                 {% endfor %}
                 <td colspan="@{ from_kludge_ns('maxdepth') - loop.depth0 }@" colspan="@{ from_kludge_ns('maxdepth') - loop.depth0 }@">
                     <b>@{ key }@</b>
-                    <div style="font-size: small; color: purple">@{ value.type | documented_type }@</div>
+                    <div style="font-size: small">
+                      <span style="color: purple">@{ value.type | documented_type }@</span>
+                      {% if value.elements %} / <span style="color: purple">elements=@{ value.elements | documented_type }@</span>{% endif %}
+                    </div>
                     {% if value.version_added %}<div style="font-style: italic; font-size: small; color: darkgreen">added in @{value.version_added}@</div>{% endif %}
                 </td>
                 <td>@{ value.returned | html_ify }@</td>
@@ -360,7 +363,10 @@ Common return values are documented :ref:`here <common_return_values>`, the foll
                 {% endfor %}
                 <td colspan="@{ from_kludge_ns('maxdepth') - loop.depth0 }@">
                     <b>@{ key }@</b>
-                    <div style="font-size: small; color: purple">@{ value.type | documented_type }@</div>
+                    <div style="font-size: small">
+                      <span style="color: purple">@{ value.type | documented_type }@</span>
+                      {% if value.elements %} / <span style="color: purple">elements=@{ value.elements | documented_type }@</span>{% endif %}
+                    </div>
                     {% if value.version_added %}<div style="font-style: italic; font-size: small; color: darkgreen">added in @{value.version_added}@</div>{% endif %}
                 </td>
                 <td>@{ value.returned | html_ify }@</td>

lib/ansible/modules/crypto/acme/acme_account_info.py

@@ -91,12 +91,13 @@ account_uri:
 account:
   description: The account information, as retrieved from the ACME server.
   returned: if account exists
-  type: complex
+  type: dict
   contains:
     contact:
       description: the challenge resource that must be created for validation
       returned: always
       type: list
+      elements: str
       sample: "['mailto:me@example.com', 'tel:00123456789']"
     status:
       description: the account's status
@@ -116,7 +117,7 @@ account:
       description: the public account key as a L(JSON Web Key,https://tools.ietf.org/html/rfc7517).
       returned: always
       type: str
-      sample: https://example.ca/account/1/orders
+      sample: '{"kty":"EC","crv":"P-256","x":"MKBCTNIcKUSDii11ySs3526iDZ8AiTo7Tu6KPAqv7D4","y":"4Etl6SRW2YiLUrN5vfvVHuhp7x8PxltmWWlbbM4IFyM"}'
 
 orders:
   description:
@@ -124,6 +125,7 @@ orders:
     - "If I(retrieve_orders) is C(url_list), this will be a list of URLs."
     - "If I(retrieve_orders) is C(object_list), this will be a list of objects."
   type: list
+  #elements: ... depends on retrieve_orders
   returned: if account exists, I(retrieve_orders) is not C(ignore), and server supports order listing
   contains:
     status:
@@ -146,6 +148,7 @@ orders:
       description:
         - List of identifiers this order is for.
       type: list
+      elements: dict
       contains:
         type:
           description: Type of identifier. C(dns) or C(ip).
@@ -176,12 +179,13 @@ orders:
       description:
         - In case an error occurred during processing, this contains information about the error.
         - The field is structured as a problem document (RFC7807).
-      type: complex
+      type: dict
       returned: when an error occurred
     authorizations:
       description:
         - A list of URLs for authorizations for this order.
       type: list
+      elements: str
     finalize:
       description:
         - A URL used for finalizing an ACME order.

lib/ansible/modules/crypto/acme/acme_certificate.py

@@ -324,7 +324,8 @@ challenge_data:
     - Per identifier / challenge type challenge data.
     - Since Ansible 2.8.5, only challenges which are not yet valid are returned.
   returned: changed
-  type: complex
+  type: list
+  elements: dict
   contains:
     resource:
       description: The challenge resource that must be created for validation.
@@ -366,14 +367,12 @@ challenge_data_dns:
   type: dict
   version_added: "2.5"
 authorizations:
-  description: ACME authorization data.
+  description:
+    - ACME authorization data.
+    - Maps an identifier to ACME authorization objects. See U(https://tools.ietf.org/html/rfc8555#section-7.1.4).
   returned: changed
-  type: complex
-  contains:
-      authorization:
-        description: ACME authorization object. See U(https://tools.ietf.org/html/rfc8555#section-7.1.4)
-        returned: success
-        type: dict
+  type: dict
+  sample: '{"example.com":{...}}'
 order_uri:
   description: ACME order URI.
   returned: changed
@@ -397,6 +396,7 @@ all_chains:
     - See L(Section 7.4.2 of RFC8555,https://tools.ietf.org/html/rfc8555#section-7.4.2) for details.
   returned: when certificate was retrieved and I(retrieve_all_alternates) is set to C(yes)
   type: list
+  elements: dict
   contains:
     cert:
       description:

lib/ansible/modules/crypto/certificate_complete_chain.py

@@ -114,12 +114,14 @@ chain:
         - "Returned as a list of PEM certificates."
     returned: success
     type: list
+    elements: str
 complete_chain:
     description:
         - "The completed chain, including leaf, all intermediates, and root."
         - "Returned as a list of PEM certificates."
     returned: success
     type: list
+    elements: str
 '''
 
 import os

lib/ansible/modules/crypto/get_certificate.py

@@ -86,6 +86,20 @@ extensions:
     description: Extensions applied to the cert
     returned: success
     type: list
+    elements: dict
+    contains:
+        critical:
+            returned: success
+            type: bool
+            description: Whether the extension is critical.
+        asn1_data:
+            returned: success
+            type: str
+            description: The Base64 encoded ASN.1 content of the extnesion.
+        name:
+            returned: success
+            type: str
+            description: The extension's name.
 issuer:
     description: Information about the issuer of the cert
     returned: success

lib/ansible/modules/crypto/openssh_cert.py

@@ -193,6 +193,7 @@ info:
     description: Information about the certificate. Output of C(ssh-keygen -L -f).
     returned: change or success
     type: list
+    elements: str
 
 '''
 

lib/ansible/modules/crypto/openssl_certificate_info.py

@@ -116,6 +116,7 @@ basic_constraints:
     description: Entries in the C(basic_constraints) extension, or C(none) if extension is not present.
     returned: success
     type: list
+    elements: str
     sample: "[CA:TRUE, pathlen:1]"
 basic_constraints_critical:
     description: Whether the C(basic_constraints) extension is critical.
@@ -125,6 +126,7 @@ extended_key_usage:
     description: Entries in the C(extended_key_usage) extension, or C(none) if extension is not present.
     returned: success
     type: list
+    elements: str
     sample: "[Biometric Info, DVCS, Time Stamping]"
 extended_key_usage_critical:
     description: Whether the C(extended_key_usage) extension is critical.
@@ -133,7 +135,7 @@ extended_key_usage_critical:
 extensions_by_oid:
     description: Returns a dictionary for every extension OID
     returned: success
-    type: complex
+    type: dict
     contains:
         critical:
             description: Whether the extension is critical.
@@ -158,6 +160,7 @@ subject_alt_name:
     description: Entries in the C(subject_alt_name) extension, or C(none) if extension is not present.
     returned: success
     type: list
+    elements: str
     sample: "[DNS:www.ansible.com, IP:1.2.3.4]"
 subject_alt_name_critical:
     description: Whether the C(subject_alt_name) extension is critical.
@@ -182,6 +185,7 @@ issuer_ordered:
     description: The certificate's issuer as an ordered list of tuples.
     returned: success
     type: list
+    elements: list
     sample: '[["organizationName", "Ansible"], ["commonName": "ca.example.com"]]'
     version_added: "2.9"
 subject:
@@ -195,6 +199,7 @@ subject_ordered:
     description: The certificate's subject as an ordered list of tuples.
     returned: success
     type: list
+    elements: list
     sample: '[["commonName", "www.example.com"], ["emailAddress": "test@example.com"]]'
     version_added: "2.9"
 not_after:
@@ -265,6 +270,7 @@ authority_cert_issuer:
         - Is C(none) if the C(AuthorityKeyIdentifier) extension is not present.
     returned: success and if the pyOpenSSL backend is I(not) used
     type: list
+    elements: str
     sample: "[DNS:www.ansible.com, IP:1.2.3.4]"
     version_added: "2.9"
 authority_cert_serial_number:

lib/ansible/modules/crypto/openssl_csr.py

@@ -365,26 +365,31 @@ subject:
     description: A list of the subject tuples attached to the CSR
     returned: changed or success
     type: list
+    elements: list
     sample: "[('CN', 'www.ansible.com'), ('O', 'Ansible')]"
 subjectAltName:
     description: The alternative names this CSR is valid for
     returned: changed or success
     type: list
+    elements: str
     sample: [ 'DNS:www.ansible.com', 'DNS:m.ansible.com' ]
 keyUsage:
     description: Purpose for which the public key may be used
     returned: changed or success
     type: list
+    elements: str
     sample: [ 'digitalSignature', 'keyAgreement' ]
 extendedKeyUsage:
     description: Additional restriction on the public key purposes
     returned: changed or success
     type: list
+    elements: str
     sample: [ 'clientAuth' ]
 basicConstraints:
     description: Indicates if the certificate belongs to a CA
     returned: changed or success
     type: list
+    elements: str
     sample: ['CA:TRUE', 'pathLenConstraint:0']
 ocsp_must_staple:
     description: Indicates whether the certificate has the OCSP

lib/ansible/modules/crypto/openssl_csr_info.py

@@ -82,6 +82,7 @@ basic_constraints:
     description: Entries in the C(basic_constraints) extension, or C(none) if extension is not present.
     returned: success
     type: list
+    elements: str
     sample: "[CA:TRUE, pathlen:1]"
 basic_constraints_critical:
     description: Whether the C(basic_constraints) extension is critical.
@@ -91,6 +92,7 @@ extended_key_usage:
     description: Entries in the C(extended_key_usage) extension, or C(none) if extension is not present.
     returned: success
     type: list
+    elements: str
     sample: "[Biometric Info, DVCS, Time Stamping]"
 extended_key_usage_critical:
     description: Whether the C(extended_key_usage) extension is critical.
@@ -99,7 +101,7 @@ extended_key_usage_critical:
 extensions_by_oid:
     description: Returns a dictionary for every extension OID
     returned: success
-    type: complex
+    type: dict
     contains:
         critical:
             description: Whether the extension is critical.
@@ -124,6 +126,7 @@ subject_alt_name:
     description: Entries in the C(subject_alt_name) extension, or C(none) if extension is not present.
     returned: success
     type: list
+    elements: str
     sample: "[DNS:www.ansible.com, IP:1.2.3.4]"
 subject_alt_name_critical:
     description: Whether the C(subject_alt_name) extension is critical.
@@ -148,6 +151,7 @@ subject_ordered:
     description: The CSR's subject as an ordered list of tuples.
     returned: success
     type: list
+    elements: list
     sample: '[["commonName", "www.example.com"], ["emailAddress": "test@example.com"]]'
     version_added: "2.9"
 public_key:
@@ -187,6 +191,7 @@ authority_cert_issuer:
         - Is C(none) if the C(AuthorityKeyIdentifier) extension is not present.
     returned: success and if the pyOpenSSL backend is I(not) used
     type: list
+    elements: str
     sample: "[DNS:www.ansible.com, IP:1.2.3.4]"
     version_added: "2.9"
 authority_cert_serial_number:

test/lib/ansible_test/_data/sanity/validate-modules/validate_modules/schema.py

@@ -142,6 +142,8 @@ return_schema = Any(
                     'sample': Any(None, list, dict, int, float, *string_types),
                     'example': Any(None, list, dict, int, float, *string_types),
                     'contains': object,
+                    # in case of type='list' elements define type of individual item in list
+                    'elements': Any(None, 'bits', 'bool', 'bytes', 'dict', 'float', 'int', 'json', 'jsonarg', 'list', 'path', 'raw', 'sid', 'str'),
                 }
             }
         ),