Skip to content

Commit 1710ac0

Browse files
openshift-merge-bot[bot]openshift-merge-bot[bot]
authored
Merge pull request #1058 from mauricioharley/adopt_proteccio_doc
Add Barbican adoption with Proteccio HSM integration documentation
2 parents 9809b7e + 273f8d7 commit 1710ac0

10 files changed

Lines changed: 1045 additions & 6 deletions

‎docs_user/assemblies/assembly_adopting-key-manager-service-with-hsm.adoc‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
:_mod-docs-content-type: ASSEMBLY
2+
ifdef::context[:parent-context: {context}]
3+
4+
[id="adopting-key-manager-service-with-hsm_{context}"]
5+
6+
:context: hsm-integration
7+
8+
= Adopting the {key_manager} with HSM integration
9+
10+
[role="_abstract"]
11+
Adopt the {key_manager_first_ref} from {OpenStackPreviousInstaller} to {rhos_long} when your source environment includes hardware security module (HSM) integration to preserve HSM functionality and maintain access to HSM-backed secrets. HSM provides enhanced security for cryptographic operations by storing encryption keys in dedicated hardware devices.
12+
13+
include::../modules/con_key-manager-service-hsm-adoption-approaches.adoc[leveloffset=+1]
14+
15+
include::../modules/proc_adopting-key-manager-service-with-proteccio-hsm.adoc[leveloffset=+1]
16+
17+
include::../modules/proc_adopting-key-manager-service-with-hsm-integration.adoc[leveloffset=+1]
18+
19+
include::../modules/ref_troubleshooting-key-manager-hsm-adoption.adoc[leveloffset=+1]
20+
21+
include::../modules/ref_troubleshooting-key-manager-proteccio-adoption.adoc[leveloffset=+1]
22+
23+
[role="_additional-resources"]
24+
== Additional resources
25+
26+
* {key_manager} service configuration documentation
27+
* Hardware security module vendor-specific documentation
28+
* OpenStack Barbican PKCS#11 plugin documentation
29+
30+
ifdef::parent-context[:context: {parent-context}]
31+
ifndef::parent-context[:!context:]

‎docs_user/assemblies/assembly_adopting-openstack-control-plane-services.adoc‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,8 @@ include::../modules/proc_configuring-ldap-with-domain-specific-drivers.adoc[leve
1616

1717
include::../modules/proc_adopting-key-manager-service.adoc[leveloffset=+1]
1818

19+
include::../assemblies/assembly_adopting-key-manager-service-with-hsm.adoc[leveloffset=+1]
20+
1921
include::../modules/proc_adopting-the-networking-service.adoc[leveloffset=+1]
2022

2123
include::../modules/proc_adopting-the-object-storage-service.adoc[leveloffset=+1]

‎docs_user/modules/con_adoption-limitations.adoc‎

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -34,7 +34,5 @@ The adoption process does not support the following features:
3434
* {loadbalancer_first_ref}
3535
* Adopting Border Gateway Protocol (BGP) environments to the {rhos_acro} data plane
3636
* Adopting a Federal Information Processing Standards (FIPS) environment
37-
* The {key_manager} only supports the simple crypto plug-in
38-
3937

4038
//* When you adopt a {OpenStackShort} {rhos_prev_ver} FIPS environment to {rhos_acro} {rhos_curr_ver}, your adopted cluster remains a FIPS cluster. There is no option to change the FIPS status during adoption. If your cluster is FIPS-enabled, you must deploy a FIPS {rhocp_long} cluster to adopt your {OpenStackShort} {rhos_prev_ver} FIPS control plane. For more information about enabling FIPS in {OpenShiftShort}, see link:{defaultOCPURL}/installing/installation-overview#installing-fips[Support for FIPS cryptography] in the {OpenShiftShort} _Installing_ guide.

‎docs_user/modules/con_key-manager-service-hsm-adoption-approaches.adoc‎

Lines changed: 66 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,66 @@
1+
:_mod-docs-content-type: CONCEPT
2+
[id="key-manager-service-hsm-adoption-approaches_{context}"]
3+
4+
= {key_manager} HSM adoption approaches
5+
6+
[role="_abstract"]
7+
The {key_manager_first_ref} adoption approach depends on your source {OpenStackPreviousInstaller} environment configuration.
8+
9+
* Use the standard adoption approach if your environment includes only the `simple_crypto` plugin for secret storage and has no HSM integration.
10+
* Use the HSM-enabled adoption approach if your source environment has HSM integration that uses Public Key Cryptography Standard (PKCS) #11, Key Management Interoperability Protocol (KMIP), or other HSM back ends alongside `simple_crypto`.
11+
12+
Standard adoption approach::
13+
* Uses the existing {key_manager} adoption procedure
14+
* Migrates a simple crypto back-end configuration
15+
* Provides a single-step adoption process
16+
* Is suitable for development, testing, and standard production environments
17+
18+
HSM-enabled adoption approach::
19+
* Uses the enhanced `barbican_adoption` role with HSM awareness
20+
* Configures HSM integration through a simple boolean flag (`barbican_hsm_enabled: true`)
21+
* Automatically creates required Kubernetes secrets (`hsm-login` and `proteccio-data`)
22+
* Preserves HSM metadata during database migration
23+
* Supports both simple crypto and HSM back ends in the target environment
24+
* Requires HSM-specific configuration variables and custom container images with HSM client libraries (built using the `rhoso_proteccio_hsm` Ansible role)
25+
* Uses HSM client certificates and configuration files accessible via URLs
26+
* Requires proper HSM partition and key configuration that matches your source environment
27+
* The HSM-enabled adoption approach currently supports:
28+
** Proteccio (Eviden Trustway): Fully supported with PKCS#11 integration
29+
** Luna (Thales): PKCS#11 support available
30+
** nCipher (Entrust): PKCS#11 support available
31+
32+
[IMPORTANT]
33+
====
34+
HSM adoption requires additional configuration steps, including:
35+
36+
* Custom Barbican container images with HSM client libraries that are built using the `rhoso_proteccio_hsm` Ansible role
37+
* HSM client certificates and configuration files that are accessible by using URLs
38+
* Proper HSM partition and key configuration that matches your source environment
39+
40+
These approaches are mutually exclusive. Choose an approach based on your source environment configuration.
41+
====
42+
43+
[options="header"]
44+
|===
45+
| Source environment characteristic | Approach | Rationale
46+
47+
| Only `simple_crypto` back-end configured
48+
| Standard adoption
49+
| No HSM complexity needed
50+
51+
| HSM integration present (PKCS#11, KMIP, and so on)
52+
| HSM-enabled adoption
53+
| Preserves HSM functionality and secrets
54+
55+
| Development or testing environment
56+
| Standard adoption
57+
| Simpler setup and maintenance
58+
59+
| Production with compliance requirements
60+
| HSM-enabled adoption
61+
| Maintains security compliance
62+
63+
| Unknown back-end configuration
64+
| Check source environment first
65+
| Determine appropriate approach
66+
|===

‎docs_user/modules/con_key-manager-service-support-for-crypto-plugins.adoc‎

Lines changed: 14 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -4,9 +4,21 @@
44
= Key Manager service support for crypto plug-ins
55

66
[role="_abstract"]
7-
The Key Manager service (barbican) does not yet support all of the crypto plug-ins available in {OpenStackPreviousInstaller}.
7+
The {key_manager_first_ref} supports multiple crypto plug-ins for different security requirements and deployment scenarios.
88

9-
//**TODO: Right now Barbican only supports the simple crypto plugin.
9+
The following crypto plug-ins are supported in {rhos_long}:
10+
11+
* Simple Crypto Plug-in: Software-based cryptographic back end suitable for development and testing environments
12+
* Public Key Cryptography Standard (PKCS) #11 Plug-in: Hardware security module (HSM) integration for production environments that requires enhanced security
1013

1114
//*TODO: Talk about Ceph Storage and Swift Storage nodes, HCI deployments,
1215
//etc.*
16+
17+
The {key_manager} supports HSM integration through the PKCS#11 plugin. This enables:
18+
19+
* Enhanced security for secret storage and retrieval
20+
* Hardware-based key management
21+
* Compliance with security requirements for production environments
22+
* Preservation of existing HSM-protected secrets during adoption
23+
24+
HSM integration is configured through a simple boolean flag (`barbican_hsm_enabled`) during the adoption process. For environments that require HSM integration during adoption, see xref:adopting-key-manager-service-with-proteccio-hsm_{context}[Adopting the {key_manager} with Proteccio HSM integration].

‎docs_user/modules/proc_adopting-key-manager-service-with-hsm-integration.adoc‎

Lines changed: 191 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,191 @@
1+
:_mod-docs-content-type: PROCEDURE
2+
[id="adopting-key-manager-service-with-hsm-integration_{context}"]
3+
4+
= Adopting the {key_manager} with HSM integration
5+
6+
[role="_abstract"]
7+
When your source {OpenStackPreviousInstaller} environment includes hardware security module (HSM) integration, you must use the HSM-enabled adoption approach to preserve HSM functionality and maintain access to HSM-backed secrets.
8+
9+
.Prerequisites
10+
11+
* The source {OpenStackPreviousInstaller} environment with HSM integration is configured.
12+
* HSM client software and certificates are available from accessible URLs.
13+
* The target {rhos_long} environment with HSM infrastructure is accessible.
14+
* HSM-enabled {key_manager_first_ref} container images are built and available in your registry.
15+
16+
[NOTE]
17+
====
18+
If you use the automated adoption process by setting `barbican_hsm_enabled: true`, the required HSM secrets (`hsm-login` and `proteccio-data`) are created automatically. You only need to manually create the secret when you perform the manual adoption steps.
19+
====
20+
21+
.Procedure
22+
23+
. Confirm that your source environment configuration includes HSM integration:
24+
+
25+
[source,bash]
26+
----
27+
$ ssh tripleo-admin@controller-0.ctlplane \
28+
"sudo cat /var/lib/config-data/puppet-generated/barbican/etc/barbican/barbican.conf | grep -A5 '\[.*plugin\]'"
29+
----
30+
+
31+
If you see `[p11_crypto_plugin]` or other HSM-specific sections, continue with the HSM adoption.
32+
33+
. Extract the simple crypto key encryption keys (KEK) from your source environment:
34+
+
35+
[source,bash]
36+
----
37+
$ SIMPLE_CRYPTO_KEK=$(ssh tripleo-admin@controller-0.ctlplane \
38+
"sudo 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'])\"")
39+
----
40+
41+
. Add the KEK to the target environment:
42+
+
43+
[source,bash]
44+
----
45+
$ oc set data secret/osp-secret "BarbicanSimpleCryptoKEK=${SIMPLE_CRYPTO_KEK}"
46+
----
47+
48+
. If you are not using the automated adoption, create HSM-specific secrets in the target environment:
49+
+
50+
[source,bash]
51+
----
52+
# Create HSM login credentials secret
53+
$ oc create secret generic hsm-login \
54+
--from-literal=PKCS11Pin=<your_hsm_password> \
55+
-n openstack
56+
57+
# Create HSM client configuration and certificates secret
58+
$ oc create secret generic proteccio-data \
59+
--from-file=client.crt=<path_to_client_cert> \
60+
--from-file=client.key=<path_to_client_key> \
61+
--from-file=10_8_60_93.CRT=<path_to_server_cert> \
62+
--from-file=proteccio.rc=<path_to_hsm_config> \
63+
-n openstack
64+
----
65+
+
66+
where:
67+
68+
69+
<your_hsm_password>::
70+
Specifies the HSM password for your {rhos_acro} environment.
71+
<path_to_client_cert>::
72+
Specifies the path to the HSM client certificate.
73+
<path_to_client_key>::
74+
Specifies the path to the client key.
75+
<path_to_server_cert>::
76+
Specifies the path to the server certificate.
77+
<path_to_hsm_config>::
78+
Specifies the path to your HSM configuration in your {rhos_acro} environment.
79+
+
80+
[NOTE]
81+
====
82+
When you use the automated adoption by setting `barbican_hsm_enabled: true`, the `barbican_adoption` role creates these secrets automatically. The secret names default to `hsm-login` and `proteccio-data`.
83+
====
84+
85+
. Patch the `OpenStackControlPlane` custom resource to deploy {key_manager} with HSM support:
86+
+
87+
----
88+
$ oc patch openstackcontrolplane openstack --type=merge --patch '
89+
spec:
90+
barbican:
91+
enabled: true
92+
apiOverride:
93+
route: {}
94+
template:
95+
databaseInstance: openstack
96+
databaseAccount: barbican
97+
rabbitMqClusterName: rabbitmq
98+
secret: osp-secret
99+
simpleCryptoBackendSecret: osp-secret
100+
serviceAccount: barbican
101+
serviceUser: barbican
102+
passwordSelectors:
103+
database: BarbicanDatabasePassword
104+
service: BarbicanPassword
105+
simplecryptokek: BarbicanSimpleCryptoKEK
106+
customServiceConfig: |
107+
[p11_crypto_plugin]
108+
plugin_name = PKCS11
109+
library_path = /usr/lib64/libnethsm.so
110+
token_labels = VHSM1
111+
mkek_label = adoption_mkek_1
112+
hmac_label = adoption_hmac_1
113+
encryption_mechanism = CKM_AES_CBC
114+
hmac_key_type = CKK_GENERIC_SECRET
115+
hmac_keygen_mechanism = CKM_GENERIC_SECRET_KEY_GEN
116+
hmac_mechanism = CKM_SHA256_HMAC
117+
key_wrap_mechanism = CKM_AES_CBC_PAD
118+
key_wrap_generate_iv = true
119+
always_set_cka_sensitive = true
120+
os_locking_ok = false
121+
globalDefaultSecretStore: pkcs11
122+
enabledSecretStores: ["simple_crypto", "pkcs11"]
123+
pkcs11:
124+
loginSecret: hsm-login
125+
clientDataSecret: proteccio-data
126+
clientDataPath: /etc/proteccio
127+
barbicanAPI:
128+
replicas: 1
129+
override:
130+
service:
131+
internal:
132+
metadata:
133+
annotations:
134+
metallb.universe.tf/address-pool: internalapi
135+
metallb.universe.tf/allow-shared-ip: internalapi
136+
metallb.universe.tf/loadBalancerIPs: 172.17.0.80
137+
spec:
138+
type: LoadBalancer
139+
barbicanWorker:
140+
replicas: 1
141+
barbicanKeystoneListener:
142+
replicas: 1
143+
'
144+
----
145+
+
146+
* `library_path` specifies the path to the PKCS#11 library, for example, `/usr/lib64/libnethsm.so` for Proteccio).
147+
* `token_labels` specifies the HSM partition name, for example, `VHSM1`.
148+
* `mkek_label` and `hmac_label` specify key labels that are configured in the HSM.
149+
* `loginSecret` specifies the name of the Kubernetes secret that contains the HSM PIN.
150+
* `clientDataSecret` specifies the name of the Kubernetes secret that contains the HSM certificates and configuration.
151+
152+
.Verification
153+
154+
. Verify that both secret stores are available:
155+
+
156+
[source,bash]
157+
----
158+
$ openstack secret store list
159+
----
160+
161+
. Test the HSM back-end functionality:
162+
+
163+
[source,bash]
164+
----
165+
$ openstack secret store --name "hsm-test-$(date +%s)" \
166+
--payload "test-payload" \
167+
--algorithm aes --mode cbc --bit-length 256
168+
----
169+
170+
. Verify that the migrated secrets are accessible:
171+
+
172+
[source,bash]
173+
----
174+
$ openstack secret list
175+
----
176+
177+
. Check that the {key_manager} services are operational:
178+
+
179+
[source,bash]
180+
----
181+
$ oc get pods -l service=barbican
182+
NAME READY STATUS RESTARTS AGE
183+
barbican-api-5d65949b4-xhkd7 2/2 Running 7 (10m ago) 29d
184+
barbican-keystone-listener-687cbdc77d-4kjnk 2/2 Running 3 (11m ago) 29d
185+
barbican-worker-5c4b947d5c-l9jdh 2/2 Running 3 (11m ago) 29d
186+
----
187+
188+
[NOTE]
189+
====
190+
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.
191+
====

0 commit comments

Comments
 (0)