Difference between revisions of "KRATool"

From Dogtag
Jump to: navigation, search
(Created page with "= Overview = KRATool allows the LDAP contents of the KRA to be migrated during a major system migration. The KRATool offers the following functionalities: 1. Rewrap the exis...")
 
(Importing into omega)
(10 intermediate revisions by the same user not shown)
Line 3: Line 3:
 
KRATool allows the LDAP contents of the KRA to be migrated during a major system migration. The KRATool offers the following functionalities:
 
KRATool allows the LDAP contents of the KRA to be migrated during a major system migration. The KRATool offers the following functionalities:
  
1. Rewrap the existing Symmetric Key
+
# Rewrap the existing Symmetric Key
2. Append offset IDs to LDAP entries
+
# Append offset IDs to LDAP entries
3. Remove offset IDs from LDAP entries
+
# Remove offset IDs from LDAP entries
  
 
See also [[Key_Recovery_Authority]]
 
See also [[Key_Recovery_Authority]]
 +
 +
= Low-level Design =
 +
 +
The KRA records, that are processed by KRATool, are classified into 2 types:
 +
 +
# Requests
 +
# Key Records
 +
 +
There are seven different types of KRA LDIF records that are processed, in total.
 +
 +
=== Requests ===
 +
* CA enrollment request:
 +
<ul>
 +
<table border=1>
 +
<tr>
 +
<th bgcolor="lightgrey">Attribute</th>
 +
<th bgcolor="lightgrey">Source Value</th>
 +
<th bgcolor="lightgrey">Target Value</th>
 +
</tr>
 +
<tr>
 +
<td align="middle">cn</td>
 +
<td align="middle">source cn</td>
 +
<td align="middle">(source cn + target_uid_offset) OR (source cn - target_uid_offset)</td>
 +
</tr>
 +
<tr>
 +
<td align="middle">dateOfModify</td>
 +
<td align="middle">original date</td>
 +
<td align="middle">date modified</td>
 +
</tr>
 +
<tr>
 +
<td align="middle">extdata-keyrecord</td>
 +
<td align="middle">source extdata-keyrecord</td>
 +
<td align="middle">(source extdata-keyrecord + target_uid_offset) OR (source extdata-keyrecord - target_uid_offset)</td>
 +
</tr>
 +
<tr>
 +
<td align="middle">extdata-requestid</td>
 +
<td align="middle">source extdata-requestid</td>
 +
<td align="middle">(source extdata-requestid + target_uid_offset) OR (source extdata-requestid - target_uid_offset)</td>
 +
</tr>
 +
<tr>
 +
<td align="middle">extdata-requestnotes</td>
 +
<td align="middle">comments (generally empty)</td>
 +
<td align="middle">comments + [REWRAPPED] + [APPENDED OFFSET OF ''xxx...xxx''] OR [REMOVED OFFSET OF ''xxx...xxx'']</td>
 +
</tr>
 +
<tr>
 +
<td align="middle">requestId</td>
 +
<td align="middle">[source length in digits][source requestId]</td>
 +
<td align="middle">[target length in digits][(source requestId + target_uid_offset) OR (source requestId - target_uid_offset)]</td>
 +
</tr>
 +
</table>
 +
<br>
 +
</ul>
 +
 +
* CA recovery request:
 +
<ul>
 +
<table border=1>
 +
<tr>
 +
<th bgcolor="lightgrey">Attribute</th>
 +
<th bgcolor="lightgrey">Source Value</th>
 +
<th bgcolor="lightgrey">Target Value</th>
 +
</tr>
 +
<tr>
 +
<td align="middle">cn</td>
 +
<td align="middle">source cn</td>
 +
<td align="middle">(source cn + target_uid_offset) OR (source cn - target_uid_offset)</td>
 +
</tr>
 +
<tr>
 +
<td align="middle">dateOfModify</td>
 +
<td align="middle">original date</td>
 +
<td align="middle">date modified</td>
 +
</tr>
 +
<tr>
 +
<td align="middle">extdata-requestid</td>
 +
<td align="middle">source extdata-requestid</td>
 +
<td align="middle">(source extdata-requestid + target_uid_offset) OR (source extdata-requestid - target_uid_offset)</td>
 +
</tr>
 +
<tr>
 +
<td align="middle">extdata-requestnotes</td>
 +
<td align="middle">ATTRIBUTE DOES NOT EXIST</td>
 +
<td align="middle">[REWRAPPED] + [APPENDED OFFSET OF xxx...xxx] OR [REMOVED OFFSET OF xxx...xxx]</td>
 +
</tr>
 +
<tr>
 +
<td align="middle">extdata-serialno</td>
 +
<td align="middle">source extdata-serialnumber</td>
 +
<td align="middle">(source extdata-serialnumber + target_uid_offset) OR (source extdata-serialnumber - target_uid_offset)</td>
 +
</tr>
 +
<tr>
 +
<td align="middle">requestId</td>
 +
<td align="middle">[source length in digits][source requestId]</td>
 +
<td align="middle">[target length in digits][(source requestId + target_uid_offset) OR (source requestId - target_uid_offset)]</td>
 +
</tr>
 +
</table>
 +
<br>
 +
</ul>
 +
 +
* TPS netkeyKeygen request:
 +
<ul>
 +
<table border=1>
 +
<tr>
 +
<th bgcolor="lightgrey">Attribute</th>
 +
<th bgcolor="lightgrey">Source Value</th>
 +
<th bgcolor="lightgrey">Target Value</th>
 +
</tr>
 +
<tr>
 +
<td align="middle">cn</td>
 +
<td align="middle">source cn</td>
 +
<td align="middle">(source cn + target_uid_offset) OR (source cn - target_uid_offset)</td>
 +
</tr>
 +
<tr>
 +
<td align="middle">dateOfModify</td>
 +
<td align="middle">original date</td>
 +
<td align="middle">date modified</td>
 +
</tr>
 +
<tr>
 +
<td align="middle">extdata-keyrecord</td>
 +
<td align="middle">source keyrecord</td>
 +
<td align="middle">(source keyrecord + target_uid_offset) OR (source keyrecord - target_uid_offset)</td>
 +
</tr>
 +
<tr>
 +
<td align="middle">extdata-requestid</td>
 +
<td align="middle">source requestid</td>
 +
<td align="middle">(source requestid + target_uid_offset) OR (source requestid + target_uid_offset)</td>
 +
</tr>
 +
<tr>
 +
<td align="middle">extdata-requestnotes</td>
 +
<td align="middle">ATTRIBUTE DOES NOT EXIST</td>
 +
<td align="middle">[REWRAPPED] + [APPENDED OFFSET OF xxx...xxx] OR [REMOVED OFFSET OF xxx...xxx]</td>
 +
</tr>
 +
<tr>
 +
<td align="middle">requestId</td>
 +
<td align="middle">[source length in digits][source requestId]</td>
 +
<td align="middle">[target length in digits][(source requestId + target_uid_offset) OR (source requestId - target_uid_offset)]</td>
 +
</tr>
 +
</table>
 +
<br>
 +
</ul>
 +
 +
* TPS recovery request:
 +
<ul>
 +
<table border=1>
 +
<tr>
 +
<th bgcolor="lightgrey">Attribute</th>
 +
<th bgcolor="lightgrey">Source Value</th>
 +
<th bgcolor="lightgrey">Target Value</th>
 +
</tr>
 +
<tr>
 +
<td align="middle">cn</td>
 +
<td align="middle">source cn</td>
 +
<td align="middle">(source cn + target_uid_offset) OR (source cn + target_uid_offset)</td>
 +
</tr>
 +
<tr>
 +
<td align="middle">dateOfModify</td>
 +
<td align="middle">original date</td>
 +
<td align="middle">date modified</td>
 +
</tr>
 +
<tr>
 +
<td align="middle">extdata-requestid</td>
 +
<td align="middle">source extdata-requestid</td>
 +
<td align="middle">(source extdata-requestid + target_uid_offset) OR (source extdata-requestid - target_uid_offset)</td>
 +
</tr>
 +
<tr>
 +
<td align="middle">extdata-requestnotes</td>
 +
<td align="middle">ATTRIBUTE DOES NOT EXIST</td>
 +
<td align="middle">[REWRAPPED] + [APPENDED OFFSET OF xxx...xxx] OR [REMOVED OFFSET OF xxx...xxx]</td>
 +
</tr>
 +
<tr>
 +
<td align="middle">extdata-serialno</td>
 +
<td align="middle">source extdata-serialnumber</td>
 +
<td align="middle">(source extdata-serialnumber + target_uid_offset) OR (source extdata-serialnumber - target_uid_offset)</td>
 +
</tr>
 +
<tr>
 +
<td align="middle">requestId</td>
 +
<td align="middle">[source length in digits][source requestId]</td>
 +
<td align="middle">[target length in digits][(source requestId + target_uid_offset) OR (source requestId + target_uid_offset)]</td>
 +
</tr>
 +
</table>
 +
<br>
 +
</ul>
 +
 +
* TPS netkeyKeyRecovery request:
 +
<ul>
 +
<table border=1>
 +
<tr>
 +
<th bgcolor="lightgrey">Attribute</th>
 +
<th bgcolor="lightgrey">Source Value</th>
 +
<th bgcolor="lightgrey">Target Value</th>
 +
</tr>
 +
<tr>
 +
<td align="middle">cn</td>
 +
<td align="middle">source cn</td>
 +
<td align="middle">(source cn + target_uid_offset) OR (source cn + target_uid_offset)</td>
 +
</tr>
 +
<tr>
 +
<td align="middle">dateOfModify</td>
 +
<td align="middle">original date</td>
 +
<td align="middle">date modified</td>
 +
</tr>
 +
<tr>
 +
<td align="middle">extdata-requestid</td>
 +
<td align="middle">source extdata-requestid</td>
 +
<td align="middle">(source extdata-requestid + target_uid_offset) OR (source extdata-requestid - target_uid_offset)</td>
 +
</tr>
 +
<tr>
 +
<td align="middle">extdata-requestnotes</td>
 +
<td align="middle">ATTRIBUTE DOES NOT EXIST</td>
 +
<td align="middle">[REWRAPPED] + [APPENDED OFFSET OF xxx...xxx] OR [REMOVED OFFSET OF xxx...xxx]</td>
 +
</tr>
 +
<tr>
 +
<td align="middle">requestId</td>
 +
<td align="middle">[source length in digits][source requestId]</td>
 +
<td align="middle">[target length in digits][(source requestId + target_uid_offset) OR (source requestId + target_uid_offset)]</td>
 +
</tr>
 +
</table>
 +
<br>
 +
</ul>
 +
 +
 +
=== Key Record ===
 +
 +
* CA keyrecord:
 +
<ul>
 +
<table border=1>
 +
<tr>
 +
<th bgcolor="lightgrey">Attribute</th>
 +
<th bgcolor="lightgrey">Source Value</th>
 +
<th bgcolor="lightgrey">Target Value</th>
 +
</tr>
 +
<tr>
 +
<td align="middle">cn</td>
 +
<td align="middle">source cn</td>
 +
<td align="middle">(source cn + target_uid_offset) OR (source cn + target_uid_offset)</td>
 +
</tr>
 +
<tr>
 +
<td align="middle">dateOfModify</td>
 +
<td align="middle">original date</td>
 +
<td align="middle">date modified</td>
 +
</tr>
 +
<tr>
 +
<td align="middle">privateKeyData</td>
 +
<td align="middle">private user key wrapped with source storage key</td>
 +
<td align="middle">private user key wrapped with target storage key</td>
 +
</tr>
 +
<tr>
 +
<td align="middle">serialno</td>
 +
<td align="middle">[source length in digits][source serialno]</td>
 +
<td align="middle">[target length in digits][(source serialno + target_uid_offset) OR (source serialno - target_uid_offset)]</td>
 +
</tr>
 +
</table>
 +
<br>
 +
</ul>
 +
 +
* TPS keyrecord:
 +
<ul>
 +
<table border=1>
 +
<tr>
 +
<th bgcolor="lightgrey">Attribute</th>
 +
<th bgcolor="lightgrey">Source Value</th>
 +
<th bgcolor="lightgrey">Target Value</th>
 +
</tr>
 +
<tr>
 +
<td align="middle">cn</td>
 +
<td align="middle">source cn</td>
 +
<td align="middle">(source cn + target_uid_offset) OR (source cn - target_uid_offset)</td>
 +
</tr>
 +
<tr>
 +
<td align="middle">dateOfModify</td>
 +
<td align="middle">original date</td>
 +
<td align="middle">date modified</td>
 +
</tr>
 +
<tr>
 +
<td align="middle">privateKeyData</td>
 +
<td align="middle">private user key wrapped with source storage key</td>
 +
<td align="middle">private user key wrapped with target storage key</td>
 +
</tr>
 +
<tr>
 +
<td align="middle">serialno</td>
 +
<td align="middle">[source length in digits][source serialno]</td>
 +
<td align="middle">[target length in digits][(source serialno + target_uid_offset) OR (source serialno - target_uid_offset)]</td>
 +
</tr>
 +
</table>
 +
<br>
 +
</ul>
 +
 +
= Scenario with 1 to 1 migration =
 +
'''NOTE: ''' This scenario includes migrating KRA records from 1 machine to another machine.
 +
 +
There are 2 different scenarios where KRATool can serve its purpose:
 +
 +
# Rewrap symmetric key
 +
# Append or remove offset ID
 +
 +
The following examples are based on migrating from '''one legacy system''' to the '''latest system'''.
 +
 +
 +
<ul>
 +
{| border=1
 +
! style="background-color:darkgrey" | Hostname || style="background-color:darkgrey" | Operating System || style="background-color:darkgrey" | PKI KRA Version || style="background-color:darkgrey" | RSA Storage Key Size
 +
|- valign="top"
 +
| '''alpha.example.com''' || align="center" | Fedora 27 (64-bit) || align="center" | PKI 10.5 || align="center" | 2048-bit
 +
|- valign="top"
 +
| '''omega.example.com''' || align="center" | Fedora 30 (64-bit) || align="center" | PKI 10.8 || align="center" | 2048-bit
 +
|}
 +
</ul>
 +
 +
Within this deployment, the KRA located on alpha.example.com contains data, while the KRA located on omega.example.com does not yet exist.
 +
 +
The administrator is tasked with installing and configuring an PKI 10.8 KRA on omega.example.com including:
 +
 +
* Extracting the data from the old KRA located on alpha.example.com
 +
* Rewrapping the private key data stored with the 2048-bit storage key located on omega.example.com
 +
* Renumbering this data
 +
* Renaming this data so that it can be consolidated and imported into omega.example.com.
 +
 +
 +
== Solution ==
 +
 +
=== Preparing omega ===
 +
1. Login as 'root' on '''omega.example.com'''
 +
 +
2. Install and configure a new PKI 8 KRA on '''omega.example.com'''
 +
'''NOTE: '''Select an RSA storage key size of 2048-bits!  Also, if TPS data is to be "imported", be certain to install and configure a TKS and TPS (make certain that the TPS uses this KRA)
 +
 +
3. Shutdown this PKI 10.8 KRA server (and leave it shutdown until instructed otherwise):
 +
    systemctl stop pki-tomcatd@<instance>
 +
 +
4. Prepare a place for data:
 +
    mkdir -p /export/pki
 +
 +
5. Go to the directory containing the NSS security databases for this PKI 10.8 KRA:
 +
    cd /var/lib/<instance>/alias
 +
 +
6. Extract the public storage certificate to a flat-file located in the new data area:
 +
    certutil -L -d . -n "storageCert cert-pki-kra" -a > /export/pki/omega.cert
 +
 +
7. Presuming that the Directory Server instance associated with this KRA is located on the same machine, shutdown Directory Server (and leave it shutdown until instructed otherwise):
 +
    systemctl stop dirsrv@<ds_instance>
 +
 +
8. Extract the pristine PKI 10.8 KRA database configuration:
 +
    /usr/lib64/dirsrv/slapd-omega/db2ldif -n omega.example.com-pki-kra -a /tmp/omega.ldif
 +
    mv /tmp/omega.ldif /export/pki/omega.ldif
 +
'''Note 1: ''' The ''db2ldif'' runs as "nobody" and so, it fails to create the ''omega.ldif'' other than ''/tmp'' location
 +
'''Note 2: ''' Be certain that the file 'omega.ldif' contains a single blank line at the end of the file!</td>
 +
 +
=== Exporting contents from alpha ===
 +
9. Login as 'root' on '''alpha.example.com'''
 +
 +
10. Prepare a place for data:
 +
    mkdir -p /export/pki
 +
 +
11. Stop the Directory Server
 +
    systemctl stop dirsrv@<ds_instance>
 +
 +
12. Generate the LDIF from the KRA LDAP Database
 +
    /usr/lib64/dirsrv/slapd-alpha/db2ldif -n alpha.example.com-pki-kra -a /tmp/alpha.ldif
 +
   
 +
 +
13. Copy the 'alpha.ldif' to the data area
 +
    mv /tmp/alpha.ldif /export/pki/alpha.ldif
 +
 +
14. Make certain that all PKI 10.5 servers are shut down
 +
 +
15. Copy the KRA NSS security databases to the data area:
 +
    cp -p /var/lib/pki-kra/alias/cert8.db /export/pki
 +
    cp -p /var/lib/pki-kra/alias/key3.db /export/pki
 +
    cp -p /var/lib/pki-kra/alias/secmod.db /export/pki
 +
 +
16. Go to the data area
 +
    cd /export/pki
 +
17. Obtain the flat-file containing the public storage certificate from '''omega.example.com'''
 +
    sftp root@omega.example.com
 +
    sftp&gt; cd /export/pki
 +
    sftp&gt; get omega.cert
 +
    sftp&gt; quit
 +
 +
18. Run KRATool on '''alpha.example.com''':
 +
   
 +
    KRATool   
 +
    -kratool_config_file /usr/share/pki/java-tools/KRATool.cfg      \
 +
    -source_ldif_file "`pwd`/alpha.ldif"                            \
 +
    -target_ldif_file "`pwd`/alpha2omega.ldif"                      \       
 +
    -log_file /tmp/KRATool.log                                      \
 +
    -source_pki_security_database_path "`pwd`"                      \
 +
    -source_storage_token_name "Internal Key Storage Token"          \
 +
    -source_storage_certificate_nickname "storageCert cert-pki-kra"  \
 +
    -target_storage_certificate_file "`pwd`/omega.cert"              \
 +
    -append_id_offset 100000000000                                  \
 +
    -source_kra_naming_context "alpha.example.com-pki-kra"          \
 +
    -target_kra_naming_context "omega.example.com-pki-kra"          \
 +
    -unwrap_algorithm AES                                            \
 +
    -process_requests_and_key_records_only
 +
 +
''NOTE:''' Obtain the password from /var/lib/<instance>/conf/password.conf.  If the private storage key is stored on an HSM attached to '''alpha.example.com''', change the input parameters appropriately, and select the appropriate password when prompted!
 +
 +
Alternatively, create a file that ONLY contains the password to automatically supply the password to include in a certificate or to access a certificate database. This is a plain-text file containing one password. Be sure to prevent unauthorized access to this file. Supply this file to KRATool by adding the '''-source_pki_security_database_pwdfile &lt;path to PKI password file&gt;''' command-line option.</td>
 +
 +
20. Copy 'alpha2omega.ldif' to '''omega.example.com''':
 +
 +
    sftp root@omega.example.com
 +
    sftp&gt; cd /export/pki
 +
    sftp&gt; put alpha2omega.ldif
 +
    sftp&gt; quit
 +
 +
=== Importing into omega ===
 +
 +
21. Login as 'root' on '''omega.example.com'''
 +
 +
22. Go to the data area
 +
    cd /export/pki
 +
 +
23. Concatenate the ldif files:
 +
    cat omega.ldif alpha2omega.ldif > omega_alpha.ldif
 +
 +
24. Import the file 'omega_alpha.ldif' into the RHDS 8.2 database associated with the PKI 10.5 KRA:
 +
    /usr/lib64/dirsrv/slapd-omega/ldif2db -n omega.example.com-pki-kra -i /export/pki/omega_alpha.ldif
 +
 +
25. Restart directory server:
 +
    systemctl start dirsrv@<ds_instance>
 +
 +
26. Restart the PKI 10.5 KRA:
 +
    systemctl start pki-tomcatd@<instance>
 +
 +
= Scenario with n to 1 migration =
 +
 +
In this scenario, the admin is tasked with merging contents from multiple old KRAs into the latest KRA machine.
 +
 +
Please follow the same steps as [[KRATool#Scenario with 1 to 1 migration | Scenario with 1 to 1 migration]] and execute steps in [[KRATool#Exporting_contents_from_alpha|exporting contents from machine]] in all the required machines

Revision as of 21:41, 10 September 2019

Overview

KRATool allows the LDAP contents of the KRA to be migrated during a major system migration. The KRATool offers the following functionalities:

  1. Rewrap the existing Symmetric Key
  2. Append offset IDs to LDAP entries
  3. Remove offset IDs from LDAP entries

See also Key_Recovery_Authority

Low-level Design

The KRA records, that are processed by KRATool, are classified into 2 types:

  1. Requests
  2. Key Records

There are seven different types of KRA LDIF records that are processed, in total.

Requests

  • CA enrollment request:
    Attribute Source Value Target Value
    cn source cn (source cn + target_uid_offset) OR (source cn - target_uid_offset)
    dateOfModify original date date modified
    extdata-keyrecord source extdata-keyrecord (source extdata-keyrecord + target_uid_offset) OR (source extdata-keyrecord - target_uid_offset)
    extdata-requestid source extdata-requestid (source extdata-requestid + target_uid_offset) OR (source extdata-requestid - target_uid_offset)
    extdata-requestnotes comments (generally empty) comments + [REWRAPPED] + [APPENDED OFFSET OF xxx...xxx] OR [REMOVED OFFSET OF xxx...xxx]
    requestId [source length in digits][source requestId] [target length in digits][(source requestId + target_uid_offset) OR (source requestId - target_uid_offset)]


  • CA recovery request:
    Attribute Source Value Target Value
    cn source cn (source cn + target_uid_offset) OR (source cn - target_uid_offset)
    dateOfModify original date date modified
    extdata-requestid source extdata-requestid (source extdata-requestid + target_uid_offset) OR (source extdata-requestid - target_uid_offset)
    extdata-requestnotes ATTRIBUTE DOES NOT EXIST [REWRAPPED] + [APPENDED OFFSET OF xxx...xxx] OR [REMOVED OFFSET OF xxx...xxx]
    extdata-serialno source extdata-serialnumber (source extdata-serialnumber + target_uid_offset) OR (source extdata-serialnumber - target_uid_offset)
    requestId [source length in digits][source requestId] [target length in digits][(source requestId + target_uid_offset) OR (source requestId - target_uid_offset)]


  • TPS netkeyKeygen request:
    Attribute Source Value Target Value
    cn source cn (source cn + target_uid_offset) OR (source cn - target_uid_offset)
    dateOfModify original date date modified
    extdata-keyrecord source keyrecord (source keyrecord + target_uid_offset) OR (source keyrecord - target_uid_offset)
    extdata-requestid source requestid (source requestid + target_uid_offset) OR (source requestid + target_uid_offset)
    extdata-requestnotes ATTRIBUTE DOES NOT EXIST [REWRAPPED] + [APPENDED OFFSET OF xxx...xxx] OR [REMOVED OFFSET OF xxx...xxx]
    requestId [source length in digits][source requestId] [target length in digits][(source requestId + target_uid_offset) OR (source requestId - target_uid_offset)]


  • TPS recovery request:
    Attribute Source Value Target Value
    cn source cn (source cn + target_uid_offset) OR (source cn + target_uid_offset)
    dateOfModify original date date modified
    extdata-requestid source extdata-requestid (source extdata-requestid + target_uid_offset) OR (source extdata-requestid - target_uid_offset)
    extdata-requestnotes ATTRIBUTE DOES NOT EXIST [REWRAPPED] + [APPENDED OFFSET OF xxx...xxx] OR [REMOVED OFFSET OF xxx...xxx]
    extdata-serialno source extdata-serialnumber (source extdata-serialnumber + target_uid_offset) OR (source extdata-serialnumber - target_uid_offset)
    requestId [source length in digits][source requestId] [target length in digits][(source requestId + target_uid_offset) OR (source requestId + target_uid_offset)]


  • TPS netkeyKeyRecovery request:
    Attribute Source Value Target Value
    cn source cn (source cn + target_uid_offset) OR (source cn + target_uid_offset)
    dateOfModify original date date modified
    extdata-requestid source extdata-requestid (source extdata-requestid + target_uid_offset) OR (source extdata-requestid - target_uid_offset)
    extdata-requestnotes ATTRIBUTE DOES NOT EXIST [REWRAPPED] + [APPENDED OFFSET OF xxx...xxx] OR [REMOVED OFFSET OF xxx...xxx]
    requestId [source length in digits][source requestId] [target length in digits][(source requestId + target_uid_offset) OR (source requestId + target_uid_offset)]



Key Record

  • CA keyrecord:
    Attribute Source Value Target Value
    cn source cn (source cn + target_uid_offset) OR (source cn + target_uid_offset)
    dateOfModify original date date modified
    privateKeyData private user key wrapped with source storage key private user key wrapped with target storage key
    serialno [source length in digits][source serialno] [target length in digits][(source serialno + target_uid_offset) OR (source serialno - target_uid_offset)]


  • TPS keyrecord:
    Attribute Source Value Target Value
    cn source cn (source cn + target_uid_offset) OR (source cn - target_uid_offset)
    dateOfModify original date date modified
    privateKeyData private user key wrapped with source storage key private user key wrapped with target storage key
    serialno [source length in digits][source serialno] [target length in digits][(source serialno + target_uid_offset) OR (source serialno - target_uid_offset)]


Scenario with 1 to 1 migration

NOTE: This scenario includes migrating KRA records from 1 machine to another machine.

There are 2 different scenarios where KRATool can serve its purpose:

  1. Rewrap symmetric key
  2. Append or remove offset ID

The following examples are based on migrating from one legacy system to the latest system.


    Hostname Operating System PKI KRA Version RSA Storage Key Size
    alpha.example.com Fedora 27 (64-bit) PKI 10.5 2048-bit
    omega.example.com Fedora 30 (64-bit) PKI 10.8 2048-bit

Within this deployment, the KRA located on alpha.example.com contains data, while the KRA located on omega.example.com does not yet exist.

The administrator is tasked with installing and configuring an PKI 10.8 KRA on omega.example.com including:

  • Extracting the data from the old KRA located on alpha.example.com
  • Rewrapping the private key data stored with the 2048-bit storage key located on omega.example.com
  • Renumbering this data
  • Renaming this data so that it can be consolidated and imported into omega.example.com.


Solution

Preparing omega

1. Login as 'root' on omega.example.com

2. Install and configure a new PKI 8 KRA on omega.example.com NOTE: Select an RSA storage key size of 2048-bits! Also, if TPS data is to be "imported", be certain to install and configure a TKS and TPS (make certain that the TPS uses this KRA)

3. Shutdown this PKI 10.8 KRA server (and leave it shutdown until instructed otherwise):

    systemctl stop pki-tomcatd@<instance>

4. Prepare a place for data:

    mkdir -p /export/pki

5. Go to the directory containing the NSS security databases for this PKI 10.8 KRA:

    cd /var/lib/<instance>/alias

6. Extract the public storage certificate to a flat-file located in the new data area:

    certutil -L -d . -n "storageCert cert-pki-kra" -a > /export/pki/omega.cert

7. Presuming that the Directory Server instance associated with this KRA is located on the same machine, shutdown Directory Server (and leave it shutdown until instructed otherwise):

    systemctl stop dirsrv@<ds_instance>

8. Extract the pristine PKI 10.8 KRA database configuration:

    /usr/lib64/dirsrv/slapd-omega/db2ldif -n omega.example.com-pki-kra -a /tmp/omega.ldif
    mv /tmp/omega.ldif /export/pki/omega.ldif

Note 1: The db2ldif runs as "nobody" and so, it fails to create the omega.ldif other than /tmp location Note 2: Be certain that the file 'omega.ldif' contains a single blank line at the end of the file!</td>

Exporting contents from alpha

9. Login as 'root' on alpha.example.com

10. Prepare a place for data:

    mkdir -p /export/pki

11. Stop the Directory Server

    systemctl stop dirsrv@<ds_instance>

12. Generate the LDIF from the KRA LDAP Database

    /usr/lib64/dirsrv/slapd-alpha/db2ldif -n alpha.example.com-pki-kra -a /tmp/alpha.ldif
    

13. Copy the 'alpha.ldif' to the data area

    mv /tmp/alpha.ldif /export/pki/alpha.ldif

14. Make certain that all PKI 10.5 servers are shut down

15. Copy the KRA NSS security databases to the data area:

    cp -p /var/lib/pki-kra/alias/cert8.db /export/pki
    cp -p /var/lib/pki-kra/alias/key3.db /export/pki
    cp -p /var/lib/pki-kra/alias/secmod.db /export/pki

16. Go to the data area

    cd /export/pki

17. Obtain the flat-file containing the public storage certificate from omega.example.com

    sftp root@omega.example.com
    sftp> cd /export/pki
    sftp> get omega.cert
    sftp> quit

18. Run KRATool on alpha.example.com:

    KRATool    
    -kratool_config_file /usr/share/pki/java-tools/KRATool.cfg       \
    -source_ldif_file "`pwd`/alpha.ldif"                             \
    -target_ldif_file "`pwd`/alpha2omega.ldif"                       \         
    -log_file /tmp/KRATool.log                                       \
    -source_pki_security_database_path "`pwd`"                       \
    -source_storage_token_name "Internal Key Storage Token"          \
    -source_storage_certificate_nickname "storageCert cert-pki-kra"  \
    -target_storage_certificate_file "`pwd`/omega.cert"              \
    -append_id_offset 100000000000                                   \
    -source_kra_naming_context "alpha.example.com-pki-kra"           \
    -target_kra_naming_context "omega.example.com-pki-kra"           \
    -unwrap_algorithm AES                                            \
    -process_requests_and_key_records_only

NOTE:' Obtain the password from /var/lib/<instance>/conf/password.conf. If the private storage key is stored on an HSM attached to alpha.example.com, change the input parameters appropriately, and select the appropriate password when prompted!

Alternatively, create a file that ONLY contains the password to automatically supply the password to include in a certificate or to access a certificate database. This is a plain-text file containing one password. Be sure to prevent unauthorized access to this file. Supply this file to KRATool by adding the -source_pki_security_database_pwdfile <path to PKI password file> command-line option.</td>

20. Copy 'alpha2omega.ldif' to omega.example.com:

    sftp root@omega.example.com
    sftp> cd /export/pki
    sftp> put alpha2omega.ldif
    sftp> quit

Importing into omega

21. Login as 'root' on omega.example.com

22. Go to the data area

    cd /export/pki

23. Concatenate the ldif files:

    cat omega.ldif alpha2omega.ldif > omega_alpha.ldif

24. Import the file 'omega_alpha.ldif' into the RHDS 8.2 database associated with the PKI 10.5 KRA:

    /usr/lib64/dirsrv/slapd-omega/ldif2db -n omega.example.com-pki-kra -i /export/pki/omega_alpha.ldif

25. Restart directory server:

    systemctl start dirsrv@<ds_instance>

26. Restart the PKI 10.5 KRA:

    systemctl start pki-tomcatd@<instance>

Scenario with n to 1 migration

In this scenario, the admin is tasked with merging contents from multiple old KRAs into the latest KRA machine.

Please follow the same steps as Scenario with 1 to 1 migration and execute steps in exporting contents from machine in all the required machines