To find and identify virtual HSMs for your KVM SEL guest (also known as AP queues), create a
.yaml file with one or more entries that describe the configuration of your wanted
HSMs.
About this task
This task may be performed by two parties alternatively:
- The owner of the trusted Linux instance (who normally is the same
as the user of the KVM SEL guest) can retrieve the
necessary values in two ways:
- via direct communication with the trusted TKE domain administrator
- obtain the values from the established KVM SEL guest
- The trusted TKE domain administrator, who establishes the desired
coprocessors can create the configuration file and transmit this to the trusted Linux instance owner. The TKE administrator signs the file and the
KVM SEL guest owner can verify the signature.
The scenario shows the methods how the trusted TKE domain administrator (tke_admin@crypto_sys) can
retrieve the necessary values. This is the same way as the owner of the trusted Linux instance can retrieve these values as the root user from the
KVM SEL guest (root@sel_guest).
The configuration file defines the desired AP queue specifications in a YAML format. Each
configuration must contain the following parameters:
- mode
- the mode specification of the cryptographic coprocessor holding
the desired APQN (see step 1)
- mkvp
- the master key verification pattern (MKVP) of the master key that is set on the desired APQN.
Depending on the environment, in which you are working, there are multiple possibilities to obtain
the MKVP. In most use cases, the trusted TKE domain
- serialnr
- the coprocessor serial number holding the AP queue (see step 3)
- secretid
- the 32-byte ID of the secret that you want to associate with the AP queue (see step 4)
We name our configuration file se_scenario.yaml.
Procedure
-
Define the coprocessor mode.
In our scenario, we are looking for AP queues that run in EP11 mode. Therefore, the first entry in the
se_scenario.yaml file may look similar to the following:
# A configuration file for an EP11 cryptographic coprocessor
- mode: EP11
You find the 32-byte ID of the secret (secretid) in the .yaml file that you generated with
the pvsecret create command in step 1 (in our scenario, for
example, in SECRET1.yaml.
Use the scp command to transfer this configuration file to the KVM SEL guest (just like in step 2).
-
Retrieve the master key verification pattern for the AP queue.
The master key of the desired AP queues that you want to use must be provided by the trusted
HSM coprocessor administrator. In our scenario, one of the desired AP queues is identified by the
APQN
27.0014. The administrator can use the following command to find the
verification pattern of the master key installed on this APQN:
admin@sel_host:~#
cat /sys/devices/ap/card27/27.0014/mkvps
WK CUR: valid 0x8b991263e3a8f4e4be0d5ec8f0a4df9e25a32ebc3b9eda61c9c062ce00000000
WK NEW: empty -
Therefore, the second entry in the
se_scenario.yaml file may look
similar to the following:
mkvp: 0x8b991263e3a8f4e4be0d5ec8f0a4df9e25a32ebc3b9eda61c9c062ce00000000
-
Retrieve the serial number of the coprocessor adapter card holding the desired
APQN.
Like the master key verification pattern, also the serial number of the cryptographic adapter
must be provided by the trusted HSM coprocessor administrator. The administrator can use the
following command to see the serial numbers of the available cryptographic adapters:
admin@sel_host:~# lszcrypt --serial
CARD.DOM TYPE MODE STATUS SERIALNR
----------------------------------------------
...
07 CEX6P EP11-Coproc online 93AAA23P
27 CEX8P EP11-Coproc online 93AADFN5
28 CEX8P EP11-Coproc online 93AADFN9
Note: Currently, the processing of HSM configuration files as described in
Process the HSM configuration file to implement an AP queue configuration requires a serial number of a length of 16 bytes for
coprocessors in
EP11 mode. You retrieve such serial
numbers using the following commands in our scenario:
admin@sel_host:~#
cat /sys/devices/ap/card27/serialnr
93AADFN530083341
cat /sys/devices/ap/card28/serialnr
93AADFN989513726
Because our target AP queue 27.0014 is located on the adapter
identified by the hexadecimal number 27, we use the related serial number from the shown output as
the third entry in the se_scenario.yaml file:
serialnr: 93AADFN530083341
-
Specify the secret ID of the secret that you want to associate to the desired AP
queue.
We intend to use APQNs on adapters X'27' and X'28', so we created two secrets in
Create an association secret for the KVM SEL guest. In files
SECRET1.yaml and
SECRET2.yaml we find the secrete IDs required for this step:
!Association
name: SECRET1
id: 0x03153249db7ce46b0330ffb1a760b59710531af08ec4d7f8424a6870fae49360
!Association
name: SECRET2
id: 0x258499e710e0bd3bb878d6bac7e478b30f3f3e72566989f638c4143d14f6c0b6
Results
With the information that we can retrieve with the shown methods, we now create our
se_scenario.yaml file for the following purpose:
- AP queues
27.0014 and 28.0014 have the same master key and
will be associated with SECRET1 for redundancy in case of fallbacks.
- AP queues
27.0015 and 28.0015 have the same master key and
will be associated with SECRET2 for redundancy in case of fallbacks.
# 27.0014/secret 1
- mode: EP11
mkvp: 0x8b991263e3a8f4e4be0d5ec8f0a4df9e25a32ebc3b9eda61c9c062ce00000000
serialnr: 93AADFN530083341
secretid: 0x03153249db7ce46b0330ffb1a760b59710531af08ec4d7f8424a6870fae49360
# 28.0014/secret 2
-mode: EP11
mkvp: 0x8b991263e3a8f4e4be0d5ec8f0a4df9e25a32ebc3b9eda61c9c062ce00000000
serialnr: 93AADFN989513726
secretid: 0x258499e710e0bd3bb878d6bac7e478b30f3f3e72566989f638c4143d14f6c0b6
# 27.0015/secret 3
-mode: EP11
mkvp: 0x34d6cfdd743f08ff22cd6421deefcd9e174258805b81289eccda94d100000000
serialnr: 93AADFN530083341
secretid: 0xd3feec6cf18265c2749d247beb119dff129cd20aeb127734d8731b7e5dc3b8cf
# 28.0015/secret 2
-mode: EP11
mkvp: 0x34d6cfdd743f08ff22cd6421deefcd9e174258805b81289eccda94d100000000
serialnr: 93AADFN989513726
secretid: 0x2570da8e34d62515cbff1b3c746afe4a86539913f809298365d325eceeae706a
What to do next
Transfer the created HSM configuration file to your KVM SEL guestadmin@sel_host:~# scp se_scenario_running.yaml guest_user@198.51.100.24:~