Clear up public key source handling docs

This commit clears up input types for x509_v2 certificate parameters
relating to the certificate's public key.

It also documents a breaking change versus the previous modules that was
forgotten about and can cause confusion. See:
#66889

Author: lkubb

salt/modules/x509_v2.py

@@ -118,6 +118,14 @@
 
 Breaking changes versus the previous ``x509`` modules
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+* The ``public_key`` parameter to ``x509.certificate_managed`` (and corresponding
+  ``x509.create_certificate``) used to accept a private key.
+  The new modules require an actual public key if this parameter is specified.
+  You can pass a private key in the ``private_key`` parameter instead.
+
+  Failing to ensure it really is a public key you are passing as ``public_key`` fails
+  with ``Could not load PEM-encoded public key.``.
+
 * The output format has changed for all ``read_*`` functions as well as the state return dict.
 * The formatting of some extension definitions might have changed, but should
   be stable for most basic use cases.
@@ -267,33 +275,48 @@ def create_certificate(
         The hashing algorithm to use for the signature. Valid values are:
         sha1, sha224, sha256, sha384, sha512, sha512_224, sha512_256, sha3_224,
         sha3_256, sha3_384, sha3_512. Defaults to ``sha256``.
-        This will be ignored for ``ed25519`` and ``ed448`` key types.
+        Ignored for ``ed25519`` and ``ed448`` key types.
 
     private_key
-        The private key corresponding to the public key the certificate should
-        be issued for. This is one way of specifying the public key that will
-        be included in the certificate, the other ones being ``public_key`` and ``csr``.
+        A **private key**, which is used to derive the public key the certificate
+        is issued for. If unset, checks ``public_key`` or ``csr`` to derive it.
+
+        Ignored when creating self-signed certificates (missing ``signing_cert``).
+
+        .. hint::
+            When ``encoding`` is ``pkcs12``, this private key is embedded into
+            the resulting container.
 
     private_key_passphrase
         If ``private_key`` is specified and encrypted, the passphrase to decrypt it.
 
     public_key
-        The public key the certificate should be issued for. Other ways of passing
-        the required information are ``private_key`` and ``csr``. If neither are set,
-        the public key of the ``signing_private_key`` will be included, i.e.
-        a self-signed certificate is generated.
+        A **public key**, which is used as the public key the certificate is issued for,
+        but only if ``private_key`` is **not** specified.
+
+        If this is unset, checks ``csr`` to derive it.
+
+        Ignored when creating self-signed certificates (missing ``signing_cert``).
 
     csr
-        A certificate signing request to use as a base for generating the certificate.
-        The following information will be respected, depending on configuration:
-        * public key
-        * extensions, if not otherwise specified (arguments, signing_policy)
+        A **certificate signing request** to use as a base for generating the certificate:
+
+        - Extensions not otherwise specified (arguments, signing_policy) are copied.
+        - If ``private_key`` and ``public_key`` are both unspecified, copies the embedded
+          public key into the certificate. This step is skipped when creating self-signed
+          certificates (missing ``signing_cert``).
 
     signing_cert
         The CA certificate to be used for signing the issued certificate.
 
+        Leave empty to create a self-signed certificate.
+
     signing_private_key
-        The private key corresponding to the public key in ``signing_cert``. Required.
+        The private key to be used for signing the new certificate. Required.
+
+        Usually, this is the private key corresponding to the public key in ``signing_cert``.
+        When creating self-signed certificates (missing ``signing_cert``), derives
+        the new certificate's embedded public key from this private key.
 
     signing_private_key_passphrase
         If ``signing_private_key`` is encrypted, the passphrase to decrypt it.
@@ -385,10 +408,9 @@ def create_certificate(
 
             .. code-block:: yaml
 
-                # mind this being a list, not a dict
                 - subjectAltName:
-                    - email:me@example.com
-                    - DNS:example.com
+                    - email:me@example.com  # list items can be strings
+                    - dns: example.com      # or single-key dicts
 
         issuerAltName
             The syntax is the same as for ``subjectAltName``, except that the additional
@@ -846,7 +868,7 @@ def create_crl(
         The hashing algorithm to use for the signature. Valid values are:
         sha1, sha224, sha256, sha384, sha512, sha512_224, sha512_256, sha3_224,
         sha3_256, sha3_384, sha3_512. Defaults to ``sha256``.
-        This will be ignored for ``ed25519`` and ``ed448`` key types.
+        Ignored for ``ed25519`` and ``ed448`` key types.
 
     encoding
         Specify the encoding of the resulting certificate revocation list.
@@ -1059,7 +1081,7 @@ def create_csr(
         The hashing algorithm to use for the signature. Valid values are:
         sha1, sha224, sha256, sha384, sha512, sha512_224, sha512_256, sha3_224,
         sha3_256, sha3_384, sha3_512. Defaults to ``sha256``.
-        This will be ignored for ``ed25519`` and ``ed448`` key types.
+        Ignored for ``ed25519`` and ``ed448`` key types.
 
     encoding
         Specify the encoding of the resulting certificate signing request.

salt/states/x509_v2.py

@@ -249,7 +249,7 @@ def certificate_managed(
     Ensure an X.509 certificate is present as specified.
 
     This function accepts the same arguments as :py:func:`x509.create_certificate <salt.modules.x509_v2.create_certificate>`,
-    as well as most ones for `:py:func:`file.managed <salt.states.file.managed>`.
+    as well as most ones for :py:func:`file.managed <salt.states.file.managed>`.
 
     name
         The path the certificate should be present at.
@@ -295,37 +295,49 @@ def certificate_managed(
         The hashing algorithm to use for the signature. Valid values are:
         sha1, sha224, sha256, sha384, sha512, sha512_224, sha512_256, sha3_224,
         sha3_256, sha3_384, sha3_512. Defaults to ``sha256``.
-        This will be ignored for ``ed25519`` and ``ed448`` key types.
+        Ignored for ``ed25519`` and ``ed448`` key types.
+
+    signing_cert
+        The CA certificate to be used for signing the issued certificate.
+
+        Leave empty to create a self-signed certificate.
 
     signing_private_key
-        The private key corresponding to the public key in ``signing_cert``. Required.
+        The private key to be used for signing the new certificate. Required.
+
+        Usually, this is the private key corresponding to the public key in ``signing_cert``.
+        When creating self-signed certificates (missing ``signing_cert``), derives
+        the new certificate's embedded public key from this private key.
 
     signing_private_key_passphrase
         If ``signing_private_key`` is encrypted, the passphrase to decrypt it.
 
-    signing_cert
-        The CA certificate to be used for signing the issued certificate.
+    private_key
+        A **private key**, which is used to derive the public key the certificate
+        is issued for. If this is unset, checks ``public_key`` or ``csr`` to derive it.
 
-    public_key
-        The public key the certificate should be issued for. Other ways of passing
-        the required information are ``private_key`` and ``csr``. If neither are set,
-        the public key of the ``signing_private_key`` will be included, i.e.
-        a self-signed certificate is generated.
+        Ignored when creating self-signed certificates (missing ``signing_cert``).
 
-    private_key
-        The private key corresponding to the public key the certificate should
-        be issued for. This is one way of specifying the public key that will
-        be included in the certificate, the other ones being ``public_key`` and ``csr``.
+        .. hint::
+            When ``encoding`` is ``pkcs12``, this private key is embedded into
+            the resulting container.
 
     private_key_passphrase
         If ``private_key`` is specified and encrypted, the passphrase to decrypt it.
 
+    public_key
+        A **public key**, which is used as the public key the certificate is issued for,
+        but only if ``private_key`` is **not** specified. If this is unset, checks ``csr`` to derive it.
+
+        Ignored when creating self-signed certificates (missing ``signing_cert``).
+
     csr
-        A certificate signing request to use as a base for generating the certificate.
-        The following information will be respected, depending on configuration:
+        A **certificate signing request** to use as a base for generating the certificate:
 
-        * public key
-        * extensions, if not otherwise specified (arguments, signing_policy)
+        - Extensions not otherwise specified (arguments, signing_policy) are copied.
+        - If ``private_key`` and ``public_key`` are both unspecified, copies the embedded
+          public key into the certificate. This step is skipped when creating self-signed
+          certificates (missing ``signing_cert``).
 
     subject
         The subject's distinguished name embedded in the certificate. This is one way of
@@ -740,7 +752,7 @@ def crl_managed(
         The hashing algorithm to use for the signature. Valid values are:
         sha1, sha224, sha256, sha384, sha512, sha512_224, sha512_256, sha3_224,
         sha3_256, sha3_384, sha3_512. Defaults to ``sha256``.
-        This will be ignored for ``ed25519`` and ``ed448`` key types.
+        Ignored for ``ed25519`` and ``ed448`` key types.
 
     encoding
         Specify the encoding of the resulting certificate revocation list.
@@ -1045,7 +1057,7 @@ def csr_managed(
         The hashing algorithm to use for the signature. Valid values are:
         sha1, sha224, sha256, sha384, sha512, sha512_224, sha512_256, sha3_224,
         sha3_256, sha3_384, sha3_512. Defaults to ``sha256``.
-        This will be ignored for ``ed25519`` and ``ed448`` key types.
+        Ignored for ``ed25519`` and ``ed448`` key types.
 
     encoding
         Specify the encoding of the resulting certificate revocation list.