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 <tool_config_file>
17 -source_ldif_file <original_ldif_file>
18 -target_ldif_file <newinstance_ldif_file>
19 -log_file <tool_log_file>
20 [-source_pki_security_database_path <nss_database>
21 -source_storage_token_name <token>
22 -source_storage_certificate_nickname <storage_certificate_nick‐
23 name>
24 -target_storage_certificate_file <new_ASCII_storage_cert>
25 [-source_pki_security_database_pwdfile <password_file>]
26 [-source_kra_naming_context <name> -target_kra_naming_con‐
27 text <name>]
28 [-process_requests_and_key_records_only]
29 [-unwrap_algorithm AES|DES3]
30 The syntax for renumbering keys:
33 KRATool -kratool_config_file <tool_config_file>
36 -source_ldif_file <original_ldif_file>
37 -target_ldif_file <newinstance_ldif_file>
38 -log_file <tool_log_file>
39 [-append_id_offset <prefix_to_add> | -remove_id_offset
40 <prefix_to_remove>]
41 [-source_kra_naming_context <name> -target_kra_naming_con‐
42 text <name>]
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 <tool_config_file>
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 <original_ldif_file>
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 <newinstance_ldif_file>
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 <tool_log_file>
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 <name>
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 in‐
114 stance naming context
115 to the new KRA instance naming context.
116
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 <name>
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 in‐
133 stance to the new KRA instance naming context.
134
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
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 <nss_databases>
155 Gives the full path to the directory which contains the Network Se‐
156 curity Services (NSS) security databases
157 used by the old KRA instance.
158
159 This option is required if any other rewrap parameters are used.
160 -source_storage_token_name <token>
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
167 This option is required if any other rewrap parameters are used.
168 -source_storage_certificate_nickname <storage_certificate_nick‐
171 name>
172 Gives the nickname of the KRA storage certificate for the old KRA
173 instance.
174 Either this certificate will be located in the security database
175 for the old KRA instance
176 or the security database will contain a pointer to the certificate
177 in the hardware token.
178
179 This option is required if any other rewrap parameters are used.
180 -target_storage_certificate_file <new_ASCII_storage_cert>
183 Gives the path and filename of an ASCII-formatted file of the stor‐
184 age certificate for the new KRA instance.
185 The storage certificate should be exported from the new KRA's data‐
186 bases
187 and stored in an accessible location before running KRATool.
188
189 This option is required if any other rewrap parameters are used.
190 -source_pki_security_database_pwdfile <password_file>
193 Gives the path and filename to a password file that contains only
194 the password for the storage token
195 given in the -source_storage_token_name option.
196
197 This argument is optional when other rewrap parameters are used.
198 If this argument is not used, then the script prompts for the pass‐
199 word.
200 -unwrap_algorithm <algorithm>
203 Specifies the symmetric key algorithm used by source KRA. Available
204 options include DES3 and AES
205
206 This argument is optional and defaults to DES3 if unspecified.
207 The following parameters are optional for renumbering keys:
210 -append_id_offset <prefix_to_add>
213 Gives an ID number which will be preprended to every imported key,
214 to prevent possible collisions.
215 A unique ID offset should be used for every KRA instance which has
216 keys exported using KRATool.
217
218 If -append_id_offset is used, then do not use the -remove_id_offset
219 option.
220 -remove_id_offset <prefix_to_remove>
223 Gives an ID number to remove from the beginning of every imported
224 key.
225
226 If -remove_id_offset is used, then do not use the -append_id_offset
227 option.
228
231 The required configuration file instructs the KRATool how to process
232 attributes in the key archival and key request entries in the LDIF
233 file. There are seven types of entries:
234 • CA enrollment requests
237 • TPS enrollment requests
239 • CA key records
241 • TPS key records
243 • CA and TPS recovery requests (which are treated the same in
245 the KRA)
246 • TPS token key recovery requests
248 Each key and key request has an LDAP entry with attributes that are
252 specific to that kind of record. For example, for a recovery request:
253 dn: cn=1,ou=kra,ou=requests,dc=alpha.example.com-pki-kra
256 objectClass: top
257 objectClass: request
258 objectClass: extensibleObject
259 requestId: 011
260 requestState: complete
261 dateOfCreate: 20110121181006Z
262 dateOfModify: 20110524094652Z
263 extdata-kra--005ftrans--005fdeskey: 3#C7#82#0F#5D#97GqY#0Aib#966#E5B#F56#F24n#
264 F#9E#98#B3
265 extdata-public--005fkey: MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDu6E3uG+Ep27bF1
266 yTWvwIDAQAB
267 extdata-archive: true
268 extdata-requesttype: netkeyKeygen
269 extdata-iv--005fs: %F2%67%45%96%41%D7%FF%10
270 extdata-requestversion: 8.1.0
271 extdata-requestortype: NETKEY_RA
272 extdata-keyrecord: 1
273 extdata-wrappeduserprivate: %94%C1%36%D3%EA%4E%36%B5%42%91%AB%47%34%C0%35%A3%6
274 F%E8%10%A9%B1%25%F4%BE%9C%11%D1%B3%3D%90%AB%79
275 extdata-userid: jmagne
276 extdata-keysize: 1024
277 extdata-updatedby: TPS-alpha.example.com-7889
278 extdata-dbstatus: UPDATED
279 extdata-cuid: 40906145C76224192D2B
280 extdata-requeststatus: complete
281 extdata-requestid: 1
282 extdata-result: 1
283 requestType: netkeyKeygen
284 cn: 1
285 creatorsName: cn=directory manager
286 modifiersName: cn=directory manager
287 createTimestamp: 20110122021010Z
288 modifyTimestamp: 20110122021010Z
289 nsUniqueId: b2891805-1dd111b2-a6d7e85f-2c2f0000
290 Much of that information passes through the script processing un‐
294 changed, so it is entered into the new, target KRA just the same. How‐
295 ever, some of those attributes can and should be edited, like the Com‐
296 mon Name (CN) and DN being changed to match the new KRA instance. The
297 fields which can safely be changed are listed in the configuration file
298 for each type of key entry. (Any attribute not listed is not touched
299 by the tool under any circumstances.)
300 If a field should be edited — meaning, the tool can update the record
303 ID number or rename the entry — then the value is set to true in the
304 configuration file. For example, this configuration updates the CN,
305 DN, ID number, last modified date, and associated entry notes for all
306 CA enrollment requests:
307 kratool.ldif.caEnrollmentRequest.cn=true
310 kratool.ldif.caEnrollmentRequest.dateOfModify=true
311 kratool.ldif.caEnrollmentRequest.dn=true
312 kratool.ldif.caEnrollmentRequest.extdata.keyRecord=true
313 kratool.ldif.caEnrollmentRequest.extdata.requestNotes=true
314 kratool.ldif.caEnrollmentRequest.requestId=true
315 If a line is set to true, then the attribute is processed in the LDIF
319 file. By default, all possible attributes are processed. Setting a
320 line to false means that the KRATool skips that attribute and passes
321 the value unchanged. For example, this leaves the last modified time
322 unchanged so that it doesn't update for when the KRATool runs:
323 kratool.ldif.caEnrollmentRequest.dateOfModify=false
326 NOTE: Key enrollments, records, and requests all have an optional notes
330 attribute where administrators can enter notes about the process. When
331 the KRATool runs, it appends a note to that attribute or adds the at‐
332 tribute with information about the tool running, what operations were
333 performed, and a timestamp:
334 extdata-requestnotes: [20110701150056Z]: REWRAPPED the 'existing DES3 symmetric
337 session key' with the '2048-bit RSA public key' obtained from the target storage
338 certificate + APPENDED ID offset '100000000000' + RENAMED source KRA naming con
339 text 'alpha.example.com-pki-kra' to target KRA naming context 'omega.example.com
340 -pki-kra' + PROCESSED requests and key records ONLY!
341 This information is very useful for both audit and maintenance of the
345 KRA, so it is beneficial to keep the extdata.requestNotes parameter for
346 all of the key record types set to true.
347 IMPORTANT: Every parameter line in the default kratool.cfg must be
350 present in the .cfg file used when the tool is invoked. No line can be
351 omitted and every line must have a valid value (true or false). If the
352 file is not properly formatted, the KRATool will fail.
353 The formatting of the .cfg file is the same as the formatting used in
356 the instance CS.cfg files.
357 A default .cfg file is included with the KRATool script. This file
360 (shown in the example entitled Default kratool.cfg File) can be copied
361 and edited into a custom file or edited directly and used with the
362 tool.
363 Default kratool.cfg File
366 kratool.ldif.caEnrollmentRequest._000=########################################
367 kratool.ldif.caEnrollmentRequest._001=## KRA CA Enrollment Request ##
368 kratool.ldif.caEnrollmentRequest._002=########################################
369 kratool.ldif.caEnrollmentRequest._003=## ##
370 kratool.ldif.caEnrollmentRequest._004=## NEVER allow 'KRATOOL' the ability ##
371 kratool.ldif.caEnrollmentRequest._005=## to change the CA 'naming context' ##
372 kratool.ldif.caEnrollmentRequest._006=## data in the following fields: ##
373 kratool.ldif.caEnrollmentRequest._007=## ##
374 kratool.ldif.caEnrollmentRequest._008=## extdata-auth--005ftoken;uid ##
375 kratool.ldif.caEnrollmentRequest._009=## extdata-auth--005ftoken;userid ##
376 kratool.ldif.caEnrollmentRequest._010=## extdata-updatedby ##
377 kratool.ldif.caEnrollmentRequest._011=## ##
378 kratool.ldif.caEnrollmentRequest._012=## NEVER allow 'KRATOOL' the ability ##
379 kratool.ldif.caEnrollmentRequest._013=## to change CA 'numeric' data in ##
380 kratool.ldif.caEnrollmentRequest._014=## the following fields: ##
381 kratool.ldif.caEnrollmentRequest._015=## ##
382 kratool.ldif.caEnrollmentRequest._016=## extdata-requestId ##
383 kratool.ldif.caEnrollmentRequest._017=## ##
384 kratool.ldif.caEnrollmentRequest._018=########################################
385 kratool.ldif.caEnrollmentRequest.cn=true
386 kratool.ldif.caEnrollmentRequest.dateOfModify=true
387 kratool.ldif.caEnrollmentRequest.dn=true
388 kratool.ldif.caEnrollmentRequest.extdata.keyRecord=true
389 kratool.ldif.caEnrollmentRequest.extdata.requestNotes=true
390 kratool.ldif.caEnrollmentRequest.requestId=true
391 kratool.ldif.caKeyRecord._000=#########################################
392 kratool.ldif.caKeyRecord._001=## KRA CA Key Record ##
393 kratool.ldif.caKeyRecord._002=#########################################
394 kratool.ldif.caKeyRecord._003=## ##
395 kratool.ldif.caKeyRecord._004=## NEVER allow 'KRATOOL' the ability ##
396 kratool.ldif.caKeyRecord._005=## to change the CA 'naming context' ##
397 kratool.ldif.caKeyRecord._006=## data in the following fields: ##
398 kratool.ldif.caKeyRecord._007=## ##
399 kratool.ldif.caKeyRecord._008=## archivedBy ##
400 kratool.ldif.caKeyRecord._009=## ##
401 kratool.ldif.caKeyRecord._010=#########################################
402 kratool.ldif.caKeyRecord.cn=true
403 kratool.ldif.caKeyRecord.dateOfModify=true
404 kratool.ldif.caKeyRecord.dn=true
405 kratool.ldif.caKeyRecord.privateKeyData=true
406 kratool.ldif.caKeyRecord.serialno=true
407 kratool.ldif.namingContext._000=############################################
408 kratool.ldif.namingContext._001=## KRA Naming Context Fields ##
409 kratool.ldif.namingContext._002=############################################
410 kratool.ldif.namingContext._003=## ##
411 kratool.ldif.namingContext._004=## NEVER allow 'KRATOOL' the ability to ##
412 kratool.ldif.namingContext._005=## change the CA 'naming context' data ##
413 kratool.ldif.namingContext._006=## in the following 'non-KeyRecord / ##
414 kratool.ldif.namingContext._007=## non-Request' fields (as these records ##
415 kratool.ldif.namingContext._008=## should be removed via the option to ##
416 kratool.ldif.namingContext._009=## process requests and key records only ##
417 kratool.ldif.namingContext._010=## if this is a KRA migration): ##
418 kratool.ldif.namingContext._011=## ##
419 kratool.ldif.namingContext._012=## cn ##
420 kratool.ldif.namingContext._013=## sn ##
421 kratool.ldif.namingContext._014=## uid ##
422 kratool.ldif.namingContext._015=## uniqueMember ##
423 kratool.ldif.namingContext._016=## ##
424 kratool.ldif.namingContext._017=## NEVER allow 'KRATOOL' the ability to ##
425 kratool.ldif.namingContext._018=## change the KRA 'naming context' data ##
426 kratool.ldif.namingContext._019=## in the following 'non-KeyRecord / ##
427 kratool.ldif.namingContext._020=## non-Request' fields (as these records ##
428 kratool.ldif.namingContext._021=## should be removed via the option to ##
429 kratool.ldif.namingContext._022=## process requests and key records only ##
430 kratool.ldif.namingContext._023=## if this is a KRA migration): ##
431 kratool.ldif.namingContext._024=## ##
432 kratool.ldif.namingContext._025=## dc ##
433 kratool.ldif.namingContext._026=## dn ##
434 kratool.ldif.namingContext._027=## uniqueMember ##
435 kratool.ldif.namingContext._028=## ##
436 kratool.ldif.namingContext._029=## NEVER allow 'KRATOOL' the ability to ##
437 kratool.ldif.namingContext._030=## change the TPS 'naming context' data ##
438 kratool.ldif.namingContext._031=## in the following 'non-KeyRecord / ##
439 kratool.ldif.namingContext._032=## non-Request' fields (as these records ##
440 kratool.ldif.namingContext._033=## should be removed via the option to ##
441 kratool.ldif.namingContext._034=## process requests and key records only ##
442 kratool.ldif.namingContext._035=## if this is a KRA migration): ##
443 kratool.ldif.namingContext._036=## ##
444 kratool.ldif.namingContext._037=## uid ##
445 kratool.ldif.namingContext._038=## uniqueMember ##
446 kratool.ldif.namingContext._039=## ##
447 kratool.ldif.namingContext._040=## If '-source_naming_context ##
448 kratool.ldif.namingContext._041=## <original source KRA naming context>' ##
449 kratool.ldif.namingContext._042=## and '-target_naming_context ##
450 kratool.ldif.namingContext._043=## <renamed target KRA naming context> ##
451 kratool.ldif.namingContext._044=## options are specified, ALWAYS ##
452 kratool.ldif.namingContext._045=## require 'KRATOOL' to change the ##
453 kratool.ldif.namingContext._046=## KRA 'naming context' data in ALL of ##
454 kratool.ldif.namingContext._047=## the following fields in EACH of the ##
455 kratool.ldif.namingContext._048=## following types of records: ##
456 kratool.ldif.namingContext._049=## ##
457 kratool.ldif.namingContext._050=## caEnrollmentRequest: ##
458 kratool.ldif.namingContext._051=## ##
459 kratool.ldif.namingContext._052=## dn ##
460 kratool.ldif.namingContext._053=## extdata-auth--005ftoken;user ##
461 kratool.ldif.namingContext._054=## extdata-auth--005ftoken;userdn ##
462 kratool.ldif.namingContext._055=## ##
463 kratool.ldif.namingContext._056=## caKeyRecord: ##
464 kratool.ldif.namingContext._057=## ##
465 kratool.ldif.namingContext._058=## dn ##
466 kratool.ldif.namingContext._059=## ##
467 kratool.ldif.namingContext._060=## recoveryRequest: ##
468 kratool.ldif.namingContext._061=## ##
469 kratool.ldif.namingContext._062=## dn ##
470 kratool.ldif.namingContext._063=## ##
471 kratool.ldif.namingContext._064=## tpsKeyRecord: ##
472 kratool.ldif.namingContext._065=## ##
473 kratool.ldif.namingContext._066=## dn ##
474 kratool.ldif.namingContext._067=## ##
475 kratool.ldif.namingContext._068=## tpsNetkeyKeygenRequest: ##
476 kratool.ldif.namingContext._069=## ##
477 kratool.ldif.namingContext._070=## dn ##
478 kratool.ldif.namingContext._071=## ##
479 kratool.ldif.namingContext._072=## tpsNetkeyKeyRecoveryRequest: ##
480 kratool.ldif.namingContext._073=## ##
481 kratool.ldif.namingContext._074=## dn ##
482 kratool.ldif.namingContext._075=## ##
483 kratool.ldif.namingContext._076=############################################
484 kratool.ldif.recoveryRequest._000=#####################################
485 kratool.ldif.recoveryRequest._001=## KRA CA / TPS Recovery Request ##
486 kratool.ldif.recoveryRequest._002=#####################################
487 kratool.ldif.recoveryRequest.cn=true
488 kratool.ldif.recoveryRequest.dateOfModify=true
489 kratool.ldif.recoveryRequest.dn=true
490 kratool.ldif.recoveryRequest.extdata.requestId=true
491 kratool.ldif.recoveryRequest.extdata.requestNotes=true
492 kratool.ldif.recoveryRequest.extdata.serialnumber=true
493 kratool.ldif.recoveryRequest.requestId=true
494 kratool.ldif.tpsKeyRecord._000=#########################################
495 kratool.ldif.tpsKeyRecord._001=## KRA TPS Key Record ##
496 kratool.ldif.tpsKeyRecord._002=#########################################
497 kratool.ldif.tpsKeyRecord._003=## ##
498 kratool.ldif.tpsKeyRecord._004=## NEVER allow 'KRATOOL' the ability ##
499 kratool.ldif.tpsKeyRecord._005=## to change the TPS 'naming context' ##
500 kratool.ldif.tpsKeyRecord._006=## data in the following fields: ##
501 kratool.ldif.tpsKeyRecord._007=## ##
502 kratool.ldif.tpsKeyRecord._008=## archivedBy ##
503 kratool.ldif.tpsKeyRecord._009=## ##
504 kratool.ldif.tpsKeyRecord._010=#########################################
505 kratool.ldif.tpsKeyRecord.cn=true
506 kratool.ldif.tpsKeyRecord.dateOfModify=true
507 kratool.ldif.tpsKeyRecord.dn=true
508 kratool.ldif.tpsKeyRecord.privateKeyData=true
509 kratool.ldif.tpsKeyRecord.serialno=true
510 kratool.ldif.tpsNetkeyKeygenRequest._000=#####################################
511 kratool.ldif.tpsNetkeyKeygenRequest._001=## KRA TPS Netkey Keygen Request ##
512 kratool.ldif.tpsNetkeyKeygenRequest._002=#####################################
513 kratool.ldif.tpsNetkeyKeygenRequest._003=## ##
514 kratool.ldif.tpsNetkeyKeygenRequest._004=## NEVER allow 'KRATOOL' the ##
515 kratool.ldif.tpsNetkeyKeygenRequest._005=## ability to change the ##
516 kratool.ldif.tpsNetkeyKeygenRequest._006=## TPS 'naming context' data in ##
517 kratool.ldif.tpsNetkeyKeygenRequest._007=## the following fields: ##
518 kratool.ldif.tpsNetkeyKeygenRequest._008=## ##
519 kratool.ldif.tpsNetkeyKeygenRequest._009=## extdata-updatedby ##
520 kratool.ldif.tpsNetkeyKeygenRequest._010=## ##
521 kratool.ldif.tpsNetkeyKeygenRequest._011=#####################################
522 kratool.ldif.tpsNetkeyKeygenRequest.cn=true
523 kratool.ldif.tpsNetkeyKeygenRequest.dateOfModify=true
524 kratool.ldif.tpsNetkeyKeygenRequest.dn=true
525 kratool.ldif.tpsNetkeyKeygenRequest.extdata.keyRecord=true
526 kratool.ldif.tpsNetkeyKeygenRequest.extdata.requestId=true
527 kratool.ldif.tpsNetkeyKeygenRequest.extdata.requestNotes=true
528 kratool.ldif.tpsNetkeyKeygenRequest.requestId=true
529 kratool.ldif.tpsNetkeyKeyRecoveryRequest._000=########################################
530 kratool.ldif.tpsNetkeyKeyRecoveryRequest._001=## KRA TPS Netkey Keyrecovery Request ##
531 kratool.ldif.tpsNetkeyKeyRecoveryRequest._002=########################################
532 kratool.ldif.tpsNetkeyKeyRecoveryRequest._003=## ##
533 kratool.ldif.tpsNetkeyKeyRecoveryRequest._004=## NEVER allow 'KRATOOL' the ability ##
534 kratool.ldif.tpsNetkeyKeyRecoveryRequest._005=## to change the TPS 'naming context'##
535 kratool.ldif.tpsNetkeyKeyRecoveryRequest._006=## data in the following fields: ##
536 kratool.ldif.tpsNetkeyKeyRecoveryRequest._007=## ##
537 kratool.ldif.tpsNetkeyKeyRecoveryRequest._008=## extdata-updatedby ##
538 kratool.ldif.tpsNetkeyKeyRecoveryRequest._009=## ##
539 kratool.ldif.tpsNetkeyKeyRecoveryRequest._010=########################################
540 kratool.ldif.tpsNetkeyKeyRecoveryRequest.cn=true
541 kratool.ldif.tpsNetkeyKeyRecoveryRequest.requestId=true
542 kratool.ldif.tpsNetkeyKeyRecoveryRequest.dn=true
543 kratool.ldif.tpsNetkeyKeyRecoveryRequest.dateOfModify=true
544 kratool.ldif.tpsNetkeyKeyRecoveryRequest.extdata.requestId=true
545 kratool.ldif.tpsNetkeyKeyRecoveryRequest.extdata.requestNotes=true
546
550 The KRATool performs two operations: it can rewrap keys with a new pri‐
551 vate key, and it can renumber attributes in the LDIF file entries for
552 key records, including enrollments and recovery requests. At least one
553 operation (rewrap or renumber) must be performed and both can be per‐
554 formed in a single invocation.
555 Rewrapping Keys
558 When rewrapping keys, the tool needs to be able to access the original
559 NSS databases for the source KRA and its storage certificate to unwrap
560 the keys, as well as the storage certificate for the new KRA, which is
561 used to rewrap the keys.
562 $ KRATool -kratool_config_file KRATool.cfg \
565 -source_ldif_file originalKRA.ldif \
566 -target_ldif_file newKRA.ldif \
567 -log_file kratool.log \
568 -source_pki_security_database_path nssdb \
569 -source_storage_token_name "Internal Key Storage Token" \
570 -source_storage_certificate_nickname "storageCert cert-pki-kra" \
571 -target_storage_certificate_file omega.crt
572 Renumbering Keys
576 When multiple KRA instances are being merged into a single instance, it
577 is important to make sure that no key or request records have conflict‐
578 ing CNs, DNs, serial numbers, or request ID numbers. These values can
579 be processed to append a new, larger number to the existing values.
580 For the CN, the new number is the addition of the original CN plus the
583 appended number. For example, if the CN is 4 and the append number is
584 1000000, the new CN is 1000004.
585 For serial numbers and request IDs, the value is always a digit count
588 plus the value. So a CN of 4 has a serial number of 014, or one digit
589 and the CN value. If the append number is 1000000, the new serial num‐
590 ber is 071000004, for seven digits and then the sum of the append num‐
591 ber (1000000) and the original value (4).
592 $ KRATool -kratool_config_file KRATool.cfg \
595 -source_ldif_file originalKRA.ldif \
596 -target_ldif_file newKRA.ldif \
597 -log_file kratool.log \
598 -append_id_offset 100000000000
599 Restoring the Original Numbering
603 If a number has been appended to key entries, as in the example enti‐
604 tled Renumbering Keys, that number can also be removed. Along with up‐
605 dating the CN, it also reconstructs any associated numbers, like serial
606 numbers and request ID numbers. Undoing a renumbering action may be
607 necessary if the original number wasn't large enough to prevent con‐
608 flicts or as part of testing a migration or KRA consolidation 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 in‐
621 vocation.
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 <mharmsen@redhat.com> and Dinesh Prasanth M K
642 <dmoluguw@redhat.com>.
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)