starlingx/docs
Code Issues Proposed changes

Merge "Remove mentions to TPM mode on certificate commands"

Browse Source
This commit is contained in:
Zuul 2022-05-18 18:12:09 +00:00 committed by Gerrit Code Review
commit 6da6a347f1
11 changed files with 12 additions and 355 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

15
doc/source/fault-mgmt/kubernetes/500-series-alarm-messages.rst
View File

@ -14,21 +14,6 @@ health of the system.
.. _500-series-alarm-messages-table-zrd-tg5-v5: .. _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=<tenant-uuid>
* - Degrade Affecting Severity:
- None
* - Severity:
- M
* - Proposed Repair Action
- Reinstall HTTPS certificate; if problem persists contact next level of
support.
----- -----

4
doc/source/introduction/functional_overview.rst
View File

@ -22,8 +22,8 @@ Where:
**Variety of open-source software supporting StarlingX and/or Kubernetes** **Variety of open-source software supporting StarlingX and/or Kubernetes**
This includes packages such as Apache, Ceph, PostgreSql, Etcd, |IPMI|, This includes packages such as Apache, Ceph, PostgreSql, Etcd, |IPMI|,
|TPM|, etc., as well as some services from OpenStack such as the etc., as well as some services from OpenStack such as the OpenStack
OpenStack Horizon Web interface, Keystone and Barbican. Horizon Web interface, Keystone and Barbican.
**StarlingX** **StarlingX**
Hardware and software infrastructure management. Hardware and software infrastructure management.

1
doc/source/node_management/kubernetes/host_hardware_management/changing-hardware-components-for-a-controller-host.rst
View File

@ -25,7 +25,6 @@ re-added, record the current partitioning and volume group assignments for
all disks so that you can reproduce them later. all disks so that you can reproduce them later.
.. note:: .. note::
All your data should be preserved across this procedure. All your data should be preserved across this procedure.
.. rubric:: |proc| .. rubric:: |proc|

6
doc/source/operations/k8s_cluster.rst
View File

@ -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: and Day-2 operations with respect to managing a cloud native platform:
* Installation * Installation
* Configuration management * Configuration management
* Operational and fault management of all components of the solution * Operational and fault management of all components of the solution
* Physical servers * Physical servers
@ -35,8 +37,10 @@ and Day-2 operations with respect to managing a cloud native platform:
* StarlingX software * StarlingX software
* Kubernetes software * Kubernetes software
* Supporting open-source software such as Ceph, Apache, and Postgres. * Supporting open-source software such as Ceph, Apache, and Postgres.
* Log and performance metrics are collected and reported for both hardware and * Log and performance metrics are collected and reported for both hardware and
software components. software components.
* Security is addressed across a variety of attack surfaces that includes TLS * Security is addressed across a variety of attack surfaces that includes TLS
support, user authentication/authorization, and network firewalls on all support, user authentication/authorization, and network firewalls on all
external interfaces, with support for technologies such as UEFI Secure Boot, external interfaces, with support for technologies such as UEFI Secure Boot,
@ -61,7 +65,7 @@ Hardened Linux
security CVE patches. security CVE patches.
Variety of open-source software supporting StarlingX and/or Kubernetes 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. well as some services from OpenStack such as Horizon, Keystone, and Barbican.
StarlingX StarlingX

1
doc/source/planning/kubernetes/index-planning-kub-913bd621ac0f.rst
View File

@ -97,7 +97,6 @@ Security planning
:maxdepth: 1 :maxdepth: 1
security-planning-uefi-secure-boot-planning security-planning-uefi-secure-boot-planning
tpm-planning
********************************** **********************************
Installation and resource planning Installation and resource planning

4
doc/source/planning/kubernetes/installation-and-resource-planning-https-access-planning.rst
View File

@ -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 You can update the certificate and key used by |prod| for the StarlingX REST
and Web Server endpoints at any time after installation. 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: .. _installation-and-resource-planning-https-access-planning-d18e105:

4
doc/source/planning/kubernetes/security-planning-uefi-secure-boot-planning.rst
View File

@ -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, option may be hidden in the |UEFI| setup utility unless |UEFI| mode is enabled,
and secure boot 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 Many motherboards ship with Microsoft secure boot certificates pre-programmed
in the |UEFI| certificate database. These certificates may be required to boot in the |UEFI| certificate database. These certificates may be required to boot
|UEFI| drivers for video cards, |RAID| controllers, or |NICs| \(for example, |UEFI| drivers for video cards, |RAID| controllers, or |NICs| \(for example,

25
doc/source/planning/kubernetes/tpm-planning.rst
View File

@ -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.

292
doc/source/security/kubernetes/secure-starlingx-rest-and-web-certificates-private-key-storage-with-tpm.rst
View File

@ -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
<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
<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 <pathTocertificateAndKey>
where:
**<pathTocertificateAndKey>**
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
<pathTocertificateAndKey>
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 <pathTocertificateAndKey>
.. 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

1
doc/source/security/kubernetes/starlingx-rest-api-applications-and-the-web-administration-server-deprecated.rst
View File

@ -49,4 +49,3 @@ For more details, refer to:
enable-https-access-for-starlingx-rest-and-web-server-endpoints enable-https-access-for-starlingx-rest-and-web-server-endpoints
install-update-the-starlingx-rest-and-web-server-certificate install-update-the-starlingx-rest-and-web-server-certificate
secure-starlingx-rest-and-web-certificates-private-key-storage-with-tpm

14
doc/source/security/kubernetes/use-uefi-secure-boot.rst
View File

@ -15,7 +15,7 @@ also means that upgrading from a legacy install to a secure boot install
\(UEFI\) is not supported. \(UEFI\) is not supported.
When upgrading a |prod| system from a version which does not support secure 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. the upgrade is complete.
For each node that is going to use secure boot, you must populate the |prod| 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 database. This option may be hidden in the UEFI setup utility unless UEFI
mode is enabled, and secure boot is enabled. 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 Many motherboards ship with Microsoft secure boot certificates
pre-programmed in the UEFI certificate database. These certificates may be pre-programmed in the |UEFI| certificate database. These certificates may be
required to boot UEFI drivers for video cards, RAID controllers, or NICs 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 \(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 Microsoft certificate\). While certificates can usually be removed from the
certificate database \(again, this is UEFI implementation specific\) it certificate database \(again, this is UEFI implementation specific\) it
may be required that you keep the Microsoft certificates to allow for 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. 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. 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. to be protected by secure boot.