The following key-management program, ikeyman,
is provided with IBM® JAVA. It
is a user-friendly GUI for managing key files, which is implemented
as a Java applet. IBM JAVA version 6 is available
when you install IBM Tivoli® Directory Server version
6.3. The ikeyman utility is available on Windows in the <TDS_Install_Directory>\java\jre\bin
directory, on Linux in the
/opt/ibm/ldap/V6.3/java/jre/bin directory, and on AIX® and Solaris systems in the /opt/IBM/ldap/V6.3/java/jre/bin
directory.
Note:
If you are prompted to set JAVA_HOME, you can set
it to the java subdirectory of the IBM Tivoli Directory Server. If you
use IBM Tivoli Directory Server, you also need to set the
LIBPATH environment variable as follows:
c:\> set LIB=%JAVA_HOME%\bin; %JAVA_HOME%\jre\bin; %LIB%
On AIX systems use the
LIBPATH environment variable to specify the library path, and on Solaris
systems use the LD_LIBRARY_PATH environment variable.
Use ikeyman to create public-private key
pairs and certificate requests, receive certificate requests into
a key database file, and manage keys in a key database file.
Note:
When setting up Secure Sockets Layer communications, ensure
that you use the correct key database file type for your application.
For example, Java-based applications such as the Web Administration
Console require JKS file types, while C-applications
like IBM Tivoli Directory Server require CMS key
database file types.
Creating a key pair and requesting a certificate from a Certificate
Authority
If your client application is connecting to an LDAP server that
requires client and server authentication, then you need to create
a public-private key pair and a certificate.
If your client application is connecting to an LDAP server that
requires only server authentication, it is not necessary to create
a public-private key pair and a certificate. It is sufficient to have
a certificate in your client key database file that is marked as a
trusted root. If the Certification Authority (CA) that issued the
server's certificate is not already defined in your client key database,
you need to request the CA's certificate from the CA, receive it into
your key database, and mark it as trusted. See Designating a key as a trusted root.
Your client uses its private key to sign messages sent to servers.
The server sends its public key to clients so that they can encrypt
messages to the server, which the server decrypts with its private
key.
To send its public key to a server, the client needs a certificate.
The certificate contains the client's public key, the Distinguished
Name associated with the client's certificate, the serial number of
the certificate, and the expiration date of the certificate. A certificate
is issued by a CA, which verifies the identity of the client.
The basic steps to create a certificate that is signed by a CA
are:
Create a certificate request using ikeyman.
Submit the certificate request to the CA. This can be done using
e-mail or an online submission from the CA's Web page.
Receive the response from the CA to an accessible location on
the file system of your server.
If you are obtaining a signed client certificate
from a CA that is not in the default list of trusted CAs, you need
to obtain the CA's certificate, receive it into your key database
and mark it as trusted. This must be done before receiving your signed
client certificate into the key database file.
To create a public-private key pair and request a certificate:
Start the ikeyman Java utility by typing:
ikeyman
Select Key Database File.
Select New (or Open if
the key database already exists).
Specify a key database type, key database file name, and location.
Click OK.
Note:
A key database is a
file that the client or server uses to store one or more key pairs
and certificates.
When prompted, supply a password for the key database file. Click OK.
Select Create.
Select New Certificate Request.
Supply user-assigned label for key pair. The label identifies
the key pair and certificate in the key database file.
If you are requesting a low-assurance client certificate, enter
the common name. This must be unique and the full name of the user.
If you are requesting a high-assurance secure server certificate,
then:
Enter the X.500 common name of the server. Usually this is the
TCP/IP fully qualified host name, for example, www.ibm.com. For a
VeriSign server certificate, it must be the fully qualified host name.
Enter the organization name. This is the name of your organization.
For a VeriSign secure server certificate, if you already have an account
with VeriSign, the name in this field must match the name on that
account.
Enter the organizational unit name. This is an optional field.
Enter the locality/city where the server is located. This is an
optional field.
Enter a three-character abbreviation of the state/province where
the server is located.
Enter the postal code appropriate for the server's location.
Enter the two-character country code where the server is located.
Click OK.
A message identifying the name and location of the certificate
request file is displayed. Click OK.
Send the certificate request to the CA.
If this is a request
for a VeriSign low assurance certificate or secure server certificate,
you must e-mail the certificate request to VeriSign.
You can
mail the low assurance certificate request to VeriSign immediately.
A secure server certificate request requires more documentation. To
find out what VeriSign requires for a secure server certificate request,
go to the following URL: http://www.verisign.com/server/index.html.
When you receive the certificate from the CA, use ikeyman to
receive it into the key database where you stored the key pair. See Receiving a certificate into a key database.
Note:
Change the key database password frequently. If you
specify an expiration date, you need to keep track of when you need
to change the password. If the password expires before you change
it, the key database is not usable until the password is changed.
Receiving a certificate into a key database
After receiving a response from your CA, you need to receive the
certificate into a key database.
To receive a certificate into a key database:
Type ikeyman to start the Java utility.
Select Key Database File.
Select Open.
Specify the key database type, key database file name, and location.
Click OK.
When prompted, supply a password for the key database file. Click OK.
Select Create.
Select Personal Certificates in the middle
window.
Click Receive.
Enter the name and location of the certificate file that contains
the signed certificate, as received from the CA. Click OK.
Changing a key database password
To change a key database password:
Type ikeyman to start the Java utility.
Select Key Database File.
Select Open.
Specify the key database type, key database file name, and location.
Click OK.
When prompted, supply the password for the key database file.
Click OK.
Select Key Database File.
Select Change password.
Enter <New password>.
Confirm <New password>.
Select and set an optional password expiration time.
Select Stash the password to a file? if
you want the password to be encrypted and stored on disk.
Click OK.
A message is displayed with the file name and location of the
stash password file. Click OK.
Note:
The password is important because it protects
the private key. The private key is the only key that can sign documents
or decrypt messages encrypted with the public key.
Showing information about a key
To show information about a key, such as its name, size or whether
it is a trusted root:
Type ikeyman to start the Java utility.
Select Key Database File.
Select Open.
Specify the key database type, key database file name, and location.
Click OK.
When prompted, supply the password for the key database file.
Click OK.
To see information about keys designated as Personal certificates:
Select Personal Certificates from the list
under the Key database content section.
Select a certificate.
Click View/Edit to display information about
the selected key.
Click OK to return to the list of Personal
Certificates.
To see information about keys that are designated as Signer Certificates:
Select Signer Certificates from the list
under the Key database content section.
Select a certificate .
Click View/Edit to display information about
the selected key.
Click OK to return to the list of Signer
Certificates.
Deleting a Key
To delete a key:
Type ikeyman to start the Java utility.
Select Key Database File.
Select Open.
Specify the key database type, key database file name, and location.
Click OK.
When prompted, supply the password for the key database file.
Click OK.
Select the type of key you want to delete from the list under
the Key database content section (Personal Certificates,
Signer Certificates, or Personal Certificate Requests).
Select a certificate.
Click Delete.
Click Yes to confirm.
Making a key the default key in the key ring
The default key must be the private key that the server uses for
its secure communications.
To make a key the default key in the key ring:
Type ikeyman to start the Java utility.
Select Key Database File.
Select Open.
Specify the key database type, key database file name, and location.
Click OK.
When prompted, supply the password for the key database file.
Click OK.
Select Personal Certificates from the list
under the Key database content section.
Select the desired certificate.
Click View/Edit.
Select the Set the certificate as the default box.
Click OK.
Creating a key pair and certificate request for self-signing
By definition, a secure server must have a public-private key pair
and a certificate.
The server uses its private key to sign messages to clients. The
server sends its public key to clients so they can encrypt messages
to the server, which the server decrypts with its private key.
The server needs a certificate to send its public key to clients.
The certificate contains the server's public key, the distinguished
name associated with the server's certificate, the serial number of
the certificate, and the expiration date of the certificate. A certificate
is issued by a CA, who verifies the identity of the server.
You can request one of the following certificates:
A low assurance certificate from VeriSign, best for non-commercial
purposes, such as a beta test of your secure environment
A server certificate to do commercial business on the Internet
from VeriSign or some other CA
A self-signed server certificate if you plan to act as your own
CA for a private Web network
The basic steps to creating a self-signed certificate are:
Type ikeyman to start the Java utility.
Select Key Database File.
Select New, or Open if
the key database already exists.
Specify a key database type, key database file name, and location.
Click OK.
Note:
A key database is a
file that the client or server uses to store one or more key pairs
and certificates.
When prompted, supply the password for the key database file.
Click OK.
Click New self-signed.
Supply the following:
User-assigned label for the key pair. The label identifies the
key pair and certificate in the key database file.
The desired certificate Version.
The desired Key Size.
The desired Signature Algorithm.
The X.500 common name of the server. Usually this is the TCP/IP
fully qualified host name, for example, www.ibm.com.
The organization name. This is the name of your organization.
The organizational unit name. This is an optional field.
The locality/city where the server is located. This is an optional
field.
A three-character abbreviation of the state/province where the
server is located.
The zip code appropriate for the server's location.
The two-character country code where the server is located.
The Validity Period for the certificate.
Click OK.
Exporting a key
If you need to transfer a key pair or certificate to another computer,
you can export the key pair from its key database to a file. On the
other computer, you can import the key pair
into a key ring.
To export a key from a key database:
Type ikeyman to start the Java utility.
Select Key Database File.
Select Open.
Specify the key database type, key database file name, and location.
Click OK.
When prompted, supply the password for the key database file.
Click OK.
Select Personal Certificates from the list
under the Key database content section.
Select the desired certificate.
Click Export/Import.
For Action type, select Export
Key.
Select the Key file type.
Note:
IBM Tivoli Directory
Server requires CMS key database file types.
Specify a file name.
Specify the location.
Click OK.
Enter the required password for the file. Click OK.
Importing a key
To import a key into a key ring:
Type ikeyman to start the Java utility.
Select Key Database File.
Select Open.
Specify the key database type, key database file name, and location.
Click OK.
When prompted, supply the password for the key database file.
Click OK.
Select Personal Certificates from the list
under the Key database content section.
Select the desired certificate.
Click Export/Import.
For Action type, select Import
Key.
Select the desired Key file type.
Note:
When setting
up Secure Sockets Layer communications, ensure that you use the correct
key database file type for your application. For example, Java-based
applications such as the Web Administration Console require JKS file
types, while C-applications like IBM Tivoli Directory Server require
CMS key database file types.
Enter the file name and location.
Click OK.
Enter the required password for the source file. Click OK.
Designating a key as a trusted root
A trusted root key is the public key and associated distinguished
name of a CA. The following trusted roots are defined in each new
key database:
Entrust.net Certification Authority (2048)
Entrust.net Client Certification Authority
Entrust.net Global Client Certification Authority
Entrust.net Global Secure Server Certification Authority
Entrust.net Secure Server Certification Authority
RSA Secure Server Certification Authority
Thawte Personal Basic CA
Thawte Personal Freeemail CA
Thawte Personal Premium CA
Thawte Premium Server CA
Thawte Server CA
VeriSign Class 1 Public Primary Certification Authority
VeriSign Class 1 Public Primary Certification Authority -
G2
VeriSign Class 1 Public Primary Certification Authority -
G3
VeriSign Class 2 Public Primary Certification Authority
VeriSign Class 2 Public Primary Certification Authority -
G2
VeriSign Class 2 Public Primary Certification Authority -
G3
VeriSign Class 3 Public Primary Certification Authority
VeriSign Class 3 Public Primary Certification Authority -
G2
VeriSign Class 3 Public Primary Certification Authority -
G3
VeriSign Class 4 Public Primary Certification Authority -
G2
VeriSign Class 4 Public Primary Certification Authority -
G3
Note:
Each of these trusted roots are initially set
to be trusted roots by default.
To designate a key as a trusted root:
Type ikeyman to start the Java utility.
Select Key Database File.
Select Open.
Specify the key database type, key database file name, and location.
Click OK.
When prompted, supply the password for the key database file.
Click OK.
Select Signer Certificates from the list
under the Key database content section.
Click Populate.
From the Add CA Certificates dialog box, select the desired certificates.
Click View/Edit.
Check the Set the certificate as a trusted root check
box, and click OK.
Select Key Database File, and then select Close.
Removing a key as a trusted root
A trusted root key is the public key and associated distinguished
name of a CA. The following trusted roots are defined in each new
key database:
Entrust.net Certification Authority (2048)
Entrust.net Client Certification Authority
Entrust.net Global Client Certification Authority
Entrust.net Global Secure Server Certification Authority
Entrust.net Secure Server Certification Authority
RSA Secure Server Certification Authority
Thawte Personal Basic CA
Thawte Personal Freeemail CA
Thawte Personal Premium CA
Thawte Premium Server CA
Thawte Server CA
VeriSign Class 1 Public Primary Certification Authority
VeriSign Class 1 Public Primary Certification Authority -
G2
VeriSign Class 1 Public Primary Certification Authority -
G3
VeriSign Class 2 Public Primary Certification Authority
VeriSign Class 2 Public Primary Certification Authority -
G2
VeriSign Class 2 Public Primary Certification Authority -
G3
VeriSign Class 3 Public Primary Certification Authority
VeriSign Class 3 Public Primary Certification Authority -
G2
VeriSign Class 3 Public Primary Certification Authority -
G3
VeriSign Class 4 Public Primary Certification Authority -
G2
VeriSign Class 4 Public Primary Certification Authority -
G3
Note:
Each of these trusted roots are initially set
to be trusted roots by default.
To remove the trusted root status of a key:
Type ikeyman to start the Java utility.
Select Key Database File.
Select Open.
Specify the key database type, key database file name, and location.
Click OK.
When prompted, supply the password for the key database file.
Click OK.
Select Signer Certificates from the list
under the Key database content section.
Select the desired certificate.
Click View/Edit.
Clear the Set the certificate as a trusted root check
box. Click OK.
Select Key Database File, and then select Close.
Requesting a certificate for an existing key
To create a certificate request for an existing key:
Type ikeyman to start the Java utility.
Select Key database file.
Select Open.
Specify the key database type, key database file name, and location.
Click OK.
When prompted, supply the password for the key database file.
Click OK.
Select Personal Certificates from the list
under the Key database content section.
Select the desired certificate.
Click Export/Import.
For Action type, select Export
Key.
Select the desired key file type.
Enter the certificate file name and location.
Click OK.
Select Key Database File, and then select Close.
Send the certificate request to the CA.
If this is a request for a VeriSign low assurance certificate or
secure server certificate, you must e-mail the certificate request
to VeriSign.
You can mail the low assurance certificate request to VeriSign
immediately. A secure server certificate request requires more documentation.
To find out what VeriSign requires for a secure server certificate
request, go to the following URL: http://www.verisign.com/server/index.html.
Migrating a key ring file to the key database format
The ikeyman program can be used to migrate
an existing key ring file, as created with mkkf,
to the format used by ikeyman.
To migrate a key ring file:
Type ikeyman to start the Java utility.
Select Key Database File.
Select Open.
Specify the key database type, key database file name, and location.
Click OK.
When prompted, supply the password for the key ring file. Click OK.