The iTP Secure WebServer version 7.0 key database is not compatible with iTP Secure WebServer 7.2 and later versions. To migrate the key database from version 7.0, you must use thedbmigrate utility distributed with iTP Secure WebServer.
Starting with iTP Secure WebServer Release 7.5, you can export the private keys in the following formats:
• PEMorDERencoded PKCS#8 format encrypted using either the3DES,AES128,AES192, or AES256algorithms
• PEMencoded format
To migrate the iTP Secure WebServer database, complete the following steps:
NOTE: Before migrating your iTP Secure WebServer 7.0 key database to iTP Secure WebServer 7.2 and later versions, store a copy of the key database in case you want to fallback to iTP Secure WebServer 7.0.
1. Using the followingdbmigrateutility commands, export the private keys from the old key database:
bin/dbmigrate -keydb <key-file> -exportpriv <key-file> -dn 'dn’ [ {[-encode <format>] [-crypt <algorithm>]} | [-nocrypt] ] where,
keydb
is the name of the key database file in which the private key is stored. key-file
is the name of the key database file in which the private key is stored. dn
is the associated DN of the private key to be exported. -encode <format>
specifies the encoding format for the private key. The valid format values arePEM orDER. The default encoding format is PEM.
You can specify this option anywhere after the–exportprivoption in the command line sequence.
–crypt <algorithm>
specifies the encryption format for storing the PKCS#8 encrypted keys. The valid values areAES256,AES192,AES128, or3DES. The default encryption algorithm isAES256.
You can specify this option anywhere after–exportprivoption in the command line sequence.
–nocrypt
specifies that the private key must be exported without encryption inPEMencoded format.
You can specify this option anywhere after–exportprivoption in the command line sequence.
When this option is used, the following warning appears:
Storing unencrypted private keys in disk files is not recommended.
Do not use–nocryptwith–crypt/-encodeoptions.
If you do not specify the-nocryptoption, you must provide the passphrase for encrypting the key before exporting it to disk file. The following example illustrates this export sequence:
./dbmigrate -keydb olddb -exportpriv keyfile –dn “CN=www.example.com”
Enter passphrase:
Enter passphrase for private key: Re-enter passphrase for private key:
Are you sure you want to export this entry? (y/n) y
The keyfile "keyfile" does not exist. Do you wish to create it? (y/n) y Private key is successfully exported to file.."keyfile"
Thedbmigratecommand prompts you for the passphrase of the key database. If you do not specify the–nocrypt option, the command prompts you for the passphrase to encrypt the private key. The passphrase specifications are same as that of passphrase for key database. If you enter a valid passphrase, the command prompts you to re-enter the passphrase for validation. After passphrase validation, the key is encrypted with the passphrase and exported in PKCS#8 format. A maximum of four attempts are allowed to enter the passphrase for the following cases:
• The passphrase specifications are not met • The passphrase validation fails
If thekey-filedoes not exist, you will be prompted to create the file. If thekey-file already exists, it is overwritten.
If the specified DN does not exist in the key database file, an error message is displayed. For example,
./dbmigrate -keydb demo.db -exportpriv priv.key -dn 'CN=www.hp.com, L=Cupertino, O=HP, OU=NED,C=US'
2. Using the followingdbmigrateutility tool command, export certificates from the old key database:
bin/dbmigrate -keydb <keydb> -exportcert <key-file> -dn 'dn' where,
<keydb>
is the name of the key database file in which the private key is stored. <key-file>
is the name of the disk file to which you want to export the certificate. dn
is the associated DN of the private key to be exported.
Thekeyadmincommand prompts you for the passphrase of the key database mentioned in thekeyadmin command.
If thekey-filedoes not exist, you will be prompted to create the file. If the key-file already exists, it will be overwritten.
If the specified DN does not exist in the key database file, an error message is displayed. The following examples illustrate the use ofdbmigrate command:
./dbmigrate -keydb demo.db -exportpriv priv.key –dn \ 'CN=www.hp.com, L=Cupertino, O=HP, OU=NED, C=US' \ –encode PEM –crypt 3DES
./dbmigrate -keydb demo.db -exportpriv priv.key –dn \ 'CN=www.hp.com, L=Cupertino, O=HP, OU=NED, C=US' \ –encode DER –crypt AES256
./dbmigrate -keydb demo.db -exportpriv priv.key –dn \ 'CN=www.hp.com, L=Cupertino, O=HP, OU=NED, C=US' ./dbmigrate -keydb demo.db -exportpriv priv.key –dn \ 'CN=www.hp.com, L=Cupertino, O=HP, OU=NED, C=US' -nocrypt
3. After exporting the certificates and the private keys from the old key database, perform the following steps to create the new key database:
a. Using the following command, import the private keys:
bin/keyadmin [-verbose] -importpriv <file> -dn <dn> -keydb <dbfile>
For more information about importing a private key, see“Importing a Private Key into iTP Secure WebServer's Key Database File” (page 68).
b. Using the following command, add the corresponding certificate:
bin/keyadmin [-verbose] -addcert <file> [-root] -keydb <dbfile> For more information about adding a certificate, see“Adding a Certificate to the Key Database File” (page 59).
4. Repeat the steps 1 through 3 for all other key database migrations.
5. Configure iTP Secure WebServer with the newly created key database and start the iTP Secure WebServer environment.
For more information about how to configure the iTP Secure WebServer environment, see “Configuring the iTP Secure WebServer” (page 94).