From 3adaa45e61b152c8fb1ebdb010f4e7d7d1d76ee1 Mon Sep 17 00:00:00 2001 From: Ron Stone Date: Mon, 18 Apr 2022 14:45:01 -0400 Subject: [PATCH] Remove mentions to TPM mode on certificate commands Remove customer documentation of TPM mode of certificate install. Fix merge conflict Story: 2009712 Task: 44087 Signed-off-by: Ron Stone Change-Id: Iaf4d0d288181f0feb10af58f3ce361f1a8ea5324 --- .../kubernetes/500-series-alarm-messages.rst | 15 - .../introduction/functional_overview.rst | 4 +- ...dware-components-for-a-controller-host.rst | 1 - doc/source/operations/k8s_cluster.rst | 6 +- .../index-planning-kub-913bd621ac0f.rst | 1 - ...esource-planning-https-access-planning.rst | 4 - ...ity-planning-uefi-secure-boot-planning.rst | 4 - .../planning/kubernetes/tpm-planning.rst | 25 -- ...tificates-private-key-storage-with-tpm.rst | 292 ------------------ ...e-web-administration-server-deprecated.rst | 1 - .../kubernetes/use-uefi-secure-boot.rst | 14 +- 11 files changed, 12 insertions(+), 355 deletions(-) delete mode 100755 doc/source/planning/kubernetes/tpm-planning.rst delete mode 100644 doc/source/security/kubernetes/secure-starlingx-rest-and-web-certificates-private-key-storage-with-tpm.rst diff --git a/doc/source/fault-mgmt/kubernetes/500-series-alarm-messages.rst b/doc/source/fault-mgmt/kubernetes/500-series-alarm-messages.rst index 3c2c8a6bd..e98c8d366 100644 --- a/doc/source/fault-mgmt/kubernetes/500-series-alarm-messages.rst +++ b/doc/source/fault-mgmt/kubernetes/500-series-alarm-messages.rst @@ -14,21 +14,6 @@ health of the system. .. _500-series-alarm-messages-table-zrd-tg5-v5: -.. list-table:: - :widths: 6 25 - :header-rows: 0 - - * - **Alarm ID: 500.100** - - |TPM| initialization failed on host. - * - Entity Instance - - tenant= - * - Degrade Affecting Severity: - - None - * - Severity: - - M - * - Proposed Repair Action - - Reinstall HTTPS certificate; if problem persists contact next level of - support. ----- diff --git a/doc/source/introduction/functional_overview.rst b/doc/source/introduction/functional_overview.rst index 6160a950f..3689c3660 100644 --- a/doc/source/introduction/functional_overview.rst +++ b/doc/source/introduction/functional_overview.rst @@ -22,8 +22,8 @@ Where: **Variety of open-source software supporting StarlingX and/or Kubernetes** This includes packages such as Apache, Ceph, PostgreSql, Etcd, |IPMI|, - |TPM|, etc., as well as some services from OpenStack such as the - OpenStack Horizon Web interface, Keystone and Barbican. + etc., as well as some services from OpenStack such as the OpenStack + Horizon Web interface, Keystone and Barbican. **StarlingX** Hardware and software infrastructure management. diff --git a/doc/source/node_management/kubernetes/host_hardware_management/changing-hardware-components-for-a-controller-host.rst b/doc/source/node_management/kubernetes/host_hardware_management/changing-hardware-components-for-a-controller-host.rst index 7e836e3e1..4ec7c9c86 100644 --- a/doc/source/node_management/kubernetes/host_hardware_management/changing-hardware-components-for-a-controller-host.rst +++ b/doc/source/node_management/kubernetes/host_hardware_management/changing-hardware-components-for-a-controller-host.rst @@ -25,7 +25,6 @@ re-added, record the current partitioning and volume group assignments for all disks so that you can reproduce them later. .. note:: - All your data should be preserved across this procedure. .. rubric:: |proc| diff --git a/doc/source/operations/k8s_cluster.rst b/doc/source/operations/k8s_cluster.rst index 25919a303..8c5327296 100644 --- a/doc/source/operations/k8s_cluster.rst +++ b/doc/source/operations/k8s_cluster.rst @@ -27,7 +27,9 @@ StarlingX Kubernetes provides a fully-managed solution that includes both Day-1 and Day-2 operations with respect to managing a cloud native platform: * Installation + * Configuration management + * Operational and fault management of all components of the solution * Physical servers @@ -35,8 +37,10 @@ and Day-2 operations with respect to managing a cloud native platform: * StarlingX software * Kubernetes software * Supporting open-source software such as Ceph, Apache, and Postgres. + * Log and performance metrics are collected and reported for both hardware and software components. + * Security is addressed across a variety of attack surfaces that includes TLS support, user authentication/authorization, and network firewalls on all external interfaces, with support for technologies such as UEFI Secure Boot, @@ -61,7 +65,7 @@ Hardened Linux security CVE patches. Variety of open-source software supporting StarlingX and/or Kubernetes - Includes packages such as Apache, Ceph, PostgreSql, Etcd, IPMI, and TPM, as + Includes packages such as Apache, Ceph, PostgreSql, Etcd, and |IPMI|, as well as some services from OpenStack such as Horizon, Keystone, and Barbican. StarlingX diff --git a/doc/source/planning/kubernetes/index-planning-kub-913bd621ac0f.rst b/doc/source/planning/kubernetes/index-planning-kub-913bd621ac0f.rst index f9aa13f9d..6e80d398d 100644 --- a/doc/source/planning/kubernetes/index-planning-kub-913bd621ac0f.rst +++ b/doc/source/planning/kubernetes/index-planning-kub-913bd621ac0f.rst @@ -97,7 +97,6 @@ Security planning :maxdepth: 1 security-planning-uefi-secure-boot-planning - tpm-planning ********************************** Installation and resource planning diff --git a/doc/source/planning/kubernetes/installation-and-resource-planning-https-access-planning.rst b/doc/source/planning/kubernetes/installation-and-resource-planning-https-access-planning.rst index 49eb1a3ed..4b5603d4f 100755 --- a/doc/source/planning/kubernetes/installation-and-resource-planning-https-access-planning.rst +++ b/doc/source/planning/kubernetes/installation-and-resource-planning-https-access-planning.rst @@ -59,10 +59,6 @@ create public certificate and private key pairs for HTTPS. You can update the certificate and key used by |prod| for the StarlingX REST and Web Server endpoints at any time after installation. -For additional security, |prod| optionally supports storing the private key of -the StarlingX Rest and Web Server certificate in a StarlingX |TPM| hardware -device. |TPM| 2.0-compliant hardware must be available on the controller hosts. - .. _installation-and-resource-planning-https-access-planning-d18e105: diff --git a/doc/source/planning/kubernetes/security-planning-uefi-secure-boot-planning.rst b/doc/source/planning/kubernetes/security-planning-uefi-secure-boot-planning.rst index 61ba43135..575f5ebab 100755 --- a/doc/source/planning/kubernetes/security-planning-uefi-secure-boot-planning.rst +++ b/doc/source/planning/kubernetes/security-planning-uefi-secure-boot-planning.rst @@ -26,10 +26,6 @@ a file containing a certificate to be loaded in the authorized database. This option may be hidden in the |UEFI| setup utility unless |UEFI| mode is enabled, and secure boot is enabled. -The |UEFI| implementation may or may not require a |TPM| device to be present -and enabled before providing for secure boot functionality. Refer to your -server board's documentation. - Many motherboards ship with Microsoft secure boot certificates pre-programmed in the |UEFI| certificate database. These certificates may be required to boot |UEFI| drivers for video cards, |RAID| controllers, or |NICs| \(for example, diff --git a/doc/source/planning/kubernetes/tpm-planning.rst b/doc/source/planning/kubernetes/tpm-planning.rst deleted file mode 100755 index f0ad5c23a..000000000 --- a/doc/source/planning/kubernetes/tpm-planning.rst +++ /dev/null @@ -1,25 +0,0 @@ - -.. cvf1552672201332 -.. _tpm-planning: - -============ -TPM Planning -============ - -|TPM| is an industry standard crypto processor that enables secure storage -of HTTPS |SSL| private keys. It is used in support of advanced security -features. - -|TPM| is an optional requirement for |UEFI| Secure Boot. - -If you plan to use |TPM| for secure protection of REST API and Web Server -HTTPS |SSL| keys, ensure that |TPM| 2.0 compliant hardware devices are -fitted on controller nodes before provisioning them. If properly connected, -the BIOS should detect these new devices and display appropriate -configuration options. |TPM| must be enabled from the BIOS before it can be -used in software. - -.. note:: - |prod| allows post installation configuration of HTTPS mode. It is - possible to transition a live HTTP system to a system that uses |TPM| - for storage of HTTPS |SSL| keys without reinstalling the system. diff --git a/doc/source/security/kubernetes/secure-starlingx-rest-and-web-certificates-private-key-storage-with-tpm.rst b/doc/source/security/kubernetes/secure-starlingx-rest-and-web-certificates-private-key-storage-with-tpm.rst deleted file mode 100644 index bf76e7799..000000000 --- a/doc/source/security/kubernetes/secure-starlingx-rest-and-web-certificates-private-key-storage-with-tpm.rst +++ /dev/null @@ -1,292 +0,0 @@ - -.. lzf1570032232833 -.. _secure-starlingx-rest-and-web-certificates-private-key-storage-with-tpm: - -======================================================================== -Secure StarlingX REST and Web Certificate's Private Key Storage with TPM -======================================================================== - -.. warning:: - - |TPM| support is deprecated and will be removed in an upcoming release - of |prod|. Users should instead use the procedure in - :ref:`starlingx-rest-api-applications-and-the-web-admin-server-cert-9196c5794834`. - - -For increased security, the |prod| REST and Web Server's certificate can -be installed such that the private key is stored in a |TPM| 2.0 device on -the controller. - -.. rubric:: |context| - -|TPM| is an industry standard cryptographic processor that enables secure -storage of secrets. |prod| can use a |TPM| device, if present, to securely -store the private key of the |prod| REST and Web Server's certificate. - -The |TPM| is used to wrap the private key within the |TPM| device. Each -wrapping is unique to that |TPM| device and cannot be synchronized between -controllers using different |TPM| devices. Therefore, the same private key -is always secured to both the active and standby controllers' |TPM| devices -at the same time. Given this operational constraint, |prod| has measures in -place to detect when the standby controller is reinstalled or replaced, and -raise appropriate alarms to prevent an Unlock or Swact of a new standby -controller until the |prod| REST and Web Server's certificate is -re-installed, in order to update the new standby controller's |TPM| device. - -.. rubric:: |prereq| - - -.. _secure-starlingx-rest-and-web-certificates-private-key-storage-with-tpm-ul-xj3-mqc-d1b: - -- Obtain an Intermediate or Root |CA|-signed certificate and key from a - trusted Intermediate or Root |CA|. Refer to the documentation for the - external Intermediate or Root |CA| that you are using, on how to create - public certificate and private key pairs, signed by an Intermediate or - Root-signed |CA|, for HTTPS. - - For lab purposes, see :ref:`Create Certificates Locally using openssl - ` for details on how to create - a test Intermediate or Root |CA| certificate and key, and use it to sign - test certificates. - - Put the |PEM| encoded versions of the certificate and key in a - single file, and copy the file to the controller host. - -- Both controllers must be provisioned and unlocked before you can install - the certificate using |TPM| to store the private key. - -- A |TPM| 2.0 device must be available on both controller nodes. - -- |TPM| must be enabled in the |UEFI| on both controllers. - -- HTTPS must be enabled on the system. - -.. note:: - - If you plan to use the container-based remote CLIs, due to a limitation in - the Python2 SSL certificate validation, the certificate used for the |prod| - REST API application endpoints and |prod| Web Administration Server ('ssl') - certificate must either have: - - #. CN=IPADDRESS and SANs=IPADDRESS - - or - - #. CN=FQDN and SANs=FQDN - - where IPADDRESS and |FQDN| are for the |OAM| Floating IP Address. - -.. caution:: - - Do not install the certificate using |TPM| on controller-0 before the - standby controller-1 has been provisioned and unlocked. If this happens, - you cannot unlock controller-1. To recover, do the following: - -.. _secure-starlingx-rest-and-web-certificates-private-key-storage-with-tpm-ol-jpm-2kq-qcb: - -#. Install the certificate without |TPM| on controller-0. For more - information, see :ref:`Install/Update the StarlingX Rest and Web - Server Certificate - `. - -#. Unlock controller-1. - -#. Reinstall the certificate using |TPM| on controller-0. - - -.. rubric:: |proc| - -.. _secure-starlingx-rest-and-web-certificates-private-key-storage-with-tpm-steps-hnx-qf5-x1b: - -#. Install the |prod| REST and Web Server's certificate using |TPM| to - securely store the private key: - - .. code-block:: none - - ~(keystone_admin)]$ system certificate-install –m tpm_mode - - where: - - **** - - is the path to the file containing both the intermediate or Root - |CA|-signed certificate and private key to install. - - .. warning:: - - For security purposes, the utility deletes the provided SSL private - key from the file system and asks for confirmation during the - installation. You should store a copy of the SSL private key off-site. - - .. note:: - - Only X.509 based RSA key certificates are supported \(PKCS12 format - and ECDSA keys are not supported\). Additionally, 4096 bit RSA key - lengths are not supported. - -#. Check the certificate's |TPM| configuration state for each provisioned - controller node. - - .. code-block:: none - - [sysadmin@controller-0 tmp(keystone_admin)]$ system certificate-show tpm - +-------------+-----------------------------------------------------+ - | Property | Value | - +-------------+-----------------------------------------------------+ - | uuid | ed3d6a22-996d-421b-b4a5-64ab42ebe8be | - | certtype | tpm_mode | - | signature | tpm_mode_13214262027721489760 | - | start_date | 2018-03-21T14:53:03+00:00 | - | expiry_date | 2019-03-21T14:53:03+00:00 | - | details | {u'state': {u'controller-1': u'tpm-config-applied', | - | | u'controller-0': u'tpm-config-applied'}} | - +-------------+-----------------------------------------------------+ - - - Subsequent certificate installs using |TPM| populate the updated\_at field - to indicate when the certificate was refreshed. - - .. code-block:: none - - [sysadmin@controller-0 tmp(keystone_admin)]$ system certificate-show tpm - +-------------+-----------------------------------------------------+ - | Property | Value | - +-------------+-----------------------------------------------------+ - | uuid | d6a47714-2b99-4470-b2c8-422857749c98 | - | certtype | tpm_mode | - | signature | tpm_mode_13214262027721489760 | - | start_date | 2018-03-21T14:53:03+00:00 | - | expiry_date | 2019-03-21T14:53:03+00:00 | - | details | {u'state': {u'controller-1': u'tpm-config-applied', | - | | u'controller-0': u'tpm-config-applied'}, | - | | u'updated_at':u'2018-03-21T16:18:15.879639+00:00'} | - +-------------+-----------------------------------------------------+ - - -If either controller has state **tpm-config-failed**, then a 500.100 -alarm is raised for the host. - -- A LOCKED controller node that is not in the |TPM| applied configuration - state \(**tpm-config-applied**\), is prevented from being UNLOCKED - -- An UNLOCKED controller node that is not in the |TPM| applied - configuration state \(**tpm-config-applied**\), is prevented from being - Swacted To or upgraded. - - - -.. rubric:: |postreq| - -When reinstalling either of the controllers or during a hardware replacement -scenario, you must reinstall the certificate: - -.. code-block:: none - - ~(keystone_admin)]$ system certificate-install -m tpm_mode - - -To disable the use of |TPM| to store the private key of the |prod| REST -and Web Server's certificate, install the certificate without the |TPM| -option: - -.. code-block:: none - - ~(keystone_admin)]$ system certificate-install - -.. warning:: - - The REST and Web Server certificate are not automatically renewed, user - MUST renew the certificate prior to expiry, otherwise a variety of system - operations will fail. - -.. _tpm-configuration-considerations: - --------------------------------- -TPM configuration considerations --------------------------------- - -There are some considerations to account for when configuring or -reconfiguring |TPM|. - -This includes certain behavior and warnings that you may encounter when -configuring |TPM|. The same behavior and warnings are seen when performing -these actions in the Horizon Web interface, also. - - -.. _tpm-configuration-considerations-ul-fbm-1fy-f1b: - -- The :command:`certificate-show tpm` command will indicate the status of - the |TPM| configuration on the hosts, either **tpm-config-failed** or - **tpm-config-applied**. - - .. code-block:: none - - ~(keystone_admin)]$ system certificate-show tpm - +-------------+-----------------------------------------------------+ - | Property | Value | - +-------------+-----------------------------------------------------+ - | uuid | ed3d6a22-996d-421b-b4a5-64ab42ebe8be | - | certtype | tpm_mode | - | signature | tpm_mode_13214262027721489760 | - | start_date | 2018-03-21T14:53:03+00:00 | - | expiry_date | 2019-03-21T14:53:03+00:00 | - | details | {u'state': {u'controller-1': u'tpm-config-applied', | - | | u'controller-0': u'tpm-config-applied'}} | - +-------------+-----------------------------------------------------+ - - -- If either controller has state **tpm-config-failed**, then a **500.100** - alarm will be raised for the host. - - .. code-block:: none - - ~(keystone_admin)]$ fm alarm-list - - +----------+------------------+------------------+----------+------------+ - | Alarm ID | Reason Text | Entity ID | Severity | Time Stamp | - +----------+------------------+------------------+----------+------------+ - | 500.100 | TPM configuration| host=controller-1| major | 2017-06-1..| - | | failed or device.| | |.586010 | - +----------+------------------+------------------+----------+------------+ - - -- An UNLOCKED controller node that is not in TPM applied configuration - state \(**tpm-config-applied**\) will be prevented from being Swacted To or - upgraded. - - The following warning is generated when you attempt to swact: - - .. code-block:: none - - ~(keystone_admin)]$ system host-swact controller-0 - TPM configuration not fully applied on host controller-1; Please - run https-certificate-install before re-attempting. - - -- A LOCKED controller node that is not in |TPM| applied configuration state - \(**tpm-config-applied**\) will be prevented from being UNLOCKED. - - The :command:`host-list` command below shows controller-1 as locked and - disabled. - - .. code-block:: none - - ~(keystone_admin)]$ system host-list - - +----+--------------+-------------+----------------+-------------+--------------+ - | id | hostname | personality | administrative | operational | availability | - +----+--------------+-------------+----------------+-------------+--------------+ - | 1 | controller-0 | controller | unlocked | enabled | available | - | 2 | controller-1 | controller | locked | disabled | online | - +----+--------------+-------------+----------------+-------------+--------------+ - - The following warning is generated when you attempt to UNLOCK a - controller not in a **tpm-config-applied** state: - - .. code-block:: none - - ~[keystone_admin)]$ system host-unlock controller-1 - - TPM configuration not fully applied on host controller-1; Please - run https-certificate-install before re-attempting - diff --git a/doc/source/security/kubernetes/starlingx-rest-api-applications-and-the-web-administration-server-deprecated.rst b/doc/source/security/kubernetes/starlingx-rest-api-applications-and-the-web-administration-server-deprecated.rst index d5e387abb..5bf964960 100644 --- a/doc/source/security/kubernetes/starlingx-rest-api-applications-and-the-web-administration-server-deprecated.rst +++ b/doc/source/security/kubernetes/starlingx-rest-api-applications-and-the-web-administration-server-deprecated.rst @@ -49,4 +49,3 @@ For more details, refer to: enable-https-access-for-starlingx-rest-and-web-server-endpoints install-update-the-starlingx-rest-and-web-server-certificate - secure-starlingx-rest-and-web-certificates-private-key-storage-with-tpm diff --git a/doc/source/security/kubernetes/use-uefi-secure-boot.rst b/doc/source/security/kubernetes/use-uefi-secure-boot.rst index d29ac0915..1d7bb9092 100644 --- a/doc/source/security/kubernetes/use-uefi-secure-boot.rst +++ b/doc/source/security/kubernetes/use-uefi-secure-boot.rst @@ -15,7 +15,7 @@ also means that upgrading from a legacy install to a secure boot install \(UEFI\) is not supported. When upgrading a |prod| system from a version which does not support secure -boot to a version that does, do not enable secure boot in UEFI firmware until +boot to a version that does, do not enable secure boot in |UEFI| firmware until the upgrade is complete. For each node that is going to use secure boot, you must populate the |prod| @@ -31,14 +31,10 @@ browse to a file containing a certificate to be loaded in the authorized database. This option may be hidden in the UEFI setup utility unless UEFI mode is enabled, and secure boot is enabled. -The UEFI implementation may or may not require a |TPM| device to be -present and enabled before providing for secure boot functionality. Refer to -you server board's manufacturer's documentation. - Many motherboards ship with Microsoft secure boot certificates -pre-programmed in the UEFI certificate database. These certificates may be -required to boot UEFI drivers for video cards, RAID controllers, or NICs -\(for example, the PXE boot software for a NIC may have been signed by a +pre-programmed in the |UEFI| certificate database. These certificates may be +required to boot |UEFI| drivers for video cards, RAID controllers, or NICs +\(for example, the |PXE| boot software for a NIC may have been signed by a Microsoft certificate\). While certificates can usually be removed from the certificate database \(again, this is UEFI implementation specific\) it may be required that you keep the Microsoft certificates to allow for @@ -46,6 +42,6 @@ complete system operation. Mixed combinations of secure boot and non-secure boot nodes are supported. For example, a controller node may secure boot, while a worker node may not. -Secure boot must be enabled in the UEFI firmware of each node for that node +Secure boot must be enabled in the |UEFI| firmware of each node for that node to be protected by secure boot.