1PKCSHSM_MK_CHANGE(1) openCryptoki PKCSHSM_MK_CHANGE(1)
2
6 pkcshsm_mk_change - utility to manage and control the re-enciphering of
7 secure keys for a concurrent HSM master key change for openCryptoki.
8
11 pkcshsm_mk_change command [OPTIONS]
12 pkcshsm_mk_change --help|-h
14
17 Manages and controls the re-enciphering of secure keys for a concurrent
18 HSM master key change for openCryptoki. Secure keys are encrypted by
19 the HSM master key(s). The HSM master key(s) must be changed (rolled)
20 from time to time, dependent on policies defined by the HSM security
21 officer. Whenever a HSM master key is changed, all secure keys that are
22 encrypted with that HSM master key must be re-enciphered with the new
23 to be set master key.
24 Changing HSM master keys needs to be coordinated between the HSM secu‐
26 rity officer and an openCryptoki administrator. The HSM security offi‐
27 cer performs a master key change via the TKE (Trusted Key Entry), while
28 the openCryptoki administrator performs administrative steps using the
29 pkcshsm_mk_change tool to re-encipher all openCryptoki token and ses‐
30 sion key objects, as well as currently active crypto operation states
31 with the new master key. Applications using those keys can continue to
32 run, the re-enciphering process takes place transparently to them.
33 A concurrent master key change works as follows:
35 1. The HSM security officer loads the new master keys using the TKE
37 into the NEW register of the set of APQNs logically belonging to‐
38 gether.
39 2. The HSM security officer notifies the openCryptoki administrator
42 that new master keys have been loaded for all the APQNs.
43 3. The openCryptoki administrator uses the pkcshsm_mk_change to ini‐
45 tiate a master key change for openCryptoki, specifying the set of
46 APQNs (and master key types) that are to be changed. The pkc‐
47 shsm_mk_change tool communicates with running applications and
48 performs/controls re-encipherment of the key objects with the new
49 master key.
50 4. When the pkcshsm_mk_change tool has completed its re-encipherment
52 processing, the openCryptoki administrator notifies the HSM secu‐
53 rity officer that openCryptoki is ready to set/activate the new
54 master keys.
55 5. The HSM security officer coordinates with other (non-openCryptoki)
57 applications and once all users of the APQNs are OK, he sets/acti‐
58 vates the new master keys on the APQNs.
59 6. The HSM security officer notifies the openCyptoki administrator
61 when for all APQNs the new master key have been set/activated.
62 7. The openCryptoki administrator uses the pkcshsm_mk_change tool to
64 finalize the master key change for openCryptoki. The tool communi‐
65 cates with running applications and performs/controls finalizing
66 the re-encipherment of the key objects with the new master key.
67 8. When the pkcshsm_mk_change tool has completed its finalizing pro‐
69 cessing, the master key change operation is complete.
70 The whole procedure can take an arbitrary amount of time. Especially
72 the time between the moment when the new master key has been loaded on
73 all APQNs, and the moment the new master keys are set/activated can
74 even last several days, due to time required for coordination with
75 other (non-openCryptoki) applications/users of the APQNs to prepare for
76 the master key change.
77 The time to perform the re-encipherment and finalization (steps 3 and
79 7) of all key objects as such depends on the amount of keys and open‐
80 Cryptoki applications using them, but is usually relatively short, i.e.
81 seconds up to a few minutes.
82 The system where openCryptoki runs may be restarted while a master key
84 change is ongoing, provided that the re-encipherment and finalization
85 steps (steps 3 and 7) are not interrupted.
86 An ongoing master key change operation can be canceled using the pkc‐
88 shsm_mk_change tool, as long as for none of the APQNs the new master
89 key has been set/activated, that is up to step 5 from above.
90
92 Initiate a master key change for openCryptoki
93 pkcshsm_mk_change reencipher [--apqns|-a APQNS] [--ep11-wkvp|-e WKVP]
94 [--cca-sym-mkvp|-s MKVP] [--cca-asym-mkvp|-S MKVP] [--cca-aes-mkvp|-A
95 MKVP] [--cca-apka-mkvp|-p MKVP] [--verbose|-v LEVEL]
96 Use the reencipher command to initiate a master key change operation
98 for the specified APQNs and master key types and re-encipher all ses‐
99 sion and token key objects of the affected tokens. For each master key
100 type that is changed, the verification pattern of the new, to be set
101 master key must be specified.
102 A CryptoExpress adapter in CCA coprocessor mode has 4 different master
104 keys: SYM, ASYM, AES, and APKA. The CCA token of openCryptoki only uses
105 SYM, AES, and APKA. Each master key type can be change individually, or
106 together with others. You can use the TKE or the panel.exe tool to
107 query the master key verification patterns: 'panel.exe --mk-query --mk‐
108 type=<type> --mkregister=NEW'. For master key types SYM and ASYM, use
109 the hex string under [RND], for types AES and APKA use the hex string
110 under [VER]. For AES and APKA you can also find the master key verifi‐
111 cation patterns in sysfs: 'cat /sys/bus/ap/devices/<card>.<do‐
112 main>/mkvps'.
113 A CryptoExpress adapter in EP11 coprocessor mode has only one master
115 key, called the EP11 wrapping key (WK). You can use the TKE or the
116 ep11info tool to query the current wrapping key verification pattern
117 (WKVP) of an EP11 APQN: 'ep11info -m <adapter> -d <domain> -D'. You
118 can also find the wrapping key verification pattern for EP11 APQNs in
119 sysfs: 'cat /sys/bus/ap/devices/<card>.<domain>/mkvps'.
120 the pkcshsm_mk_change reencipher command will query all available slots
122 and determine if the token in the slot is affected by the master key
123 change, based on the list of APQNs and master key types. For each af‐
124 fected slot, it prompts for the USER pin.
125 On successful completion, the id of the master key change operation is
127 displayed. This id must later be specified when finalizing or cancel‐
128 ing the operation using the finalize or cancel command.
129 Finalize a master key change for openCryptoki
131 pkcshsm_mk_change finalize [--id|-i OPERATION-ID] [--verbose|-v LEVEL]
132 Use the finalize command to finalize a master key change operation when
134 the new master key has been activated on the APQNs. The id of the mas‐
135 ter key change operation to finalize must be specified.
136 Cancel a master key change for openCryptoki
138 pkcshsm_mk_change cancel [--id|-i OPERATION-ID] [--verbose|-v LEVEL]
139 Use the cancel command to finalize a master key change operation. The
141 id of the master key change operation to cancel must be specified. A
142 master key change operation can only be canceled as long as for none of
143 the APQNs the new master key have been set/activated.
144 List master key change operations
146 pkcshsm_mk_change list [--id|-i OPERATION-ID] [--verbose|-v LEVEL]
147 Use the list command to list currently active master key change opera‐
149 tions. If no operation ID is specified, all currently active master key
150 change operations are displayed, otherwise only the specified one is
151 displayed.
152
155 -a, --apqns APQNS
156 Specifies a comma separated list of APQNs for which a master key
157 change is to be performed. Each APQN must be specified in the
158 form card.domain, where both card and domain are in hex, as
159 displayed by the lszcrypt command. Multiple APQNs are separated
160 by a comma. This options is only valid with the reencipher com‐
161 mand.
162 -e, --ep11-wkvp WKVP
164 Specifies the EP11 wrapping key verification pattern (WKVP) of
165 the new, to be set EP11 wrapping key as a 16 bytes hex string.
166 This options is only valid with the reencipher command. You can
167 use the TKE or the ep11info tool to query the current wrapping
168 key verification pattern (WKVP) of an EP11 APQN: 'ep11info -m
169 <adapter> -d <domain> -D'. You can also find the wrapping key
170 verification pattern for EP11 APQNs in sysfs: 'cat
171 /sys/bus/ap/devices/<card>.<domain>/mkvps'.
172 -s, --cca-sym-mkvp MKVP
174 Specifies the CCA master key verification pattern (MKVP) of the
175 new, to be set CCA SYM master key as a 8 bytes hex string. This
176 options is only valid with the reencipher command. You can use
177 the TKE or the panel.exe tool to query the master key verifica‐
178 tion patterns: 'panel.exe --mk-query --mktype=SYM --mkregis‐
179 ter=NEW'. Use the hex string under [RND].
180 -S, --cca-asym-mkvp MKVP
182 Specifies the CCA master key verification pattern (MKVP) of the
183 new, to be set CCA ASYM master key as a 8 bytes hex string.
184 This options is only valid with the reencipher command. You can
185 use the TKE or the panel.exe tool to query the master key veri‐
186 fication patterns: 'panel.exe --mk-query --mktype=ASYM --mkreg‐
187 ister=NEW'. Use the hex string under [RND].
188 -A, --cca-aes-mkvp MKVP
190 Specifies the CCA master key verification pattern (MKVP) of the
191 new, to be set CCA AES master key as a 8 bytes hex string. This
192 options is only valid with the reencipher command. You can use
193 the TKE or the panel.exe tool to query the master key verifica‐
194 tion patterns: 'panel.exe --mk-query --mktype=AES --mkregis‐
195 ter=NEW'. Use the hex string under [VER]. You can also find
196 the AES master key verification patterns in sysfs: 'cat
197 /sys/bus/ap/devices/<card>.<domain>/mkvps'.
198 -p, --cca-apka-mkvp MKVP
200 Specifies the CCA master key verification pattern (MKVP) of the
201 new, to be set CCA APKA master key as a 8 bytes hex string.
202 This options is only valid with the reencipher command. You can
203 use the TKE or the panel.exe tool to query the master key veri‐
204 fication patterns: 'panel.exe --mk-query --mktype=APKA --mkreg‐
205 ister=NEW'. Use the hex string under [VER]. You can also find
206 the APKA master key verification patterns in sysfs: 'cat
207 /sys/bus/ap/devices/<card>.<domain>/mkvps'.
208 -i, --id OPERATION-ID
210 Specifies the id of the master key change operation for the fi‐
211 nalize, cancel, or list command. On successful completion of the
212 reencipher command, the id of the master key change operation is
213 displayed.
214 -v, --verbose LEVEL
216 Specifies the verbose level (optional): none (default), error,
217 warn, info, devel, or debug.
218 -h, --help
220 Displays help text and exits.
221
224 opencryptoki(7)
2253.21.0 August 2022 PKCSHSM_MK_CHANGE(1)