Debian Codegraph @

doc/README.cca_stdll

raw
1 CCA TOKEN
2
3 Overview
4 --------
5 The CCA token is a secure key token.
6 A Secure key - key value does not exist in the clear outside of the HSM
7 (secure, tamper-resistent boundary of the card). It is a clear key wrapped
8 with the appropriate MasterKey that has been installed into the secure hardware.
9 A clear key is generated in the hardware, wrapped with the appropriate
10 master key that has been installed into the hardware. The wrapped key is then
11 passed back to the invoker. Upon an encryption and/or decryption request,
12 the wrapped key and the data to be encrypted are passed into the hardware.
13 The wrapped key is verified, and the clear key is used to encrypt and/or
14 decrypt the data. All this is done in the CCA hardware.
15
16 Within openCryptoki, this wrapped key value is stored in the CKA_IBM_OPAQUE
17 attribute rather than the CKA_VALUE attribute.
18
19 Pre-requisites:
20 The CCA token requires cca library, libcsulcca.so, which is part of the
21 csulcca rpm.
22 It also requires proper configuration and installation of the MK keys into
23 the hardware which is outside the scope of this document.
24
25 For more details about the CCA token, please also see
26 https://www.ibm.com/docs/en/linux-on-systems?topic=specifications-cca-token
27
28 Configuration
29 -------------
30
31 To use the CCA token a slot entry must be defined in the
32 opencryptoki.conf configuration file that sets the stdll attribute to
33 libpkcs11_cca.so.
34
35 The CCA token also requires that the appropriate master keys have
36 been installed into the hardware. The corresponding driver must also be
37 loaded, i.e. modprobe z90crypt.
38
39 CCA Token Objects
40 -------------------------
41
42 openCryptoki stores token objects on disk. Public token objects are not
43 encrypted. Private token objects are encrypted.
44 Versions of openCryptoki prior to version 3, used a CCA generated secure key
45 (des3 key) and the crypto adapter to encrypt the private token object's data.
46 In version 3, a clear key (DES3 or AES key, dependent on the tokversion setting
47 in opencryptoki.conf) and software crypto (openssl) are used to encrypt this
48 data.
49
50 Migration Information
51 ---------------------
52
53 Migrating version 2 private token objects to version 3 is ONLY required if
54 the system will run openCryptoki version 3 and will use private token
55 objects saved or preserved from version 2.
56 Note, public token objects do not need to be migrated.
57 If there are no private token objects from version 2, then the version 3
58 does not require any migrating.
59
60 In version 2 private token objects are encrypted and decrypted with a secure
61 key in the crypto adapter. In version 3, this encryption and decryption is
62 done with a clear key using software crypto. Therefore, openCryptoki
63 version 3, will not successfully decrypt a version 2 private token object.
64
65 Version 2 private token objects must be "migrated" to version 3 so that
66 openCryptoki version 3 can access these objects. This migration will
67 decrypt the objects using the CCA call, CSNBDEC and the current
68 openCryptoki key stored in MK_USER. The objects will then be re-encrypted
69 using software crypto. The key bits that are stored in MK_USER will then be
70 used as a clear key.
71
72 Once the migration has completed, these private token objects should then be
73 accessible to version 3.
74
75 Migration Steps
76 ---------------
77
78 1. Either update or install version 3.
79 a. Update to openCryptoki version 3. In most Linux distributions, an update
80 from version 2 to version 3 will preserve the contents of the CCA data-store.
81
82 b. Install openCryptoki version 3. In most distributions, an install will
83 remove the contents of the CCA data-store. You will essentially be starting
84 from the beginning and have to initialize the CCA token.
85
86 In this scenario, if a prior version of openCryptoki had been running on the
87 system, and you wanted to preserve your token objects, you will have saved
88 or backed them up somewhere.
89
90 2. Backup the CCA data-store before migrating. It is always a good idea to
91 back up the data in case the migration is unsuccessful or data is corrupted.
92 The data-store is the directory in which the CCA token information is stored
93 on disk. In most distributions it can be found in /var/lib/opencryptoki/ccatok.
94 Within this directory there is,
95
96 MK_USER: The des3 key used for internal on-disk encryption, encrypted
97 under the USER's PIN by software routines
98
99 MK_SO: The des3 key used for internal on-disk encryption, encrypted
100 under the SO's PIN by software routines
101
102 NKTOK.DAT: Token information.
103
104 TOK_OBJ: The directory in which token objects are stored.
105
106 TOK_OBJ/OBJ.IDX: A list of current token objects.
107
108 **NOTE: MK_USER and MK_SO contain the same key, encrypted under
109 different PINs
110
111 3. Ensure no openCryptoki processes are running. Stop the pkcsslotd daemon
112 if it is running.
113
114 4. Run the pkcscca tool to perform the migration.
115 For example,
116 pkcscca -m v2objectsv3 -v
117
118 Note that the "-v" option will allow you to see which objects did and did not
119 get migrated. Specify the "-d" flag if you wish to migrate CCA token objects
120 stored in a data-store different from the default, /var/lib/opencryptoki/ccatok.
121
122 5. (Optional) Removing shared memory may be required to pick up
123 the newly migrated objects.
124
125 CCA token's shared memory segment tracks its token objects.
126 Token objects stored on disk are only loaded into shared memory
127 when the shared memory is created. The shared memory is usually
128 created after a reboot, an install, or an update of the openCryptoki package.
129
130 If another openCryptoki process accessed the CCA token after install
131 or update, then openCryptoki will have loaded all the token objects into
132 shared memory, except for the private token objects requiring migration,
133 since they will have failed decryption. Subsequent calls to the
134 openCryptoki api will not find these objects since they have not
135 been loaded into shared memory. openCryptoki won't read the
136 objects from disk and load into shared memory again until the next time
137 shared memory is created.
138
139 So, in this case, shared memory must be removed and created again so
140 that openCryptoki can successfully load all the token objects including the
141 newly migrated private token objects into CCA token's shared memory segment.
142
143 Remove shared memory if,
144 - after updating or installing, any openCryptoki processes or tools tried
145 to access the CCA token before migrating CCA token's private token
146 objects. For example, the pkcsconf command was run.
147
148 The pre-migrated objects will have failed decryption and not
149 been loaded into shared memory. A reboot or removing shared memory
150 will cause the token to create shared memory again and load the newly
151 migrated private token objects into it.
152
153 CCA's shared memory can be removed two ways.
154 1. a reboot
155
156 2. remove the shared memory file,
157 i.e. "rm /dev/shm/var.lib.opencryptoki.ccatok"
158
159 Notes: (1). Ensure that no openCryptoki processes are running
160 before removing the shared memory. Otherwise, you risk corrupting
161 any running openCryptoki processes.
162 (2). If you have installed openCryptoki manually (not via a distro
163 rpm) the CCA token shared memory segment may be named
164 usr.local.var.lib.opencryptoki.ccatok.
165
166 The next openCryptoki process to run will cause openCryptoki to create
167 a shared memory segment for the token and load the newly migrated objects
168 as well as any other token objects for the token.
169
170 6. After a successful migration, the CCA private token objects should be
171 encrypted and ready to be accessed by openCryptoki version 3.
172
173 7. You may now want to migrate the data stores of the CCA token to a FIPS
174 compliant format using the pkcstok_migrate tool. For details, please see
175 https://www.ibm.com/docs/en/linux-on-systems?topic=tools-pkcstok-migrate
176
177 TroubleShooting:
178 1. If version 3 cannot find the newly migrated CCA private token objects,
179 reboot or remove the shared memory file. This will cause token to create
180 shared memory again and load the newly migrated private token objects
181 into shared memory.
182
183 Key Migration Information
184 -------------------------
185
186 There may be situations when CCA master keys must be changed. All CCA secret
187 and private keys are enciphered (wrapped) with a master key (MK). After a CCA
188 master key is changed, the keys wrapped with an old master key need to be
189 re-enciphered with the new master key. Only openCryptoki keys with attribute
190 CKA_EXTRACTABLE=TRUE can be migrated.
191
192 Key Migration Steps
193 -------------------
194
195 The key migration tool pkcscca can be used to perform the migration of the
196 old CCA master key to the new master key. After a new master key is loaded
197 and set, perform the following steps:
198
199 1. Stop all processes that are currently using openCryptoki with the
200 CCA token.
201
202 2. Make sure pkcsslotd is running.
203
204 3. Back up the token object repository of the CCA token. For example, you can
205 use the following commands:
206
207 cd /var/lib/opencryptoki/cca/
208 tar -cvzf ~/cca/TOK_OBJ_backup.tgz TOK_OBJ
209
210 4. Migrate the keys of the CCA token object repository with the pkcscca
211 migration tool.
212
213 pkcscca -m keys -s <slotid> -k <aes|apka|asym|sym>
214
215 The following parameters are mandatory:
216
217 -s
218 - slot number for the CCA token
219 -k
220 - master key type to be migrated: aes, apka, asym, or sym
221
222 All the specified token objects representing extractable keys that are
223 found for the CCA token, are re-encrypted and ready for use. Keys with an
224 attribute CKA_EXTRACTABLE=FALSE are not migratable.The keys that failed to
225 migrate are displayed to the user.
226
227 5. Re-start the previously stopped openCryptoki processes.