1KRATool(1) PKI Key Recovery Authority (KRA) Tool KRATool(1)
2
6 KRATool - Command-Line utility used to export private keys from one or
7 more KRA instances (generally legacy) into a KRA instance (generally
8 modern); during the process of moving the keys, the KRATool can rewrap
9 keys, renumber keys, or both.
10
13 The syntax for rewrapping keys:
14 KRATool -kratool_config_file lt;tool_config_filegt;
17 -source_ldif_file lt;original_ldif_filegt;
18 -target_ldif_file lt;newinstance_ldif_filegt;
19 -log_file lt;tool_log_filegt;
20 [-source_pki_security_database_path lt;nss_databasegt;
21 -source_storage_token_name lt;tokengt;
22 -source_storage_certificate_nickname lt;storage_certificate_nick‐
23 namegt;
24 -target_storage_certificate_file lt;new_ASCII_storage_certgt;
25 [-source_pki_security_database_pwdfile lt;password_filegt;]
26 [-source_kra_naming_context lt;namegt; -target_kra_naming_context
27 lt;namegt;]
28 [-process_requests_and_key_records_only]
29 [-unwrap_algorithm AES|DES3]
30 The syntax for renumbering keys:
33 KRATool -kratool_config_file lt;tool_config_filegt;
36 -source_ldif_file lt;original_ldif_filegt;
37 -target_ldif_file lt;newinstance_ldif_filegt;
38 -log_file lt;tool_log_filegt;
39 [-append_id_offset lt;prefix_to_addgt; | -remove_id_offset lt;pre‐
40 fix_to_removegt;]
41 [-source_kra_naming_context lt;namegt; -target_kra_naming_context
42 lt;namegt;]
43 [-process_requests_and_key_records_only]
44
47 The KRATool command provides a command-line utility used to rewrap
48 keys, renumber keys, or both. For example, some private keys (mainly
49 in older deployments) were wrapped in SHA-1, 1024-bit storage keys when
50 they were archived in the Key Recovery Authority (KRA). These algo‐
51 rithms have become less secure as processor speeds improve and algo‐
52 rithms have been broken. As a security measure, it is possible to re‐
53 wrap the private keys in a new, stronger storage key (SHA-256, 2048-bit
54 keys).
55 Note: Because the KRATool utility can export private keys from one KRA,
58 rewrap them with a new storage key, and then import them into a new
59 KRA, this tool can be used as part of a process of combining multiple
60 KRA instances into a single KRA.
61
64 The following parameters are mandatory for both rewrapping and renum‐
65 bering keys:
66 -kratool_config_file lt;tool_config_filegt;
69 Gives the complete path and filename of the configuration file used
70 by the tool.
71 This configuration process tells the tool how to process certain
72 parameters in the existing key records,
73 whether to apply any formatting changes (like changing the naming
74 context or adding an offset)
75 or even whether to update the modify date.
76 The configuration file is required and a default file is included
77 with the tool.
78 The file format is described in the section entitled Configuration
79 File (.cfg).
80 -source_ldif_file lt;original_ldif_filegt;
83 Gives the complete path and filename of the LDAP Data Interchange
84 Format (LDIF) file
85 which contains all of the key data from the old KRA.
86 -target_ldif_file lt;newinstance_ldif_filegt;
89 Gives the complete path and filename of the LDIF file
90 to which the tool will write all of the key data from the new KRA.
91 This file is created by the tool as it runs.
92 -log_file lt;tool_log_filegt;
95 Gives the path and filename of the log file to use to log the tool
96 progress and messages.
97 This file is created by the tool as it runs.
98 The following parameters are optional for both rewrapping and renumber‐
101 ing keys:
102 -source_kra_naming_context lt;namegt;
105 Gives the naming context of the original KRA instance,
106 the Distinguished Name (DN) element that refers to the original
107 KRA.
108 Key-related LDIF entries have a DN with the KRA instance name in
109 it,
110 such as cn=1,ou=kra,ou=requests,dc=alpha.example.com-pki-kra.
111 The naming context for that entry is the DN value, alpha.exam‐
112 ple.com-pki-kra.
113 These entries can be renamed, automatically, from the old KRA
114 instance naming context
115 to the new KRA instance naming context.
116 nbsp;
117 While this argument is optional, it is recommended because it means
118 that the LDIF file does not have to be edited
119 before it is imported into the target KRA.
120 If this argument is used, then the -target_kra_naming_context argu‐
121 ment must also be used.
122 -target_kra_naming_context lt;namegt;
125 Gives the naming context of the new KRA instance, the name that the
126 original key entries should be changed too.
127 Key-related LDIF entries have a DN with the KRA instance name in
128 it,
129 such as cn=1,ou=kra,ou=requests,dc=omega.example.com-pki-kra.
130 The naming context for that entry is the DN value, omega.exam‐
131 ple.com-pki-kra.
132 These entries can be renamed, automatically, from the old KRA
133 instance to the new KRA instance naming context.
134 nbsp;
135 While this argument is optional, it is recommended because it means
136 that the LDIF file does not have to be edited
137 before it is imported into the target KRA.
138 If this argument is used, then the -source_kra_naming_context argu‐
139 ment must also be used.
140 -process_requests_and_key_records_only
143 Removes configuration entries from the source LDIF file, leaving
144 only the key and request entries.
145 nbsp;
146 While this argument is optional, it is recommended because it means
147 that the LDIF file does not have to be edited
148 before it is imported into the target KRA.
149 The following parameters are optional for rewrapping keys:
152 -source_pki_security_database_path lt;nss_databasesgt;
155 Gives the full path to the directory which contains the Network
156 Security Services (NSS) security databases
157 used by the old KRA instance.
158 nbsp;
159 This option is required if any other rewrap parameters are used.
160 -source_storage_token_name lt;tokengt;
163 Gives the name of the token which stores the KRA data, like Inter‐
164 nal Key Storage Token for internal tokens
165 or a name like NHSM6000-OCS for the hardware token name.
166 nbsp;
167 This option is required if any other rewrap parameters are used.
168 -source_storage_certificate_nickname lt;storage_certificate_nicknamegt;
171 Gives the nickname of the KRA storage certificate for the old KRA
172 instance.
173 Either this certificate will be located in the security database
174 for the old KRA instance
175 or the security database will contain a pointer to the certificate
176 in the hardware token.
177 nbsp;
178 This option is required if any other rewrap parameters are used.
179 -target_storage_certificate_file lt;new_ASCII_storage_certgt;
182 Gives the path and filename of an ASCII-formatted file of the stor‐
183 age certificate for the new KRA instance.
184 The storage certificate should be exported from the new KRA's data‐
185 bases
186 and stored in an accessible location before running KRATool.
187 nbsp;
188 This option is required if any other rewrap parameters are used.
189 -source_pki_security_database_pwdfile lt;password_filegt;
192 Gives the path and filename to a password file that contains only
193 the password for the storage token
194 given in the -source_storage_token_name option.
195 nbsp;
196 This argument is optional when other rewrap parameters are used.
197 If this argument is not used, then the script prompts for the pass‐
198 word.
199 -unwrap_algorithm lt;algorithmgt;
202 Specifies the symmetric key algorithm used by source KRA. Available
203 options include DES3 and AES
204 nbsp;
205 This argument is optional and defaults to DES3 if unspecified.
206 The following parameters are optional for renumbering keys:
209 -append_id_offset lt;prefix_to_addgt;
212 Gives an ID number which will be preprended to every imported key,
213 to prevent possible collisions.
214 A unique ID offset should be used for every KRA instance which has
215 keys exported using KRATool.
216 nbsp;
217 If -append_id_offset is used, then do not use the -remove_id_offset
218 option.
219 -remove_id_offset lt;prefix_to_removegt;
222 Gives an ID number to remove from the beginning of every imported
223 key.
224 nbsp;
225 If -remove_id_offset is used, then do not use the -append_id_offset
226 option.
227
230 The required configuration file instructs the KRATool how to process
231 attributes in the key archival and key request entries in the LDIF
232 file. There are seven types of entries:
233 · CA enrollment requests
236 · TPS enrollment requests
238 · CA key records
240 · TPS key records
242 · CA and TPS recovery requests (which are treated the same in
244 the KRA)
245 · TPS token key recovery requests
247 Each key and key request has an LDAP entry with attributes that are
251 specific to that kind of record. For example, for a recovery request:
252 dn: cn=1,ou=kra,ou=requests,dc=alpha.example.com-pki-kra
255 objectClass: top
256 objectClass: request
257 objectClass: extensibleObject
258 requestId: 011
259 requestState: complete
260 dateOfCreate: 20110121181006Z
261 dateOfModify: 20110524094652Z
262 extdata-kra--005ftrans--005fdeskey: 3#C7#82#0F#5D#97GqY#0Aib#966#E5B#F56#F24n#
263 F#9E#98#B3
264 extdata-public--005fkey: MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDu6E3uG+Ep27bF1
265 yTWvwIDAQAB
266 extdata-archive: true
267 extdata-requesttype: netkeyKeygen
268 extdata-iv--005fs: %F2%67%45%96%41%D7%FF%10
269 extdata-requestversion: 8.1.0
270 extdata-requestortype: NETKEY_RA
271 extdata-keyrecord: 1
272 extdata-wrappeduserprivate: %94%C1%36%D3%EA%4E%36%B5%42%91%AB%47%34%C0%35%A3%6
273 F%E8%10%A9%B1%25%F4%BE%9C%11%D1%B3%3D%90%AB%79
274 extdata-userid: jmagne
275 extdata-keysize: 1024
276 extdata-updatedby: TPS-alpha.example.com-7889
277 extdata-dbstatus: UPDATED
278 extdata-cuid: 40906145C76224192D2B
279 extdata-requeststatus: complete
280 extdata-requestid: 1
281 extdata-result: 1
282 requestType: netkeyKeygen
283 cn: 1
284 creatorsName: cn=directory manager
285 modifiersName: cn=directory manager
286 createTimestamp: 20110122021010Z
287 modifyTimestamp: 20110122021010Z
288 nsUniqueId: b2891805-1dd111b2-a6d7e85f-2c2f0000
289 Much of that information passes through the script processing
293 unchanged, so it is entered into the new, target KRA just the same.
294 However, some of those attributes can and should be edited, like the
295 Common Name (CN) and DN being changed to match the new KRA instance.
296 The fields which can safely be changed are listed in the configuration
297 file for each type of key entry. (Any attribute not listed is not
298 touched by the tool under any circumstances.)
299 If a field should be edited — meaning, the tool can update the record
302 ID number or rename the entry — then the value is set to true in the
303 configuration file. For example, this configuration updates the CN,
304 DN, ID number, last modified date, and associated entry notes for all
305 CA enrollment requests:
306 kratool.ldif.caEnrollmentRequest.cn=true
309 kratool.ldif.caEnrollmentRequest.dateOfModify=true
310 kratool.ldif.caEnrollmentRequest.dn=true
311 kratool.ldif.caEnrollmentRequest.extdata.keyRecord=true
312 kratool.ldif.caEnrollmentRequest.extdata.requestNotes=true
313 kratool.ldif.caEnrollmentRequest.requestId=true
314 If a line is set to true, then the attribute is processed in the LDIF
318 file. By default, all possible attributes are processed. Setting a
319 line to false means that the KRATool skips that attribute and passes
320 the value unchanged. For example, this leaves the last modified time
321 unchanged so that it doesn't update for when the KRATool runs:
322 kratool.ldif.caEnrollmentRequest.dateOfModify=false
325 NOTE: Key enrollments, records, and requests all have an optional notes
329 attribute where administrators can enter notes about the process. When
330 the KRATool runs, it appends a note to that attribute or adds the
331 attribute with information about the tool running, what operations were
332 performed, and a timestamp:
333 extdata-requestnotes: [20110701150056Z]: REWRAPPED the 'existing DES3 symmetric
336 session key' with the '2048-bit RSA public key' obtained from the target storage
337 certificate + APPENDED ID offset '100000000000' + RENAMED source KRA naming con
338 text 'alpha.example.com-pki-kra' to target KRA naming context 'omega.example.com
339 -pki-kra' + PROCESSED requests and key records ONLY!
340 This information is very useful for both audit and maintenance of the
344 KRA, so it is beneficial to keep the extdata.requestNotes parameter for
345 all of the key record types set to true.
346 IMPORTANT: Every parameter line in the default kratool.cfg must be
349 present in the .cfg file used when the tool is invoked. No line can be
350 omitted and every line must have a valid value (true or false). If the
351 file is not properly formatted, the KRATool will fail.
352 The formatting of the .cfg file is the same as the formatting used in
355 the instance CS.cfg files.
356 A default .cfg file is included with the KRATool script. This file
359 (shown in the example entitled Default kratool.cfg File) can be copied
360 and edited into a custom file or edited directly and used with the
361 tool.
362 Default kratool.cfg File
365 kratool.ldif.caEnrollmentRequest._000=########################################
366 kratool.ldif.caEnrollmentRequest._001=## KRA CA Enrollment Request ##
367 kratool.ldif.caEnrollmentRequest._002=########################################
368 kratool.ldif.caEnrollmentRequest._003=## ##
369 kratool.ldif.caEnrollmentRequest._004=## NEVER allow 'KRATOOL' the ability ##
370 kratool.ldif.caEnrollmentRequest._005=## to change the CA 'naming context' ##
371 kratool.ldif.caEnrollmentRequest._006=## data in the following fields: ##
372 kratool.ldif.caEnrollmentRequest._007=## ##
373 kratool.ldif.caEnrollmentRequest._008=## extdata-auth--005ftoken;uid ##
374 kratool.ldif.caEnrollmentRequest._009=## extdata-auth--005ftoken;userid ##
375 kratool.ldif.caEnrollmentRequest._010=## extdata-updatedby ##
376 kratool.ldif.caEnrollmentRequest._011=## ##
377 kratool.ldif.caEnrollmentRequest._012=## NEVER allow 'KRATOOL' the ability ##
378 kratool.ldif.caEnrollmentRequest._013=## to change CA 'numeric' data in ##
379 kratool.ldif.caEnrollmentRequest._014=## the following fields: ##
380 kratool.ldif.caEnrollmentRequest._015=## ##
381 kratool.ldif.caEnrollmentRequest._016=## extdata-requestId ##
382 kratool.ldif.caEnrollmentRequest._017=## ##
383 kratool.ldif.caEnrollmentRequest._018=########################################
384 kratool.ldif.caEnrollmentRequest.cn=true
385 kratool.ldif.caEnrollmentRequest.dateOfModify=true
386 kratool.ldif.caEnrollmentRequest.dn=true
387 kratool.ldif.caEnrollmentRequest.extdata.keyRecord=true
388 kratool.ldif.caEnrollmentRequest.extdata.requestNotes=true
389 kratool.ldif.caEnrollmentRequest.requestId=true
390 kratool.ldif.caKeyRecord._000=#########################################
391 kratool.ldif.caKeyRecord._001=## KRA CA Key Record ##
392 kratool.ldif.caKeyRecord._002=#########################################
393 kratool.ldif.caKeyRecord._003=## ##
394 kratool.ldif.caKeyRecord._004=## NEVER allow 'KRATOOL' the ability ##
395 kratool.ldif.caKeyRecord._005=## to change the CA 'naming context' ##
396 kratool.ldif.caKeyRecord._006=## data in the following fields: ##
397 kratool.ldif.caKeyRecord._007=## ##
398 kratool.ldif.caKeyRecord._008=## archivedBy ##
399 kratool.ldif.caKeyRecord._009=## ##
400 kratool.ldif.caKeyRecord._010=#########################################
401 kratool.ldif.caKeyRecord.cn=true
402 kratool.ldif.caKeyRecord.dateOfModify=true
403 kratool.ldif.caKeyRecord.dn=true
404 kratool.ldif.caKeyRecord.privateKeyData=true
405 kratool.ldif.caKeyRecord.serialno=true
406 kratool.ldif.namingContext._000=############################################
407 kratool.ldif.namingContext._001=## KRA Naming Context Fields ##
408 kratool.ldif.namingContext._002=############################################
409 kratool.ldif.namingContext._003=## ##
410 kratool.ldif.namingContext._004=## NEVER allow 'KRATOOL' the ability to ##
411 kratool.ldif.namingContext._005=## change the CA 'naming context' data ##
412 kratool.ldif.namingContext._006=## in the following 'non-KeyRecord / ##
413 kratool.ldif.namingContext._007=## non-Request' fields (as these records ##
414 kratool.ldif.namingContext._008=## should be removed via the option to ##
415 kratool.ldif.namingContext._009=## process requests and key records only ##
416 kratool.ldif.namingContext._010=## if this is a KRA migration): ##
417 kratool.ldif.namingContext._011=## ##
418 kratool.ldif.namingContext._012=## cn ##
419 kratool.ldif.namingContext._013=## sn ##
420 kratool.ldif.namingContext._014=## uid ##
421 kratool.ldif.namingContext._015=## uniqueMember ##
422 kratool.ldif.namingContext._016=## ##
423 kratool.ldif.namingContext._017=## NEVER allow 'KRATOOL' the ability to ##
424 kratool.ldif.namingContext._018=## change the KRA 'naming context' data ##
425 kratool.ldif.namingContext._019=## in the following 'non-KeyRecord / ##
426 kratool.ldif.namingContext._020=## non-Request' fields (as these records ##
427 kratool.ldif.namingContext._021=## should be removed via the option to ##
428 kratool.ldif.namingContext._022=## process requests and key records only ##
429 kratool.ldif.namingContext._023=## if this is a KRA migration): ##
430 kratool.ldif.namingContext._024=## ##
431 kratool.ldif.namingContext._025=## dc ##
432 kratool.ldif.namingContext._026=## dn ##
433 kratool.ldif.namingContext._027=## uniqueMember ##
434 kratool.ldif.namingContext._028=## ##
435 kratool.ldif.namingContext._029=## NEVER allow 'KRATOOL' the ability to ##
436 kratool.ldif.namingContext._030=## change the TPS 'naming context' data ##
437 kratool.ldif.namingContext._031=## in the following 'non-KeyRecord / ##
438 kratool.ldif.namingContext._032=## non-Request' fields (as these records ##
439 kratool.ldif.namingContext._033=## should be removed via the option to ##
440 kratool.ldif.namingContext._034=## process requests and key records only ##
441 kratool.ldif.namingContext._035=## if this is a KRA migration): ##
442 kratool.ldif.namingContext._036=## ##
443 kratool.ldif.namingContext._037=## uid ##
444 kratool.ldif.namingContext._038=## uniqueMember ##
445 kratool.ldif.namingContext._039=## ##
446 kratool.ldif.namingContext._040=## If '-source_naming_context ##
447 kratool.ldif.namingContext._041=## <original source KRA naming context>' ##
448 kratool.ldif.namingContext._042=## and '-target_naming_context ##
449 kratool.ldif.namingContext._043=## <renamed target KRA naming context> ##
450 kratool.ldif.namingContext._044=## options are specified, ALWAYS ##
451 kratool.ldif.namingContext._045=## require 'KRATOOL' to change the ##
452 kratool.ldif.namingContext._046=## KRA 'naming context' data in ALL of ##
453 kratool.ldif.namingContext._047=## the following fields in EACH of the ##
454 kratool.ldif.namingContext._048=## following types of records: ##
455 kratool.ldif.namingContext._049=## ##
456 kratool.ldif.namingContext._050=## caEnrollmentRequest: ##
457 kratool.ldif.namingContext._051=## ##
458 kratool.ldif.namingContext._052=## dn ##
459 kratool.ldif.namingContext._053=## extdata-auth--005ftoken;user ##
460 kratool.ldif.namingContext._054=## extdata-auth--005ftoken;userdn ##
461 kratool.ldif.namingContext._055=## ##
462 kratool.ldif.namingContext._056=## caKeyRecord: ##
463 kratool.ldif.namingContext._057=## ##
464 kratool.ldif.namingContext._058=## dn ##
465 kratool.ldif.namingContext._059=## ##
466 kratool.ldif.namingContext._060=## recoveryRequest: ##
467 kratool.ldif.namingContext._061=## ##
468 kratool.ldif.namingContext._062=## dn ##
469 kratool.ldif.namingContext._063=## ##
470 kratool.ldif.namingContext._064=## tpsKeyRecord: ##
471 kratool.ldif.namingContext._065=## ##
472 kratool.ldif.namingContext._066=## dn ##
473 kratool.ldif.namingContext._067=## ##
474 kratool.ldif.namingContext._068=## tpsNetkeyKeygenRequest: ##
475 kratool.ldif.namingContext._069=## ##
476 kratool.ldif.namingContext._070=## dn ##
477 kratool.ldif.namingContext._071=## ##
478 kratool.ldif.namingContext._072=## tpsNetkeyKeyRecoveryRequest: ##
479 kratool.ldif.namingContext._073=## ##
480 kratool.ldif.namingContext._074=## dn ##
481 kratool.ldif.namingContext._075=## ##
482 kratool.ldif.namingContext._076=############################################
483 kratool.ldif.recoveryRequest._000=#####################################
484 kratool.ldif.recoveryRequest._001=## KRA CA / TPS Recovery Request ##
485 kratool.ldif.recoveryRequest._002=#####################################
486 kratool.ldif.recoveryRequest.cn=true
487 kratool.ldif.recoveryRequest.dateOfModify=true
488 kratool.ldif.recoveryRequest.dn=true
489 kratool.ldif.recoveryRequest.extdata.requestId=true
490 kratool.ldif.recoveryRequest.extdata.requestNotes=true
491 kratool.ldif.recoveryRequest.extdata.serialnumber=true
492 kratool.ldif.recoveryRequest.requestId=true
493 kratool.ldif.tpsKeyRecord._000=#########################################
494 kratool.ldif.tpsKeyRecord._001=## KRA TPS Key Record ##
495 kratool.ldif.tpsKeyRecord._002=#########################################
496 kratool.ldif.tpsKeyRecord._003=## ##
497 kratool.ldif.tpsKeyRecord._004=## NEVER allow 'KRATOOL' the ability ##
498 kratool.ldif.tpsKeyRecord._005=## to change the TPS 'naming context' ##
499 kratool.ldif.tpsKeyRecord._006=## data in the following fields: ##
500 kratool.ldif.tpsKeyRecord._007=## ##
501 kratool.ldif.tpsKeyRecord._008=## archivedBy ##
502 kratool.ldif.tpsKeyRecord._009=## ##
503 kratool.ldif.tpsKeyRecord._010=#########################################
504 kratool.ldif.tpsKeyRecord.cn=true
505 kratool.ldif.tpsKeyRecord.dateOfModify=true
506 kratool.ldif.tpsKeyRecord.dn=true
507 kratool.ldif.tpsKeyRecord.privateKeyData=true
508 kratool.ldif.tpsKeyRecord.serialno=true
509 kratool.ldif.tpsNetkeyKeygenRequest._000=#####################################
510 kratool.ldif.tpsNetkeyKeygenRequest._001=## KRA TPS Netkey Keygen Request ##
511 kratool.ldif.tpsNetkeyKeygenRequest._002=#####################################
512 kratool.ldif.tpsNetkeyKeygenRequest._003=## ##
513 kratool.ldif.tpsNetkeyKeygenRequest._004=## NEVER allow 'KRATOOL' the ##
514 kratool.ldif.tpsNetkeyKeygenRequest._005=## ability to change the ##
515 kratool.ldif.tpsNetkeyKeygenRequest._006=## TPS 'naming context' data in ##
516 kratool.ldif.tpsNetkeyKeygenRequest._007=## the following fields: ##
517 kratool.ldif.tpsNetkeyKeygenRequest._008=## ##
518 kratool.ldif.tpsNetkeyKeygenRequest._009=## extdata-updatedby ##
519 kratool.ldif.tpsNetkeyKeygenRequest._010=## ##
520 kratool.ldif.tpsNetkeyKeygenRequest._011=#####################################
521 kratool.ldif.tpsNetkeyKeygenRequest.cn=true
522 kratool.ldif.tpsNetkeyKeygenRequest.dateOfModify=true
523 kratool.ldif.tpsNetkeyKeygenRequest.dn=true
524 kratool.ldif.tpsNetkeyKeygenRequest.extdata.keyRecord=true
525 kratool.ldif.tpsNetkeyKeygenRequest.extdata.requestId=true
526 kratool.ldif.tpsNetkeyKeygenRequest.extdata.requestNotes=true
527 kratool.ldif.tpsNetkeyKeygenRequest.requestId=true
528 kratool.ldif.tpsNetkeyKeyRecoveryRequest._000=########################################
529 kratool.ldif.tpsNetkeyKeyRecoveryRequest._001=## KRA TPS Netkey Keyrecovery Request ##
530 kratool.ldif.tpsNetkeyKeyRecoveryRequest._002=########################################
531 kratool.ldif.tpsNetkeyKeyRecoveryRequest._003=## ##
532 kratool.ldif.tpsNetkeyKeyRecoveryRequest._004=## NEVER allow 'KRATOOL' the ability ##
533 kratool.ldif.tpsNetkeyKeyRecoveryRequest._005=## to change the TPS 'naming context'##
534 kratool.ldif.tpsNetkeyKeyRecoveryRequest._006=## data in the following fields: ##
535 kratool.ldif.tpsNetkeyKeyRecoveryRequest._007=## ##
536 kratool.ldif.tpsNetkeyKeyRecoveryRequest._008=## extdata-updatedby ##
537 kratool.ldif.tpsNetkeyKeyRecoveryRequest._009=## ##
538 kratool.ldif.tpsNetkeyKeyRecoveryRequest._010=########################################
539 kratool.ldif.tpsNetkeyKeyRecoveryRequest.cn=true
540 kratool.ldif.tpsNetkeyKeyRecoveryRequest.requestId=true
541 kratool.ldif.tpsNetkeyKeyRecoveryRequest.dn=true
542 kratool.ldif.tpsNetkeyKeyRecoveryRequest.dateOfModify=true
543 kratool.ldif.tpsNetkeyKeyRecoveryRequest.extdata.requestId=true
544 kratool.ldif.tpsNetkeyKeyRecoveryRequest.extdata.requestNotes=true
545
549 The KRATool performs two operations: it can rewrap keys with a new pri‐
550 vate key, and it can renumber attributes in the LDIF file entries for
551 key records, including enrollments and recovery requests. At least one
552 operation (rewrap or renumber) must be performed and both can be per‐
553 formed in a single invocation.
554 Rewrapping Keys
557 When rewrapping keys, the tool needs to be able to access the original
558 NSS databases for the source KRA and its storage certificate to unwrap
559 the keys, as well as the storage certificate for the new KRA, which is
560 used to rewrap the keys.
561 $ KRATool -kratool_config_file KRATool.cfg \
564 -source_ldif_file originalKRA.ldif \
565 -target_ldif_file newKRA.ldif \
566 -log_file kratool.log \
567 -source_pki_security_database_path nssdb \
568 -source_storage_token_name "Internal Key Storage Token" \
569 -source_storage_certificate_nickname "storageCert cert-pki-kra" \
570 -target_storage_certificate_file omega.crt
571 Renumbering Keys
575 When multiple KRA instances are being merged into a single instance, it
576 is important to make sure that no key or request records have conflict‐
577 ing CNs, DNs, serial numbers, or request ID numbers. These values can
578 be processed to append a new, larger number to the existing values.
579 For the CN, the new number is the addition of the original CN plus the
582 appended number. For example, if the CN is 4 and the append number is
583 1000000, the new CN is 1000004.
584 For serial numbers and request IDs, the value is always a digit count
587 plus the value. So a CN of 4 has a serial number of 014, or one digit
588 and the CN value. If the append number is 1000000, the new serial num‐
589 ber is 071000004, for seven digits and then the sum of the append num‐
590 ber (1000000) and the original value (4).
591 $ KRATool -kratool_config_file KRATool.cfg \
594 -source_ldif_file originalKRA.ldif \
595 -target_ldif_file newKRA.ldif \
596 -log_file kratool.log \
597 -append_id_offset 100000000000
598 Restoring the Original Numbering
602 If a number has been appended to key entries, as in the example enti‐
603 tled Renumbering Keys, that number can also be removed. Along with
604 updating the CN, it also reconstructs any associated numbers, like
605 serial numbers and request ID numbers. Undoing a renumbering action
606 may be necessary if the original number wasn't large enough to prevent
607 conflicts or as part of testing a migration or KRA consolidation
608 process.
609 $ KRATool -kratool_config_file KRATool.cfg \
612 -source_ldif_file originalKRA.ldif \
613 -target_ldif_file newKRA.ldif \
614 -log_file kratool.log \
615 -remove_id_offset 100000000000
616 Renumbering and Rewrapping in a Single Command
620 Rewrapping and renumbering operations can be performed in the same
621 invocation.
622 $ KRATool -kratool_config_file KRATool.cfg \
625 -source_ldif_file originalKRA.ldif \
626 -target_ldif_file newKRA.ldif \
627 -log_file kratool.log \
628 -source_pki_security_database_path nssdb \
629 -source_storage_token_name "Internal Key Storage Token" \
630 -source_storage_certificate_nickname "storageCert cert-pki-kra" \
631 -target_storage_certificate_file omega.crt \
632 -append_id_offset 100000000000
633
637 pki(1)
638
641 Matthew Harmsen lt;mharmsen@redhat.comgt; and Dinesh Prasanth M K
642 lt;dmoluguw@redhat.comgt;.
643
646 Copyright (c) 2019 Red Hat, Inc. This is licensed under the GNU Gen‐
647 eral Public License, version 2 (GPLv2). A copy of this license is
648 available at http://www.gnu.org/licenses/old-licenses/gpl-2.0.txt.
649PKI Sep 11, 2019 KRATool(1)