1KRATool(1)           PKI Key Recovery Authority (KRA) Tool          KRATool(1)
2
3
4

NAME

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
11

SYNOPSIS

13       The syntax for rewrapping keys:
14
15              KRATool -kratool_config_file </path/to/tool_config_file>
16                   -source_ldif_file </path/to/original_ldif_file>
17                   -target_ldif_file </path/to/newinstance_ldif_file>
18                   -log_file </path/to/tool_log_file>
19                   [-source_pki_security_database_path </path/to/nss_databases>
20                   -source_storage_token_name </path/to/token>
21                   -source_storage_certificate_nickname <storage_certificate_nickname>
22                   -target_storage_certificate_file </path/to/new_ASCII_storage_cert>
23                   [-source_pki_security_database_pwdfile </path/to/password_file>]]
24                   [-source_kra_naming_context <name> -target_kra_naming_context <name>]
25                   [-process_requests_and_key_records_only]
26
27       The syntax for renumbering keys:
28
29              KRATool -kratool_config_file </path/to/tool_config_file>
30                   -source_ldif_file </path/to/original_ldif_file>
31                   -target_ldif_file </path/to/newinstance_ldif_file>
32                   -log_file </path/to/tool_log_file>
33                   [-append_id_offset <prefix_to_add> | -remove_id_offset <prefix_to_remove>]
34                   [-source_kra_naming_context <name> -target_kra_naming_context <name>]
35                   [-process_requests_and_key_records_only]
36
37

DESCRIPTION

39       The KRATool command provides a  command-line  utility  used  to  rewrap
40       keys,  renumber  keys, or both.  For example, some private keys (mainly
41       in older deployments) were wrapped in SHA-1, 1024-bit storage keys when
42       they  were  archived  in  the Key Recovery Authority (KRA). These algo‐
43       rithms have become less secure as processor speeds  improve  and  algo‐
44       rithms  have  been broken. As a security measure, it is possible to re‐
45       wrap the private keys in a new, stronger storage key (SHA-256, 2048-bit
46       keys).
47
48       Note:  Because  the  KRATool  utility  can export private keys from one
49              KRA, rewrap them with a new storage key, and  then  import  them
50              into  a  new  KRA, this tool can be used as part of a process of
51              combining multiple KRA instances into a single KRA.
52
53

OPTIONS

55       The following parameters are mandatory for both rewrapping  and  renum‐
56       bering keys:
57
58       -kratool_config_file </path/to/tool_config_file>
59              Gives  the  complete path and filename of the configuration file
60              used by the tool. This configuration process tells the tool  how
61              to  process  certain  parameters  in  the  existing key records,
62              whether to apply any formatting changes (like changing the  nam‐
63              ing  context  or adding an offset) or even whether to update the
64              modify date. The configuration file is required  and  a  default
65              file  is included with the tool. The file format is described in
66              the section entitled Configuration File (.cfg).
67
68
69       -source_ldif_file </path/to/original_ldif_file>
70              Gives the complete path and filename of the  Lightweight  Direc‐
71              tory  Access Protocol (LDAP) Data Interchange Format (LDIF) file
72              which contains all of the key data from the old KRA.
73
74
75       -target_ldif_file </path/to/newinstance_ldif_file>
76              Gives the complete path and filename of the LDIF file  to  which
77              the  tool  will write all of the key data from the new KRA. This
78              file is created by the tool as it runs.
79
80
81       -log_file </path/to/tool_log_file>
82              Gives the path and filename of the log file to use  to  log  the
83              tool  progress and messages. This file is created by the tool as
84              it runs.
85
86
87       The following parameters are optional for both rewrapping and renumber‐
88       ing keys:
89
90
91       -source_kra_naming_context <name>
92              Gives  the naming context of the original KRA instance, the Dis‐
93              tinguished Name (DN) element that refers to  the  original  KRA.
94              Key-related LDIF entries have a DN with the KRA instance name in
95              it,  such  as  cn=1,ou=kra,ou=requests,dc=alpha.example.com-pki-
96              kra.  The  naming  context  for  that  entry  is  the  DN value,
97              alpha.example.com-pki-kra. These entries can be  renamed,  auto‐
98              matically,  from  the old KRA instance naming context to the new
99              KRA instance naming context.
100
101              While this argument is optional, it is  recommended  because  it
102              means that the LDIF file does not have to be edited before it is
103              imported into the target KRA.  If this argument  is  used,  then
104              the -target_kra_naming_context argument must also be used.
105
106
107       -target_kra_naming_context <name>
108              Gives  the naming context of the new KRA instance, the name that
109              the original key entries should be changed too. Key-related LDIF
110              entries  have  a  DN  with  the KRA instance name in it, such as
111              cn=1,ou=kra,ou=requests,dc=omega.example.com-pki-kra. The naming
112              context  for  that entry is the DN value, omega.example.com-pki-
113              kra.These entries can be renamed, automatically,  from  the  old
114              KRA instance to the new KRA instance naming context.
115
116              While  this  argument  is optional, it is recommended because it
117              means that the LDIF file does not have to be edited before it is
118              imported  into  the  target KRA.  If this argument is used, then
119              the -source_kra_naming_context argument must also be used.
120
121
122       -process_requests_and_key_records_only
123              Removes configuration entries from the source LDIF file, leaving
124              only the key and request entries.
125
126              While  this  argument  is optional, it is recommended because it
127              means that the LDIF file does not have to be edited before it is
128              imported into the target KRA.
129
130
131       The following parameters are optional for rewrapping keys:
132
133
134       -source_pki_security_database_path </path/to/nss_databases>
135              Gives  the full path to the directory which contains the Network
136              Security Services (NSS) security databases used by the  old  KRA
137              instance.
138
139              This option is required if any other rewrap parameters are used.
140
141
142       -source_storage_token_name </path/to/token>
143              Gives  the  name  of  the  token which stores the KRA data, like
144              Internal Key Storage Token for internal tokens or  a  name  like
145              NHSM6000-OCS for the hardware token name.
146
147              This option is required if any other rewrap parameters are used.
148
149
150       -source_storage_certificate_nickname <storage_certificate_nickname>
151              Gives  the  nickname  of the KRA storage certificate for the old
152              KRA instance. Either this certificate will  be  located  in  the
153              security database for the old KRA instance or the security data‐
154              base will contain a pointer to the certificate in  the  hardware
155              token.
156
157              This option is required if any other rewrap parameters are used.
158
159
160       -target_storage_certificate_file </path/to/new_ASCII_storage_cert>
161              Gives  the  path  and filename of an ASCII-formatted file of the
162              storage certificate for the new KRA instance. The  storage  cer‐
163              tificate  should  be  exported  from the new KRA's databases and
164              stored in an accessible location before running KRATool.
165
166              This option is required if any other rewrap parameters are used.
167
168
169       -source_pki_security_database_pwdfile </path/to/password_file>
170              Gives the path and filename to a  password  file  that  contains
171              only   the   password   for  the  storage  token  given  in  the
172              -source_storage_token_name option.
173
174              This argument is optional when other rewrap parameters are used.
175              If  this  argument  is not used, then the script prompts for the
176              password.
177
178
179       The following parameters are optional for renumbering keys:
180
181
182       -append_id_offset <prefix_to_add>
183              Gives an ID number which will be preprended  to  every  imported
184              key,  to  prevent possible collisions. A unique ID offset should
185              be used for every KRA instance which  has  keys  exported  using
186              KRATool.
187
188              If   -append_id_offset   is   used,   then   do   not   use  the
189              -remove_id_offset option.
190
191
192       -remove_id_offset <prefix_to_remove>
193              Gives an ID  number  to  remove  from  the  beginning  of  every
194              imported key.
195
196              If   -remove_id_offset   is   used,   then   do   not   use  the
197              -append_id_offset option.
198
199

Configuration File (.cfg)

201       The required configuration file instructs the KRATool  how  to  process
202       attributes  in  the  key  archival  and key request entries in the LDIF
203       file. There are six types of entries:
204
205              * CA enrollment requests * TPS  enrollment  requests  *  CA  key
206              records  * TPS key records * CA and TPS recovery requests (which
207              are treated the same in the KRA)
208
209       Each key and key request has an LDAP entry  with  attributes  that  are
210       specific to that kind of record. For example, for a recovery request:
211
212              dn: cn=1,ou=kra,ou=requests,dc=alpha.example.com-pki-kra
213              objectClass: top
214              objectClass: request
215              objectClass: extensibleObject
216              requestId: 011
217              requestState: complete
218              dateOfCreate: 20110121181006Z
219              dateOfModify: 20110524094652Z
220              extdata-kra--005ftrans--005fdeskey: 3#C7#82#0F#5D#97GqY#0Aib#966#E5B#F56#F24n#
221               F#9E#98#B3
222              extdata-public--005fkey: MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDu6E3uG+Ep27bF1
223               yTWvwIDAQAB
224              extdata-archive: true
225              extdata-requesttype: netkeyKeygen
226              extdata-iv--005fs: %F2%67%45%96%41%D7%FF%10
227              extdata-requestversion: 8.1.0
228              extdata-requestortype: NETKEY_RA
229              extdata-keyrecord: 1
230              extdata-wrappeduserprivate: %94%C1%36%D3%EA%4E%36%B5%42%91%AB%47%34%C0%35%A3%6
231               F%E8%10%A9%B1%25%F4%BE%9C%11%D1%B3%3D%90%AB%79
232              extdata-userid: jmagne
233              extdata-keysize: 1024
234              extdata-updatedby: TPS-alpha.example.com-7889
235              extdata-dbstatus: UPDATED
236              extdata-cuid: 40906145C76224192D2B
237              extdata-requeststatus: complete
238              extdata-requestid: 1
239              extdata-result: 1
240              requestType: netkeyKeygen
241              cn: 1
242              creatorsName: cn=directory manager
243              modifiersName: cn=directory manager
244              createTimestamp: 20110122021010Z
245              modifyTimestamp: 20110122021010Z
246              nsUniqueId: b2891805-1dd111b2-a6d7e85f-2c2f0000
247
248       Much of that information passes through the script processing unchanged, so it is entered into the new, target KRA just the same. However, some of those attributes can and should be edited, like the Common Name (CN) and DN being changed to match the new KRA instance. The fields which can safely be changed are listed in the configuration file for each type of key entry. (Any attribute not listed is not touched by the tool under any circumstances.)
249
250       If a field /fIshould/fP be edited — meaning, the tool can update the record ID number or rename the entry — then the value is set to true in the configuration file. For example, this configuration updates the CN, DN, ID number, last modified date, and associated entry notes for all CA enrollment requests:
251
252              kratool.ldif.caEnrollmentRequest.cn=true
253              kratool.ldif.caEnrollmentRequest.dateOfModify=true
254              kratool.ldif.caEnrollmentRequest.dn=true
255              kratool.ldif.caEnrollmentRequest.extdata.keyRecord=true
256              kratool.ldif.caEnrollmentRequest.extdata.requestNotes=true
257              kratool.ldif.caEnrollmentRequest.requestId=true
258
259       If a line is set to true, then the attribute is processed in the LDIF file. By default, all possible attributes are processed. Setting a line to false means that the KRATool skips that attribute and passes the value unchanged. For example, this leaves the last modified time unchanged so that it doesn't update for when the KRATool runs:
260
261              kratool.ldif.caEnrollmentRequest.dateOfModify=false
262
263       NOTE:  Key enrollments, records, and requests all have an optional notes attribute where administrators can enter notes about the process. When the KRATool runs, it appends a note to that attribute or adds the attribute with information about the tool running, what operations were performed, and a timestamp:
264
265              extdata-requestnotes: [20110701150056Z]: REWRAPPED the 'existing DES3 symmetric session key' with the '2048-bit RSA public key' obtained from the target storage certificate + APPENDED ID offset '100000000000' + RENAMED source KRA naming context 'alpha.example.com-pki-kra' to target KRA naming context 'omega.example.com-pki-kra' + PROCESSED requests and key records ONLY!
266
267              This information is very useful for both audit and maintenance of the KRA, so it is beneficial to keep the extdata.requestNotes parameter for all of the key record types set to true.
268
269
270       IMPORTANT:
271              Every parameter line in the default kratool.cfg must be present in the .cfg file used when the tool is invoked. No line can be omitted and every line must have a valid value (true or false). If the file is not properly formatted, the KRATool will fail.
272
273
274       The formatting of the .cfg file is the same as the formatting used in the instance CS.cfg files.
275
276
277       A default .cfg file is included with the KRATool script. This file (shown in the example entitled Default kratool.cfg File) can be copied and edited into a custom file or edited directly and used with the tool.
278
279
280   Default kratool.cfg File
281
282
283              kratool.ldif.caEnrollmentRequest._000=########################################
284              kratool.ldif.caEnrollmentRequest._001=##     KRA CA Enrollment Request      ##
285              kratool.ldif.caEnrollmentRequest._002=########################################
286              kratool.ldif.caEnrollmentRequest._003=##                                    ##
287              kratool.ldif.caEnrollmentRequest._004=##  NEVER allow 'KRATOOL' the ability ##
288              kratool.ldif.caEnrollmentRequest._005=##  to change the CA 'naming context' ##
289              kratool.ldif.caEnrollmentRequest._006=##  data in the following fields:     ##
290              kratool.ldif.caEnrollmentRequest._007=##                                    ##
291              kratool.ldif.caEnrollmentRequest._008=##    extdata-auth--005ftoken;uid     ##
292              kratool.ldif.caEnrollmentRequest._009=##    extdata-auth--005ftoken;userid  ##
293              kratool.ldif.caEnrollmentRequest._010=##    extdata-updatedby               ##
294              kratool.ldif.caEnrollmentRequest._011=##                                    ##
295              kratool.ldif.caEnrollmentRequest._012=##  NEVER allow 'KRATOOL' the ability ##
296              kratool.ldif.caEnrollmentRequest._013=##  to change CA 'numeric' data in    ##
297              kratool.ldif.caEnrollmentRequest._014=##  the following fields:             ##
298              kratool.ldif.caEnrollmentRequest._015=##                                    ##
299              kratool.ldif.caEnrollmentRequest._016=##    extdata-requestId               ##
300              kratool.ldif.caEnrollmentRequest._017=##                                    ##
301              kratool.ldif.caEnrollmentRequest._018=########################################
302              kratool.ldif.caEnrollmentRequest.cn=true
303              kratool.ldif.caEnrollmentRequest.dateOfModify=true
304              kratool.ldif.caEnrollmentRequest.dn=true
305              kratool.ldif.caEnrollmentRequest.extdata.keyRecord=true
306              kratool.ldif.caEnrollmentRequest.extdata.requestNotes=true
307              kratool.ldif.caEnrollmentRequest.requestId=true
308              kratool.ldif.caKeyRecord._000=#########################################
309              kratool.ldif.caKeyRecord._001=##          KRA CA Key Record          ##
310              kratool.ldif.caKeyRecord._002=#########################################
311              kratool.ldif.caKeyRecord._003=##                                     ##
312              kratool.ldif.caKeyRecord._004=##  NEVER allow 'KRATOOL' the ability  ##
313              kratool.ldif.caKeyRecord._005=##  to change the CA 'naming context'  ##
314              kratool.ldif.caKeyRecord._006=##  data in the following fields:      ##
315              kratool.ldif.caKeyRecord._007=##                                     ##
316              kratool.ldif.caKeyRecord._008=##    archivedBy                       ##
317              kratool.ldif.caKeyRecord._009=##                                     ##
318              kratool.ldif.caKeyRecord._010=#########################################
319              kratool.ldif.caKeyRecord.cn=true
320              kratool.ldif.caKeyRecord.dateOfModify=true
321              kratool.ldif.caKeyRecord.dn=true
322              kratool.ldif.caKeyRecord.privateKeyData=true
323              kratool.ldif.caKeyRecord.serialno=true
324              kratool.ldif.namingContext._000=############################################
325              kratool.ldif.namingContext._001=##       KRA Naming Context Fields        ##
326              kratool.ldif.namingContext._002=############################################
327              kratool.ldif.namingContext._003=##                                        ##
328              kratool.ldif.namingContext._004=##  NEVER allow 'KRATOOL' the ability to  ##
329              kratool.ldif.namingContext._005=##  change the CA 'naming context' data   ##
330              kratool.ldif.namingContext._006=##  in the following 'non-KeyRecord /     ##
331              kratool.ldif.namingContext._007=##  non-Request' fields (as these records ##
332              kratool.ldif.namingContext._008=##  should be removed via the option to   ##
333              kratool.ldif.namingContext._009=##  process requests and key records only ##
334              kratool.ldif.namingContext._010=##  if this is a KRA migration):          ##
335              kratool.ldif.namingContext._011=##                                        ##
336              kratool.ldif.namingContext._012=##    cn                                  ##
337              kratool.ldif.namingContext._013=##    sn                                  ##
338              kratool.ldif.namingContext._014=##    uid                                 ##
339              kratool.ldif.namingContext._015=##    uniqueMember                        ##
340              kratool.ldif.namingContext._016=##                                        ##
341              kratool.ldif.namingContext._017=##  NEVER allow 'KRATOOL' the ability to  ##
342              kratool.ldif.namingContext._018=##  change the KRA 'naming context' data  ##
343              kratool.ldif.namingContext._019=##  in the following 'non-KeyRecord /     ##
344              kratool.ldif.namingContext._020=##  non-Request' fields (as these records ##
345              kratool.ldif.namingContext._021=##  should be removed via the option to   ##
346              kratool.ldif.namingContext._022=##  process requests and key records only ##
347              kratool.ldif.namingContext._023=##  if this is a KRA migration):          ##
348              kratool.ldif.namingContext._024=##                                        ##
349              kratool.ldif.namingContext._025=##      dc                                ##
350              kratool.ldif.namingContext._026=##      dn                                ##
351              kratool.ldif.namingContext._027=##      uniqueMember                      ##
352              kratool.ldif.namingContext._028=##                                        ##
353              kratool.ldif.namingContext._029=##  NEVER allow 'KRATOOL' the ability to  ##
354              kratool.ldif.namingContext._030=##  change the TPS 'naming context' data  ##
355              kratool.ldif.namingContext._031=##  in the following 'non-KeyRecord /     ##
356              kratool.ldif.namingContext._032=##  non-Request' fields (as these records ##
357              kratool.ldif.namingContext._033=##  should be removed via the option to   ##
358              kratool.ldif.namingContext._034=##  process requests and key records only ##
359              kratool.ldif.namingContext._035=##  if this is a KRA migration):          ##
360              kratool.ldif.namingContext._036=##                                        ##
361              kratool.ldif.namingContext._037=##    uid                                 ##
362              kratool.ldif.namingContext._038=##    uniqueMember                        ##
363              kratool.ldif.namingContext._039=##                                        ##
364              kratool.ldif.namingContext._040=##  If '-source_naming_context            ##
365              kratool.ldif.namingContext._041=##  original source KRA naming context'   ##
366              kratool.ldif.namingContext._042=##  and '-target_naming_context           ##
367              kratool.ldif.namingContext._043=##  renamed target KRA naming context'    ##
368              kratool.ldif.namingContext._044=##  options are specified, ALWAYS         ##
369              kratool.ldif.namingContext._045=##  require 'KRATOOL' to change the       ##
370              kratool.ldif.namingContext._046=##  KRA 'naming context' data in ALL of   ##
371              kratool.ldif.namingContext._047=##  the following fields in EACH of the   ##
372              kratool.ldif.namingContext._048=##  following types of records:           ##
373              kratool.ldif.namingContext._049=##                                        ##
374              kratool.ldif.namingContext._050=##    caEnrollmentRequest:                ##
375              kratool.ldif.namingContext._051=##                                        ##
376              kratool.ldif.namingContext._052=##      dn                                ##
377              kratool.ldif.namingContext._053=##      extdata-auth--005ftoken;user      ##
378              kratool.ldif.namingContext._054=##      extdata-auth--005ftoken;userdn    ##
379              kratool.ldif.namingContext._055=##                                        ##
380              kratool.ldif.namingContext._056=##    caKeyRecord:                        ##
381              kratool.ldif.namingContext._057=##                                        ##
382              kratool.ldif.namingContext._058=##      dn                                ##
383              kratool.ldif.namingContext._059=##                                        ##
384              kratool.ldif.namingContext._060=##    recoveryRequest:                    ##
385              kratool.ldif.namingContext._061=##                                        ##
386              kratool.ldif.namingContext._062=##      dn                                ##
387              kratool.ldif.namingContext._063=##                                        ##
388              kratool.ldif.namingContext._064=##    tpsKeyRecord:                       ##
389              kratool.ldif.namingContext._065=##                                        ##
390              kratool.ldif.namingContext._066=##      dn                                ##
391              kratool.ldif.namingContext._067=##                                        ##
392              kratool.ldif.namingContext._068=##    tpsNetkeyKeygenRequest:             ##
393              kratool.ldif.namingContext._069=##                                        ##
394              kratool.ldif.namingContext._070=##      dn                                ##
395              kratool.ldif.namingContext._071=##                                        ##
396              kratool.ldif.namingContext._072=############################################
397              kratool.ldif.recoveryRequest._000=#####################################
398              kratool.ldif.recoveryRequest._001=##  KRA CA / TPS Recovery Request  ##
399              kratool.ldif.recoveryRequest._002=#####################################
400              kratool.ldif.recoveryRequest.cn=true
401              kratool.ldif.recoveryRequest.dateOfModify=true
402              kratool.ldif.recoveryRequest.dn=true
403              kratool.ldif.recoveryRequest.extdata.requestId=true
404              kratool.ldif.recoveryRequest.extdata.requestNotes=true
405              kratool.ldif.recoveryRequest.extdata.serialnumber=true
406              kratool.ldif.recoveryRequest.requestId=true
407              kratool.ldif.tpsKeyRecord._000=#########################################
408              kratool.ldif.tpsKeyRecord._001=##         KRA TPS Key Record          ##
409              kratool.ldif.tpsKeyRecord._002=#########################################
410              kratool.ldif.tpsKeyRecord._003=##                                     ##
411              kratool.ldif.tpsKeyRecord._004=##  NEVER allow 'KRATOOL' the ability  ##
412              kratool.ldif.tpsKeyRecord._005=##  to change the TPS 'naming context' ##
413              kratool.ldif.tpsKeyRecord._006=##  data in the following fields:      ##
414              kratool.ldif.tpsKeyRecord._007=##                                     ##
415              kratool.ldif.tpsKeyRecord._008=##    archivedBy                       ##
416              kratool.ldif.tpsKeyRecord._009=##                                     ##
417              kratool.ldif.tpsKeyRecord._010=#########################################
418              kratool.ldif.tpsKeyRecord.cn=true
419              kratool.ldif.tpsKeyRecord.dateOfModify=true
420              kratool.ldif.tpsKeyRecord.dn=true
421              kratool.ldif.tpsKeyRecord.privateKeyData=true
422              kratool.ldif.tpsKeyRecord.serialno=true
423              kratool.ldif.tpsNetkeyKeygenRequest._000=#####################################
424              kratool.ldif.tpsNetkeyKeygenRequest._001=##  KRA TPS Netkey Keygen Request  ##
425              kratool.ldif.tpsNetkeyKeygenRequest._002=#####################################
426              kratool.ldif.tpsNetkeyKeygenRequest._003=##                                 ##
427              kratool.ldif.tpsNetkeyKeygenRequest._004=##  NEVER allow 'KRATOOL' the      ##
428              kratool.ldif.tpsNetkeyKeygenRequest._005=##  ability to change the          ##
429              kratool.ldif.tpsNetkeyKeygenRequest._006=##  TPS 'naming context' data in   ##
430              kratool.ldif.tpsNetkeyKeygenRequest._007=##  the following fields:          ##
431              kratool.ldif.tpsNetkeyKeygenRequest._008=##                                 ##
432              kratool.ldif.tpsNetkeyKeygenRequest._009=##    extdata-updatedby            ##
433              kratool.ldif.tpsNetkeyKeygenRequest._010=##                                 ##
434              kratool.ldif.tpsNetkeyKeygenRequest._011=#####################################
435              kratool.ldif.tpsNetkeyKeygenRequest.cn=true
436              kratool.ldif.tpsNetkeyKeygenRequest.dateOfModify=true
437              kratool.ldif.tpsNetkeyKeygenRequest.dn=true
438              kratool.ldif.tpsNetkeyKeygenRequest.extdata.keyRecord=true
439              kratool.ldif.tpsNetkeyKeygenRequest.extdata.requestId=true
440              kratool.ldif.tpsNetkeyKeygenRequest.extdata.requestNotes=true
441              kratool.ldif.tpsNetkeyKeygenRequest.requestId=true
442

EXAMPLES

444       The KRATool performs two operations: it can rewrap keys with a new pri‐
445       vate key, and it can renumber attributes in the LDIF file  entries  for
446       key  records, including enrollments and recovery requests. At least one
447       operation (rewrap or renumber) must be performed and both can  be  per‐
448       formed in a single invocation.
449
450
451   Rewrapping Keys
452
453
454       When  rewrapping keys, the tool needs to be able to access the original
455       NSS databases for the source KRA and its storage certificate to  unwrap
456       the  keys, as well as the storage certificate for the new KRA, which is
457       used to rewrap the keys.
458
459              KRATool -kratool_config_file "/usr/share/pki/java-tools/KRATool.cfg" -source_ldif_file "/tmp/files/originalKRA.ldif" -target_ldif_file "/tmp/files/newKRA.ldif" -log_file "/tmp/kratool.log" -source_pki_security_database_path "/tmp/files/" -source_storage_token_name "Internal Key Storage Token"  -source_storage_certificate_nickname "storageCert cert-pki-kra"  -target_storage_certificate_file "/tmp/files/omega.cert"
460
461   Renumbering Keys
462
463
464       When multiple KRA instances are being merged into a single instance, it
465       is important to make sure that no key or request records have conflict‐
466       ing CNs, DNs, serial numbers, or request ID numbers. These  values  can
467       be processed to append a new, larger number to the existing values.
468
469       For  the CN, the new number is the addition of the original CN plus the
470       appended number. For example, if the CN is 4 and the append  number  is
471       1000000, the new CN is 1000004.
472
473       For  serial  numbers and request IDs, the value is always a digit count
474       plus the value. So a CN of 4 has a serial number of 014, or  one  digit
475       and  the CN value. If the append number is 1000000, the new serial num‐
476       ber is 071000004, for seven digits and then the sum of the append  num‐
477       ber (1000000) and the original value (4).
478
479              KRATool -kratool_config_file "/usr/share/pki/java-tools/KRATool.cfg" -source_ldif_file "/tmp/files/originalKRA.ldif" -target_ldif_file "/tmp/files/newKRA.ldif" -log_file "/tmp/kratool.log" -append_id_offset 100000000000
480
481   Restoring the Original Numbering
482
483
484       If  a  number has been appended to key entries, as in the example enti‐
485       tled Renumbering Keys, that number can  also  be  removed.  Along  with
486       updating  the  CN,  it  also  reconstructs any associated numbers, like
487       serial numbers and request ID numbers. Undoing a renumbering action may
488       be necessary if the original number wasn't large enough to prevent con‐
489       flicts or as part of testing a migration or KRA consolidation process.
490
491              KRATool -kratool_config_file "/usr/share/pki/java-tools/KRATool.cfg" -source_ldif_file "/tmp/files/originalKRA.ldif" -target_ldif_file "/tmp/files/newKRA.ldif" -log_file "/tmp/kratool.log" -remove_id_offset 100000000000
492
493   Renumbering and Rewrapping in a Single Command
494
495
496       Rewrapping and renumbering operations can  be  performed  in  the  same
497       invocation.
498
499              KRATool -kratool_config_file "/usr/share/pki/java-tools/KRATool.cfg" -source_ldif_file "/tmp/files/originalKRA.ldif" -target_ldif_file "/tmp/files/newKRA.ldif" -log_file "/tmp/kratool.log" -source_pki_security_database_path "/tmp/files/" -source_storage_token_name "Internal Key Storage Token" -source_storage_certificate_nickname "storageCert cert-pki-kra" -target_storage_certificate_file "/tmp/files/omega.cert" -append_id_offset 100000000000
500

AUTHORS

502       Matthew Harmsen <mharmsen@redhat.com>.
503
504
506       Copyright (c) 2016 Red Hat, Inc. This is licensed under the GNU General
507       Public License, version 2 (GPLv2). A copy of this license is  available
508       at http://www.gnu.org/licenses/old-licenses/gpl-2.0.txt.
509
510

SEE ALSO

512       pki(1)
513
514
515
516version 10.3                     July 18, 2016                      KRATool(1)
Impressum