Updated system_local_ca_cert` and `system_local_ca_key parameters

Updates for r9: https://review.opendev.org/c/starlingx/docs/+/923875
Change-Id: I587c01c04a0b504a9a61819ff15c869e05c25a88
Signed-off-by: Juanita Balaraj <juanita.balaraj@windriver.com>

doc/source/introduction/terms.rst

@@ -62,6 +62,11 @@ commonly used in the |org| community and in this documentation.
      Tools that make the process of distributing, installing, and managing
      updates.
 
+   Elliptic Curve Digital Signature Algorithm (ECDSA)
+
+     ECDSA is an asymmetric key encryption algorithm that uses Elliptic curve
+     cryptography to produce keys and sign data.
+
    Edge Computing
      The delivery of computing capabilities to the logical extremes of a
      network in order to improve the performance, operating cost and

doc/source/security/kubernetes/migrate-platform-certificates-to-use-cert-manager-c0b1727e4e5d.rst

@@ -1,7 +1,6 @@
 .. Greg updates required for -High Security Vulnerability Document Updates
 .. Is this the target file that the rest of the updates need to point to??
 
-
 .. _migrate-platform-certificates-to-use-cert-manager-c0b1727e4e5d:
 
 ===========================================================================
@@ -86,23 +85,86 @@ playbook are:
                 # Sudo password
                 ansible_become_pass: <sysadmin-passwd>
 
-
     The inventory parameters have the following meanings:
 
     ``system_local_ca_cert`` and ``system_local_ca_key``
-        Both values being the single-line base64 encoding of the corresponding
+
+        Platform issuer (system-local-ca) public certificate and private key
+        pair, both values being the single-line base64 encoding of the corresponding
         pem file; i.e. the output of :command:`base64 -w0 <pem-file>`.
 
         It is highly recommended that you use an Intermediate |CA|
-        ``system-local-ca``, where the ``system-local-ca``'s certificate and
+        ``system-local-ca``, where the ``system-local-ca``'s certificate is
-        key are generated and signed by an external trusted Root |CA|.  Refer
+        generated and signed by an external trusted Root |CA|.  Refer
         to the documentation for the external trusted Root |CA| that you are
-        using, on how to create a public certificate and private key pair, for
+        using, on how to create an Intermediate |CA| public certificate and
-        use in an Intermediate |CA|.
+        private key pair.
 
-        The duration of the Intermediate CA public certificate and private key
+        The 'system_local_ca_cert' override must provide either:
-        pair should be at least 3 years.  See *rca_duration/ica_duration* to
+
-        modify this semantic check.
+        - A single certificate, directly signed by the Root |CA|; or
+
+        - A bundle of Intermediate |CA| certificates where every certificate is
+          signed by the next one, starting with ``system-local-ca``'s public
+          certificate and ending with the Intermediate |CA| certificate that is
+          directly signed by the Root |CA| certificate. The Root |CA| should not
+          be included in this bundle.
+
+        The ``system_local_ca_key`` override must provide only the private
+        key for ``system-local-ca``. Only RSA and |ECDSA| keys are supported.
+
+        The duration of the Intermediate |CA| public certificate should be at
+        least 3 years. See *ica_duration* to modify this semantic check.
+
+        .. warning::
+
+            The private key for ``system-local-ca`` should be handled carefully,
+            avoiding any possibility of transference between the cluster and
+            the external |CA|.
+
+        .. note::
+
+            It is recommended that the private key is generated locally and
+            used to create a Certificate Signing Request (CSR). The |CSR| and
+            its challenge password should be exchanged securely with the
+            external |CA| to obtain the signed public certificate for the
+            Intermediate |CA|, while the private key is never transferred.
+
+        Using OpenSSL, the private key and the |CSR| can be generated via
+        the CLI using the following command:
+
+        .. code-block::
+
+            $ openssl req -newkey rsa:4096 -keyout private_key.key -out cert.csr
+
+        You will be prompted to fill the certificate subject fields and to
+        provide a challenge password. Refer to your external |CA| to generate
+        an Intermediate |CA| public certificate that matches this private key
+        that can be used to issue the internal platform certificates. The
+        certificate should have the following extensions:
+
+        .. code-block::
+
+            subjectKeyIdentifier = hash
+            authorityKeyIdentifier = keyid:always,issuer
+            basicConstraints = critical, CA:true
+            keyUsage = critical, digitalSignature, cRLSign, keyCertSign
+
+        For example, if you are running a private |PKI|, you can generate
+        the Intermediate |CA| certificate ``cert.pem`` from ``cert.csr``
+        using the following extensions:
+
+        .. code-block::
+
+            cat <<eof> extensions.conf
+            [v3_req]
+            subjectKeyIdentifier = hash
+            authorityKeyIdentifier = keyid:always,issuer
+            basicConstraints = critical, CA:true
+            keyUsage = critical, digitalSignature, cRLSign, keyCertSign
+            eof
+
+            $ openssl x509 -req -CA <CA-certificate-path> -CAkey <CA-private-key> -days <expiration-days> -in cert.csr -out cert.pem -extensions v3_req -extfile extensions.conf
 
     ``system_root_ca_cert``
         The public certificate of the Root |CA| that signed

doc/source/shared/abbrevs.txt

@@ -38,6 +38,7 @@
 .. |CSIs| replace:: :abbr:`CSIs (Container Storage Interfaces)`
 .. |CSK| replace:: :abbr:`CSK (Code Signing Key)`
 .. |CSKs| replace:: :abbr:`CSKs (Code Signing Keys)`
+.. |CSR| replace:: :abbr:`CSR (Certificate Signing Request)`
 .. |CSV| replace:: :abbr:`CSV (Comma-Separated Values)`
 .. |CVE| replace:: :abbr:`CVE (Common Vulnerabilities and Exposures)`
 .. |CVSS| replace:: :abbr:`CVSS (Common Vulnerability Scoring System)`
@@ -62,6 +63,7 @@
 .. |DVR| replace:: :abbr:`DVR (Distributed Virtual Router)`
 .. |DWQ| replace:: abbr:`DWQ (Dedicated Work Queue)`
 .. |EMS| replace:: :abbr:`EMS (Element Management System)`
+.. |ECDSA| replace:: :abbr:`ECDSA (Elliptic Curve Digital Signature Algorithm)`
 .. |ePRTC| replace:: :abbr:`ePRTC (Enhanced Primary Reference Time Clock)`
 .. |FEC| replace:: :abbr:`FEC (Forward Error Correction)`
 .. |FPGA| replace:: :abbr:`FPGA (Field Programmable Gate Array)`
@@ -136,6 +138,7 @@
 .. |PHB| replace:: :abbr:`PHB (Per-Hop Behavior)`
 .. |PHC| replace:: :abbr:`PHC (PTP Hardware Clock)`
 .. |PHCs| replace:: :abbr:`PHCs (PTP Hardware Clocks)`
+.. |PKI| replace:: :abbr:`PKI (Public Key Infrastructure)`
 .. |PMC| replace:: :abbr:`PMC (PTP Management Client)`
 .. |PMD| replace:: :abbr:`PMD (Pole Mode Driver)`
 .. |PMU| replace:: :abbr:`PMU (Performance Monitor Unit)`