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

Secure StarlingX REST and Web Certificate's Private Key Storage with TPM

Warning

support is deprecated and will be removed in an upcoming release of . Users should instead use the procedure in starlingx-rest-api-applications-and-the-web-admin-server-cert-9196c5794834.

For increased security, the REST and Web Server's certificate can be installed such that the private key is stored in a 2.0 device on the controller.

is an industry standard cryptographic processor that enables secure storage of secrets. can use a device, if present, to securely store the private key of the REST and Web Server's certificate.

The is used to wrap the private key within the device. Each wrapping is unique to that device and cannot be synchronized between controllers using different devices. Therefore, the same private key is always secured to both the active and standby controllers' devices at the same time. Given this operational constraint, 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 REST and Web Server's certificate is re-installed, in order to update the new standby controller's device.

• Obtain an Intermediate or Root -signed certificate and key from a trusted Intermediate or Root . Refer to the documentation for the external Intermediate or Root that you are using, on how to create public certificate and private key pairs, signed by an Intermediate or Root-signed , for HTTPS.

  For lab purposes, see Create Certificates Locally using openssl <create-certificates-locally-using-openssl> for details on how to create a test Intermediate or Root certificate and key, and use it to sign test certificates.

  Put the 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 to store the private key.

• A 2.0 device must be available on both controller nodes.

• must be enabled in the 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 REST API application endpoints and Web Administration Server ('ssl') certificate must either have:

1. CN=IPADDRESS and SANs=IPADDRESS

   or

2. CN=FQDN and SANs=FQDN

   where IPADDRESS and are for the Floating IP Address.

Caution

Do not install the certificate using 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:

1. Install the certificate without on controller-0. For more information, see Install/Update the StarlingX Rest and Web Server Certificate <install-update-the-starlingx-rest-and-web-server-certificate>.
2. Unlock controller-1.
3. Reinstall the certificate using on controller-0.

1. Install the REST and Web Server's certificate using to securely store the private key:

   ~(keystone_admin)]$ system certificate-install –m tpm_mode <pathTocertificateAndKey>

   where:

   <pathTocertificateAndKey>

   is the path to the file containing both the intermediate or Root -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.

2. Check the certificate's configuration state for each provisioned controller node.

   [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 populate the updated_at field to indicate when the certificate was refreshed.

   [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 applied configuration state (tpm-config-applied), is prevented from being UNLOCKED
• An UNLOCKED controller node that is not in the applied configuration state (tpm-config-applied), is prevented from being Swacted To or upgraded.

When reinstalling either of the controllers or during a hardware replacement scenario, you must reinstall the certificate:

~(keystone_admin)]$ system certificate-install -m tpm_mode
<pathTocertificateAndKey>

To disable the use of to store the private key of the REST and Web Server's certificate, install the certificate without the option:

~(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

There are some considerations to account for when configuring or reconfiguring .

This includes certain behavior and warnings that you may encounter when configuring . The same behavior and warnings are seen when performing these actions in the Horizon Web interface, also.

• The certificate-show tpm command will indicate the status of the configuration on the hosts, either tpm-config-failed or tpm-config-applied.

  ~(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.

  ~(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:

  ~(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 applied configuration state (tpm-config-applied) will be prevented from being UNLOCKED.

  The host-list command below shows controller-1 as locked and disabled.

  ~(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:

  ~[keystone_admin)]$ system host-unlock controller-1
  
  TPM configuration not fully applied on host controller-1; Please
  run https-certificate-install before re-attempting