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 StarlingX. Users should instead use the procedure in Create a local CA Issuer.
For increased security, the StarlingX 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.
About this task
TPM is an industry standard cryptographic processor that enables secure storage of secrets. StarlingX can use a TPM device, if present, to securely store the private key of the StarlingX 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, StarlingX 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 StarlingX REST and Web Server’s certificate is re-installed, in order to update the new standby controller’s TPM device.
Prerequisites
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 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 StarlingX REST API application endpoints and StarlingX 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:
Install the certificate without TPM on controller-0. For more information, see Install/Update the StarlingX Rest and Web Server Certificate.
Unlock controller-1.
Reinstall the certificate using TPM on controller-0.
Procedure
Install the StarlingX REST and Web Server’s certificate using TPM 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 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.
[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.
[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.
Postrequisites
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 TPM to store the private key of the StarlingX REST and Web Server’s certificate, install the certificate without the TPM 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 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.
The certificate-show tpm command will indicate the status of the TPM 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 TPM 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
