Chapter 7. Configuring a Proteccio HSM back end to work with the RHOSO Key Manager service

Procedure

1. Use DNF to install ansible-role-rhoso-proteccio-hsm:

   $ sudo dnf -y install ansible-role-rhoso-proteccio-hsm

2. Place the Trustway client image for Linux, and the client cert and the client key into the /opt/proteccio directory tree.

   $ cp <trustway_client_cert>.crt /opt/proteccio
   $ cp <Trustway_client_key>.key /opt/proteccio
   $ cp  <Proteccio3.06.05.iso> /opt/proteccio

   where:

   <trustway_client_cert>

   Specifies the file name of your client certificate.

   <trustway_client_key>

   Specifies the file name of your client key.

   <Proteccio3.06.05.iso>

   Specifies the name of your Trustway client for Linux ISO.

3. Retrieve the server certificate from the HSM device, and copy it to the /opt/proceccio directory. For more information on retrieving the server certificate from your Proteccio HSM, see the vendor documentation.
4. Optional: If you have more than one HSM for HA, get every certificate for each of the HSMs and put them altogether in the /opt/proteccio directory.

5. Update your proteccio.rc file to look similar to the following:

   [PROTECCIO]
   IPaddr=<Trustway_HSM_IP_address>
   SSL=1
   SrvCert=<HSM_Certificate_Name>.CRT
   
   [CLIENT]
   Mode=0
   LoggingLevel=7
   LogFile=/var/log/barbican/proteccio.log
   StatusFile=/var/log/barbican/HSM_Status.log
   ClntKey=<Client_Certificate_Name>.key
   ClntCert=<Client_Certificate_Name>.crt

   where:

   <Trustway_HSM_IP_Address>

   Specifies the IP address of your Trustway HSM.

   <HSM_Certificate_Name>

   Specifies the name of your Trustway certificate.

   Mode=0

   Specifies that only a single HSM device is in place.

   <Client_Certificate_Name>

   Specifies your client certificate name.

6. Optional: If you are configuring HA, you must include additional entries for the IP addresses of each HSM. Each new HSM must be inside of a [PROTECCIO] section. Additionally, you much change the Mode parameter inside the [CLIENT] to a value of either 1 or 2. For more information, see the official Eviden documentation.

   [PROTECCIO]
   IPaddr=<Trustway_HSM-2_IP_address>
   SSL=1
   SrvCert=<HSM-2_Certificate_Name>.CRT
   
   [CLIENT]
   Mode=2

   where:

   <Trustway_HSM-2_IP_Address>

   Specifies the IP address of your second Trustway HSM.

7. Create a new [PROTECCIO] section with the corresponding parameters for every subsequent Trustway unit you have in your environment.

8. Move the proteccio.rc configuration file to /opt/proteccio:

   $ mv proteccio.rc /opt/proteccio

9. Create a playbook called ansible-proteccio.yaml with the following contents:

     vars:
       Trustway_client_name: <name>
       Trustway_server_cert_src: "/opt/trustway/<server.pem>"
       Trustway_partition_password: "<password>"
       Trustway_data_secret: "Trustway_data_secret"
       login_secret: "login_secret"
       barbican_dest_image_namespace: "<namespace>"
       proteccio_client_src: "file:///opt/proteccio/<iso_file>"
       proteccio_password: "{{ PIN to log into proteccio }}"
       kubeconfig_path: "<kubeconfig_path"
       oc_dir: "<directory>"
     roles:
       - rhoso_proteccio_hsm

   where:

   <name>

   Specifies the name of your Trustway certificate.

   <server.pem>

   Specifies the name of your server certificate.

   <password>

   Specifies your HSM partition password.

   <namespace>

   Specifies your account name for Quay.io or other container registry.

   <iso_file>

   Specifies the name of the Proteccio client ISO file.

   <kubeconfig_path>

   Specifies the full path to your OpenShift configuration file.

   <directory>

   Specifies the full path to the OpenShift Client location.

10. Run the playbook:

    $ ansible-playbook ansible-proteccio.yaml

Procedure

1. Create a CR file with the following contents:

   apiVersion: core.openstack.org/v1beta1
   kind: OpenStackVersion
   metadata:
     name: openstack-galera-network-isolation
     namespace: openstack
   spec:
     customContainerImages:
         barbicanAPIImage: <api_image>
         barbicanWorkerImage: <worker_image>

   where:

   <api_image>

   Specifies the registry and path to the custom barbicanAPIImage.

   <worker_image>

   Specifies the registry and path to the custom barbicanWorkerImage.

2. Apply the OpenStackVersion CR:

   $ oc apply -f <filename>

   where:

   <filename>

   Specifies the OpenStackVersion CR file name.

Procedure

1. Configure the Key Manager service within your OpenStackControlPlane CR for use with the Trustway HSM:

   spec:
     barbican:
       apiOverride:
         route: {}
       enabled: true
       template:
         globalDefaultSecretStore: pkcs11
         enabledSecretStores:
           - pkcs11
           - simple_crypto
         apiTimeout: 90
         barbicanAPI:
           apiTimeout: 0
           customServiceConfig: |
             [secretstore:pkcs11]
             secret_store_plugin = store_crypto
             crypto_plugin = p11_crypto
             [p11_crypto_plugin]
             plugin_name = PKCS11
             library_path = /opt/tw_proteccio/lib/libnethsm.so
             token_labels = <token_label>
             mkek_label = <mkek_label>
             hmac_label = <hmac_label>
             encryption_mechanism = CKM_AES_CBC
             hmac_key_type = CKK_GENERIC_SECRET
             hmac_keygen_mechanism = CKM_GENERIC_SECRET_KEY_GEN
             hmac_mechanism = CKM_SHA256_HMAC
             key_wrap_mechanism = CKM_AES_CBC_PAD
             key_wrap_generate_iv = true
             always_set_cka_sensitive = true
             os_locking_ok = false
   
           pkcs11:
             loginSecret: "login_secret"
             clientDataSecret: "proteccio-data"
             clientDataPath: /etc/proteccio

   where:

   <token_label>

   Specifies the token label of your HSM. If you are using HA, you must replace <token_label> with the virtual token serial number.

   <mkek_label>

   Specifies a user-defined label. If you have already defined this label, you must use the same one.

   <hmac_label>

   Specifies a user-defined label. If you have already set this up, you must use the same label.

   Note

   Use one of the following options to identify the HSM that you can use. These options are mutually exclusive and have the following order of precedence:

   Expand

   Parameter	Value	Precedence
   token_serial_number	<serial_number>	1 - Highest
   token_labels	Comma-delimited lists	2 - Middle
   slot-id	<slot_id>	3 - Lowest

   Show more

2. Optional: If you have saved secrets that are using RHOSO Key Manager simple_crypto, keep those secrets available by enabling multiple back ends:

   spec:
     barbican:
       apiOverride:
         route: {}
       enabled: true
       template:
         globalDefaultSecretStore: pkcs11
         enabledSecretStores:
           - pkcs11
           - simple_crypto

3. Deploy the OpenStackControlPlane CR:

   $ oc apply -f openstack_control_plane.yaml