Add conversion filters for serial numbers (#713)

* Refactoring.

* Add parse_filter and to_filter plugins.

* Mention filters when serial numbers are accepted or returned.

plugins/modules/ecs_certificate.py

@@ -350,6 +350,8 @@ seealso:
       description: Can be used to create private keys (both for certificates and accounts).
     - module: community.crypto.openssl_csr
       description: Can be used to create a Certificate Signing Request (CSR).
+    - plugin: community.crypto.to_serial
+      plugin_type: filter
 '''
 
 EXAMPLES = r'''
@@ -490,7 +492,10 @@ tracking_id:
     type: int
     sample: 380079
 serial_number:
-    description: The serial number of the issued certificate.
+    description:
+        - The serial number of the issued certificate.
+        - This return value is an B(integer). If you need the serial numbers as a colon-separated hex string,
+          such as C(11:22:33), you need to convert it to that form with P(community.crypto.to_serial#filter).
     returned: success
     type: int
     sample: 1235262234164342

plugins/modules/get_certificate.py

@@ -106,6 +106,10 @@ notes:
 requirements:
     - "python >= 2.7 when using O(proxy_host)"
     - "cryptography >= 1.6"
+
+seealso:
+    - plugin: community.crypto.to_serial
+      plugin_type: filter
 '''
 
 RETURN = '''
@@ -147,31 +151,34 @@ extensions:
             type: str
             description: The extension's name.
 issuer:
-    description: Information about the issuer of the cert
+    description: Information about the issuer of the cert.
     returned: success
     type: dict
 not_after:
-    description: Expiration date of the cert
+    description: Expiration date of the cert.
     returned: success
     type: str
 not_before:
-    description: Issue date of the cert
+    description: Issue date of the cert.
     returned: success
     type: str
 serial_number:
-    description: The serial number of the cert
+    description:
+        - The serial number of the cert.
+        - This return value is an B(integer). If you need the serial numbers as a colon-separated hex string,
+          such as C(11:22:33), you need to convert it to that form with P(community.crypto.to_serial#filter).
     returned: success
-    type: str
+    type: int
 signature_algorithm:
-    description: The algorithm used to sign the cert
+    description: The algorithm used to sign the cert.
     returned: success
     type: str
 subject:
-    description: Information about the subject of the cert (OU, CN, etc)
+    description: Information about the subject of the cert (C(OU), C(CN), etc).
     returned: success
     type: dict
 version:
-    description: The version number of the certificate
+    description: The version number of the certificate.
     returned: success
     type: str
 '''

plugins/modules/openssh_cert.py

@@ -190,7 +190,13 @@ options:
                The certificate serial number may be used in a KeyRevocationList.
                The serial number may be omitted for checks, but must be specified again for a new certificate.
                Note: The default value set by ssh-keygen is 0."
+            - This option accepts an B(integer). If you want to provide serial numbers as colon-separated hex strings,
+              such as C(11:22:33), you need to convert them to an integer with P(community.crypto.parse_serial#filter).
         type: int
+
+seealso:
+    - plugin: community.crypto.parse_serial
+      plugin_type: filter
 '''
 
 EXAMPLES = '''

plugins/modules/openssl_csr_info.py

@@ -55,6 +55,8 @@ seealso:
     - plugin: community.crypto.openssl_csr_info
       plugin_type: filter
       description: A filter variant of this module.
+    - plugin: community.crypto.to_serial
+      plugin_type: filter
 '''
 
 EXAMPLES = r'''
@@ -301,6 +303,8 @@ authority_cert_serial_number:
     description:
         - The CSR's authority cert serial number.
         - Is V(none) if the C(AuthorityKeyIdentifier) extension is not present.
+        - This return value is an B(integer). If you need the serial numbers as a colon-separated hex string,
+          such as C(11:22:33), you need to convert it to that form with P(community.crypto.to_serial#filter).
     returned: success
     type: int
     sample: 12345

plugins/modules/x509_certificate_info.py

@@ -77,6 +77,8 @@ seealso:
     - plugin: community.crypto.x509_certificate_info
       plugin_type: filter
       description: A filter variant of this module.
+    - plugin: community.crypto.to_serial
+      plugin_type: filter
 '''
 
 EXAMPLES = r'''
@@ -330,7 +332,10 @@ signature_algorithm:
     type: str
     sample: sha256WithRSAEncryption
 serial_number:
-    description: The certificate's serial number.
+    description:
+        - The certificate's serial number.
+        - This return value is an B(integer). If you need the serial numbers as a colon-separated hex string,
+          such as C(11:22:33), you need to convert it to that form with P(community.crypto.to_serial#filter).
     returned: success
     type: int
     sample: 1234
@@ -374,6 +379,8 @@ authority_cert_serial_number:
     description:
         - The certificate's authority cert serial number.
         - Is V(none) if the C(AuthorityKeyIdentifier) extension is not present.
+        - This return value is an B(integer). If you need the serial numbers as a colon-separated hex string,
+          such as C(11:22:33), you need to convert it to that form with P(community.crypto.to_serial#filter).
     returned: success
     type: int
     sample: 12345

plugins/modules/x509_crl.py

@@ -193,6 +193,8 @@ options:
                     - Mutually exclusive with O(revoked_certificates[].path) and
                       O(revoked_certificates[].content). One of these three options must
                       be specified.
+                    - This option accepts an B(integer). If you want to provide serial numbers as colon-separated hex strings,
+                      such as C(11:22:33), you need to convert them to an integer with P(community.crypto.parse_serial#filter).
                 type: int
             revocation_date:
                 description:
@@ -271,6 +273,12 @@ options:
 notes:
     - All ASN.1 TIME values should be specified following the YYYYMMDDHHMMSSZ pattern.
     - Date specified should be UTC. Minutes and seconds are mandatory.
+
+seealso:
+    - plugin: community.crypto.parse_serial
+      plugin_type: filter
+    - plugin: community.crypto.to_serial
+      plugin_type: filter
 '''
 
 EXAMPLES = r'''
@@ -356,7 +364,10 @@ revoked_certificates:
     elements: dict
     contains:
         serial_number:
-            description: Serial number of the certificate.
+            description:
+                - Serial number of the certificate.
+                - This return value is an B(integer). If you need the serial numbers as a colon-separated hex string,
+                  such as C(11:22:33), you need to convert it to that form with P(community.crypto.to_serial#filter).
             type: int
             sample: 1234
         revocation_date:

plugins/modules/x509_crl_info.py

@@ -53,6 +53,8 @@ seealso:
     - plugin: community.crypto.x509_crl_info
       plugin_type: filter
       description: A filter variant of this module.
+    - plugin: community.crypto.to_serial
+      plugin_type: filter
 '''
 
 EXAMPLES = r'''
@@ -118,7 +120,10 @@ revoked_certificates:
     elements: dict
     contains:
         serial_number:
-            description: Serial number of the certificate.
+            description:
+                - Serial number of the certificate.
+                - This return value is an B(integer). If you need the serial numbers as a colon-separated hex string,
+                  such as C(11:22:33), you need to convert it to that form with P(community.crypto.to_serial#filter).
             type: int
             sample: 1234
         revocation_date: