Chapter 27. KRATool (Rewrapping Private Keys)
Some private keys (mainly in older deployments) were wrapped in SHA-1, 1024-bit storage keys when they were archived in the Key Recovery Authority (KRA). These algorithms have become less secure as processor speeds improve and algorithms have been broken. As a security measure, it is possible to rewrap the private keys in a new, stronger storage key (SHA-256, 2048-bit keys).
Note
Because the
KRATool utility can export private keys from one KRA, rewrap them with a new storage key, and then import them into a new KRA, this tool can be used as part of a process of combining multiple KRA instances into a single KRA.
27.1. Syntax
The
KRATool utility can be run to rewrap keys, to renumber keys, or both.
The syntax for rewrapping keys:
KRATool -kratool_config_file /path/to/tool_config_file
-source_ldif_file /path/to/original_ldif_file
-target_ldif_file /path/to/newinstance_ldif_file
-log_file /path/to/tool_log_file
[-source_pki_security_database_path /path/to/nss_databases
-source_storage_token_name /path/to/token
-source_storage_certificate_nickname storage_certificate_nickname
-target_storage_certificate_file /path/to/new_ASCII_storage_cert
[-source_pki_security_database_pwdfile /path/to/password_file]]
[-source_kra_naming_context name -target_kra_naming_context name]
[-process_requests_and_key_records_only]
The syntax to renumber keys:
KRATool -kratool_config_file /path/to/tool_config_file
-source_ldif_file /path/to/original_ldif_file
-target_ldif_file /path/to/newinstance_ldif_file
-log_file /path/to/tool_log_file
[-append_id_offset prefix_to_add | -remove_id_offset prefix_to_remove]
[-source_kra_naming_context name -target_kra_naming_context name]
[-process_requests_and_key_records_only]| Option | Description |
|---|---|
| Mandatory parameters | |
| -kratool_config_file | Gives the complete path and filename of the configuration file used by the tool. This configuration process tells the tool how to process certain parameters in the existing key records, whether to apply any formatting changes (like changing the naming context or adding an offset) or even whether to update the modify date. The configuration file is required and a default file is included with the tool. The file format is described in Section 27.2, “.cfg File”. |
| -source_ldif_file | Gives the complete path and filename of the LDIF file which contains all of the key data from the old KRA. |
| -target_ldif_file | Gives the complete path and filename of the LDIF file to which the tool will write all of the key data from the new KRA. This file is created by the tool as it runs. |
| -log_file | Gives the path and filename of the log file to use to log the tool progress and messages. This file is created by the tool as it runs. |
| Optional parameters | |
| -source_kra_naming_context | Gives the naming context of the original KRA instance, the DN element that refers to the original KRA. Key-related LDIF entries have a DN with the KRA instance name in it, such as cn=1,ou=kra,ou=requests,dc=alpha.example.com-pki-kra. The naming context for that entry is the DN value, alpha.example.com-pki-kra. These entries can be renamed, automatically, from the old KRA instance naming context to the new KRA instance naming context.
While this argument is optional, it is recommended because it means that the LDIF file does not have to be edited before it is imported into the target KRA.
If this argument is used, then the
-target_kra_naming_context argument must also be used.
|
| -target_kra_naming_context | Gives the naming context of the new KRA instance, the name that the original key entries should be changed to. Key-related LDIF entries have a DN with the KRA instance name in it, such as cn=1,ou=kra,ou=requests,dc=omega.example.com-pki-kra. The naming context for that entry is the DN value, omega.example.com-pki-kra.These entries can be renamed, automatically, from the old KRA instance to the new KRA instance naming context.
While this argument is optional, it is recommended because it means that the LDIF file does not have to be edited before it is imported into the target KRA.
If this argument is used, then the
-source_kra_naming_context argument must also be used.
|
| -process_requests_and_key_records_only | Removes configuration entries from the source LDIF file, leaving only the key and request entries.
While this argument is optional, it is recommended because it means that the LDIF file does not have to be edited before it is imported into the target KRA.
|
| Rewrap parameters | |
| -source_pki_security_database_path | Gives the full path to the directory which contains the NSS security databases used by the old KRA instance.
This option is required if any other rewrap parameters are used.
|
| -source_storage_token_name | Gives the name of the token which stores the KRA data, like Internal Key Storage Token for internal tokens or a name like NHSM6000-OCS for the hardware token name.
This option is required if any other rewrap parameters are used.
|
| -source_storage_certificate_nickname | Gives the nickname of the KRA storage certificate for the old KRA instance. Either this certificate will be located in the security database for the old KRA instance or the security database will contain a pointer to the certificate in the hardware token.
This option is required if any other rewrap parameters are used.
|
| -target_storage_certificate_file | Gives the path and filename of an ASCII-formatted file of the storage certificate for the new KRA instance. The storage certificate should be exported from the new KRA's databases and stored in an accessible location before running KRATool.
This option is required if any other rewrap parameters are used.
|
| -source_pki_security_database_pwdfile | Gives the path and filename to a password file that contains only the password for the storage token given in the -source_storage_token_name option.
This argument is optional when other rewrap parameters are used. If this argument is not used, then the script prompts for the password.
|
| Number offset parameters | |
| -append_id_offset | Gives an ID number which will be preprended to every imported key, to prevent possible collisions. A unique ID offset should be used for every KRA instance which has keys exported using KRATool.
If
-append_id_offset is used, then do not use the -remove_id_offset option.
|
| -remove_id_offset | Gives an ID number to remove from the beginning of every imported key.
If
-remove_id_offset is used, then do not use the -append_id_offset option.
|
