:_mod-docs-content-type: PROCEDURE
[id="adopting-the-key-manager-service-with-proteccio-hsm_{context}"]

= Adopting the {key_manager} with Proteccio HSM integration

[role="_abstract"]
To adopt the {key_manager_first_ref} with Proteccio hardware security module (HSM) integration, you patch an existing `OpenStackControlPlane` custom resource (CR) where {key_manager} is disabled. The patch starts the service with the configuration parameters from the {rhos_prev_long} ({OpenStackShort}) environment and preserves access to existing HSM-backed secrets. You configure the {key_manager} to use both the `simple_crypto` and `pkcs11` back ends.

The {key_manager} Proteccio HSM adoption is complete if you see the following results:

* The `BarbicanAPI`, `BarbicanWorker`, and `BarbicanKeystoneListener` services are up and running with HSM-enabled configuration.
* All secrets from the source {OpenStackShort} {rhos_prev_ver} environment are available in {rhos_long} {rhos_curr_ver}.
* The PKCS11 crypto plugin is available alongside `simple_crypto` for new secret storage.
* HSM functionality is verified and operational.

[NOTE]
If your environment does not include Proteccio HSM, to adopt the {key_manager} by using `simple_crypto` only, see xref:adopting-the-key-manager-service_adopt-control-plane[Adopting the {key_manager}].

.Prerequisites

* You have a running {OpenStackPreviousInstaller} environment with Proteccio HSM integration (the source cloud).
* You have a Single Node OpenShift or OpenShift Local running in the {rhocp_long} cluster.
* You have SSH access to the source {OpenStackPreviousInstaller} undercloud and Controller nodes.
* Custom {key_manager} container images with the Proteccio client libraries are built and available in your container registry. For more information, see the `rhoso_proteccio_hsm` Ansible role documentation.
* The Proteccio client certificate, client key, server certificate, and `proteccio.rc` configuration file for the target environment are available on the host where you run the adoption commands.

[IMPORTANT]
====
Without proper HSM configuration, your HSM-protected secrets become inaccessible after adoption. Ensure the following before you begin:

* The HSM partition name, MKEK label, and HMAC label match the values configured in your source environment ({OpenStackShort}).
* The Proteccio client certificates and configuration files are valid for the target environment ({rhos_acro}).
====

.Procedure

. Confirm that your source environment configuration includes Proteccio HSM integration:
+
[source,bash]
----
$ ssh tripleo-admin@controller-0.ctlplane \
  "sudo cat /var/lib/config-data/puppet-generated/barbican/etc/barbican/barbican.conf | grep -A5 '\[p11_crypto_plugin\]'"
----
+
If you see the `[p11_crypto_plugin]` section with Proteccio-specific settings, for example `library_path = /usr/lib64/libnethsm.so`, continue with the HSM adoption. If you do not see this section, your source environment does not include Proteccio HSM integration. Use the standard adoption procedure instead. For more information, see xref:adopting-the-key-manager-service_adopt-control-plane[Adopting the {key_manager}].

. Add the simple crypto key encryption key (KEK) secret:
+
----
$ oc set data secret/osp-secret "BarbicanSimpleCryptoKEK=$($CONTROLLER1_SSH "python3 -c \"import configparser; c = configparser.ConfigParser(); c.read('/var/lib/config-data/puppet-generated/barbican/etc/barbican/barbican.conf'); print(c['simple_crypto_plugin']['kek'])\"")"
----

. Create the HSM login credentials secret:
+
[source,bash]
----
$ oc create secret generic hsm-login \
  --from-literal=PKCS11Pin=<your_hsm_password> \
  -n openstack
----
+
where:

`<your_hsm_password>`::
Specifies the HSM PKCS#11 PIN for the Proteccio partition in your environment.

. Create the Proteccio client data secret with the certificates and configuration:
+
[source,bash]
----
$ oc create secret generic proteccio-data \
  --from-file=client.crt=<path_to_client_cert> \
  --from-file=client.key=<path_to_client_key> \
  --from-file=<hsm_server_cert_filename>=<path_to_server_cert> \
  --from-file=proteccio.rc=<path_to_hsm_config> \
  -n openstack
----
+
where:

`<path_to_client_cert>`::
Specifies the path to the HSM client certificate file.
`<path_to_client_key>`::
Specifies the path to the HSM client key file.
`<hsm_server_cert_filename>`::
Specifies the filename of the HSM server certificate that is expected by the Proteccio client, for example, `10_8_60_93.CRT`.
`<path_to_server_cert>`::
Specifies the path to the HSM server certificate file.
`<path_to_hsm_config>`::
Specifies the path to the `proteccio.rc` configuration file for your environment.

. Patch the `OpenStackControlPlane` CR to deploy the {key_manager} with HSM support:
+
[subs="+quotes"]
----
$ oc patch openstackcontrolplane openstack --type=merge --patch '
spec:
  barbican:
    enabled: true
    apiOverride:
      route: {}
    template:
      databaseInstance: openstack
      databaseAccount: barbican
      messagingBus:
        cluster: rabbitmq
      secret: osp-secret
      simpleCryptoBackendSecret: osp-secret
      serviceAccount: barbican
      serviceUser: barbican
      passwordSelectors:
        database: BarbicanDatabasePassword
        service: BarbicanPassword
        simplecryptokek: BarbicanSimpleCryptoKEK
      customServiceConfig: |
        [p11_crypto_plugin]
        plugin_name = PKCS11
        library_path = *<library_path>*
        token_labels = *<partition_name>*
        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 = *<key_wrap_mechanism>*
        key_wrap_generate_iv = true
        always_set_cka_sensitive = true
        os_locking_ok = false
      globalDefaultSecretStore: pkcs11
      enabledSecretStores: ["simple_crypto", "pkcs11"]
      pkcs11:
        loginSecret: hsm-login
        clientDataSecret: proteccio-data
        clientDataPath: /etc/proteccio
      barbicanAPI:
        replicas: 1
        override:
          service:
            internal:
              metadata:
                annotations:
                  metallb.universe.tf/address-pool: internalapi
                  metallb.universe.tf/allow-shared-ip: internalapi
                  metallb.universe.tf/loadBalancerIPs: *<172.17.0.80>*
              spec:
                type: LoadBalancer
      barbicanWorker:
        replicas: 1
      barbicanKeystoneListener:
        replicas: 1
'
----
+
where:

`<library_path>`::
Specifies the path to the PKCS#11 library inside the container, for example, `/usr/lib64/libnethsm.so` for Proteccio.
`<partition_name>`::
Specifies the HSM partition name, for example, `VHSM1`. This value must match the partition configured in your source environment.
`<mkek_label>`::
Specifies the label of the Master Key Encryption Key (MKEK) in the HSM. This value must match the key configured in your source environment.
`<hmac_label>`::
Specifies the label of the HMAC key in the HSM. This value must match the key configured in your source environment.
`<key_wrap_mechanism>`::
Specifies the PKCS#11 key wrap mechanism, for example, `CKM_AES_CBC_PAD`. This value must match the mechanism configured in your source environment.
`<172.17.0.80>`::
Specifies the load balancer IP in your environment. If you use IPv6, change the load balancer IP to the load balancer IP in your environment, for example, `metallb.universe.tf/loadBalancerIPs: fd00:bbbb::80`.

`messagingBus.Cluster`::
For more information about RHOSO RabbitMQ clusters, see link:https://docs.redhat.com/en/documentation/red_hat_openstack_services_on_openshift/18.0/html/monitoring_high_availability_services/ref_rhoso-rabbitmq-clusters_ha-monitoring#con_understand-the-rabbitmq-interface-for-openstack-services[RHOSO RabbitMQ clusters] in _Monitoring high availability services_.

.Verification

. Ensure that the {identity_service_first_ref} endpoints are defined and are pointing to the control plane FQDNs:
+
----
$ openstack endpoint list | grep key-manager
----

. Ensure that the Barbican API service is registered in the {identity_service}:
+
----
$ openstack service list | grep key-manager
----

. Verify that all secrets from the source environment are available:
+
----
$ openstack secret list
----

. Confirm that the {key_manager} services are running with HSM-enabled configuration:
+
----
$ oc get pods -n openstack -l service=barbican -o wide
----

. Test secret creation to verify HSM functionality:
+
----
$ openstack secret store --name adoption-verification --payload 'HSM adoption successful'
----

. Verify that the HSM back end is operational by retrieving the secret:
+
----
$ openstack secret get <secret_id> --payload
----
+
where:

`<secret_id>`::
Specifies the ID of the secret created in the previous step.

[NOTE]
====
HSM adoption preserves both simple crypto and HSM-backed secrets. The migration process maintains HSM metadata and secret references, ensuring continued access to existing secrets while enabling new secrets to use either back end.
====
