Manage Digital Certificates with iKeyman

The iKeyman utility is a tool you can use to manage your digital certificates. With iKeyman, you can create a new key database or a test digital certificate, add CA roots to your database, copy certificates from one database to another, request and receive a digital certificate from a CA, set default keys, and change passwords.

The iKeyman utility is a part of the IBM Java Secure Socket Extension package.

 

Installation

iKeyman depends on .ibmjceprovider.jar, .ibmjcefw.jar.,  .ibmpkcs11.jar.,  .ibmpkcs.jar. along with the appropiate JCE policy jurasdiction files.

The sample code that invokes iKeyman assumes these 4 jars files reside under the same directory as iKeyman's jar, i.e.

$JAVA_HOME/jre/lib/ext/gskikm.jar
$JAVA_HOME/jre/lib/ext/ibmjceprovider
$JAVA_HOME/jre/lib/ext/ibmjcefw
$JAVA_HOME/jre/lib/ext/ibmpkcs11.jar
$JAVA_HOME/jre/lib/ext/ibmpkcs.jar

Update $JAVA_HOME/jre/lib/security/java.security and replace

"security.provider.2=com.ibm.crypto.provider.IBMJCA"

with

"security.provider.2=com.ibm.crypto.provider.IBMJCE"

Note that the IBMJCE provider must be placed after the default SUN JCA provider that is available with the JRE.

Update "LOCAL_PATH/jre/lib/security/java.security" file and add

"security.provider.3=com.ibm.crypto.pkcs11.provider.IBMPKCS11"

>if PKCS11 hardware crypto is needed.

Go to directory "LOCAL_PATH/demo/ikeyman" and enter:

"jar -xvf SampleIKEYMAN.jar"

The "iKeyman" window will appear to manage X509 certificates, certificate requests, and RSA keys in the supported key databases (files).

Note: The key tool is based on 3 default KeyStore types, PKCS12KS, JKS, JCEK. It tries to get KeyStore instances from them. If any type fails, this type then won't be shown in the supported key file list.

 

Starting iKeyman

Each of the tasks you wish to perform requires that iKeyman be running. To start iKeyman:

cd demo/ikeyman
jar -xvf SampleIKEYMAN.jar
ikeyman

 

Create a Key Database

A key database enables a client application to connect to those servers that have digital certificates signed by those CAs for which you have signed digital certificates.

To create a key file, follow these steps:

  1. Start iKeyman, if it is not already running.

  2. Click

    Key Database File | New

  3. Select JKS for the Key database type field.

  4. Change the values for the File Name and Location, if desired.

  5. Click OK.

    The Password Prompt window is displayed,

  6. Type a password in the Password field, and type it again in the Confirm Password field.

  7. Click OK. A confirmation window is displayed, verifying that you have created a key database.

  8. Click OK.

You have successfully created a key database, and the IBM Key Management window is displayed.

The IBM Key Management will reflect your new key file name and your signer digital certificates.

The following signer digital certificates are provided with iKeyman:

These signer digital certificates enable your clients to connect to servers that have valid digital certificates from these signers. Now that you have created a key database, you can use it on your client and connect to a server that has a valid digital certificate from one of the signers.

To use a signer digital certificate that is not on this list, you need to request it from the CA and add it to your key database.

Note: The VeriSign Test CA Root Certificate is a low-assurance CA that is included for testing purposes. You should remove this root before placing a key database class into a production application.

 

Create a Self-signed Digital Certificate for Testing

When you are developing a production application, you might not want to purchase a true digital certificate until after you are done testing the product. With iKeyman, you can create a self-signed digital certificate to use until testing is complete. A self-signed digital certificate is a temporary digital certificate you issue to yourself, with yourself as the CA.

Note: Do not release a production application with a self-signed digital certificate; no browser or client will be able to recognize or communicate with your server.

To create a self-signed digital certificate, follow these steps:

  1. Start iKeyman, if it is not already running.

  2. Click Key Database File . Open to display the Open window.

  3. Select the key database file to which you want to add a self-signed digital certificate and click Open. The Password Prompt window is displayed.

  4. Type the password and click OK. The IBM Key Management window is displayed. The title bar shows the name of the key database file you selected, indicating that the file is open and ready.

  5. Select Personal Certificates from the pulldown list.

  6. Click New Self-Signed. The Create New Self-Signed Certificate window is displayed.

  7. Type a Key Label, such as keytest, for the self-signed digital certificate.

  8. Type a Common Name and Organization, and select a Country. For the remaining fields, either accept the default values, or type or select new values.

  9. Click OK. The IBM Key Management window is displayed. The Personal Certificates field shows the name of the self-signed digital certificate you created.

 

Adding a CA Root Digital Certificate

After you have requested and received a CA root digital certificate from a CA, you can add it to your database. Most root digital certificates have the form *.arm (for example, cert.arm).

To add a CA root digital certificate to a database, follow these steps:

  1. Start iKeyman, if it is not already running.

  2. Click Key Database File . Open to display the Open window.

  3. Select the key database file to which you want to add a CA root digital certificate and click Open. The Password Prompt window is displayed.

  4. Type the password and click OK. The IBM Key Management window is displayed. The title bar shows the name of the key database file you selected, indicating that the file is open and ready.

  5. Select Signer Certificates from the pulldown list.

  6. Click Add. The Add CA.s Certificate from a File window is displayed.

  7. Click Data type and select a data type, such as Base64-encoded ASCII data.

  8. Type a Certificate file name and Location for the CA root digital certificate, or click Browse to select the name and location.

  9. Click OK. The Enter a Label window is displayed.

  10. Type a label for the CA root digital certificate, such as VeriSign Test CA Root Certificate, and click OK. The IBM Key Management window is displayed.

The Signer Certificates field now shows the label of the CA root digital certificate you just added.

 

Deleting a CA Root Digital Certificate

If you no longer want to support one of the signers in your signer digital certificate list, you need to delete the CA root digital certificate.

Note: Before deleting a CA root digital certificate, create a backup copy in case you later want to re-create the CA root.

To delete a CA root digital certificate from a database, follow these steps:

  1. Start iKeyman, if it is not already running.

  2. Click Key Database File . Open to display the Open window.

  3. Select the key database file from which you want to delete a CA root digital certificate and click Open. The Password Prompt window is displayed.

  4. Type the password and click OK. The IBM Key Management window is displayed. The title bar shows the name of the key database file you selected, indicating that the file is open and ready.

  5. Select Signer Certificates from the pulldown list.

  6. Select the CA root digital certificate you want to delete and click Delete. The Confirm window is displayed.

  7. Click Yes. The IBM Key Management window is displayed. The label of the CA root digital certificate you just deleted no longer appears in the Signer Certificates field.

 

Copying Certificates from One Key Database to another

When setting up a private trust network or using self-signed certificates for testing purposes, you might find it necessary to extract a certificate from a database to be added to another database as a signer or site certificate. Other times, you might want to export a personal certificate and import it as a personal certificate.

First scenario: To extract a certificate from the (source) key database to be added as a signer or site certificate in the (target) key database, follow these steps:

  1. Start iKeyman, if it is not already running.

  2. Click Key Database File . Open. The Open window is displayed.

  3. Select the (source) key database containing the certificate that you would like to add to another (target) database as a signer or site certificate and click Open. The Password Prompt window is displayed.

  4. Type the password and click OK. The IBM Key Management window is displayed. The title bar shows the name of the key database file you selected, indicating that the class is open and ready.

  5. Select the type of certificate you want to export: Personal, Signer, or Site.

  6. Select the certificate that you want to add to another database.

  7. If you select Personal, click the Extract Certificate pushbutton. If you select Signer or Site, click the Extract pushbutton. The Extract a Certificate to a File window is displayed. You will proceed with the remaining steps.

  8. Click Data type and select a data type, such as Base64-encoded ASCII data. The data type needs to match the data type of the certificate stored in the certificate file. The iKeyman tool supports Base64-encoded ASCII files and binary DER-encoded certificates.

  9. Type the certificate file name and location where you want to store the certificate, or click Browse to select the name and location.

  10. Click OK. The certificate is written to the specified file, and the IBM Key Management window is displayed.

To add a certificate as a signer or site certificate to the database (target), follow these steps:

  1. Start iKeyman, if it is not already running.

  2. Click Key Database File . Open to display the Open window.

  3. Select the key database to which you would like to add the certificate that has been extracted from above and click Open. The Password Prompt window is displayed.

  4. Type the password and click OK. The IBM Key Management window is displayed. The title bar shows the name of the key database file you selected, indicating that the class is open and ready.

  5. Select the type of certificate you would like to add: Signer or Site.

  6. Click Add. If you had selected Signer Certificates from the pulldown list the Add CA.s Certificate from a File window displays. If you had selected Site Certificates from the 16 pulldown list the Add Site Certificate window displays. For more information concerning these two windows see step 8 on page 16 above.

  7. Type the certificate file name that you used when you extracted a certificate. For more information, see step 9 on page 16 above.

  8. The Enter a Label window displays.

  9. Specify the name of the certificate, and click OK.

    The certificate is now added to the (target) database.

Second scenario: In the previous scenario, you extracted a personal, signer, or site certificate from a source database and added it to the target database as a signer or site certificate. This scenario exports a personal certificate from a source database and imports it to a target database as a personal certificate.

To export a personal certificate from the (source) key database to be imported as a personal certificate in the (target) key database follow these steps:

  1. Start iKeyman, if it is not already running.

  2. Click...

    Key Database File | Open | (source) key database | Open

  3. Type the password and click OK. The IBM Key Management window is displayed. The title bar shows the name of the key database file you selected, indicating that the class is open and ready.

  4. Select Personal Certificates from the pulldown list.

  5. Select the personal certificate you want to export.

  6. Select the Export/Import pushbutton to transfer keys between the current database and a PKCS#12 file or another database. The Export/Import Key window displays.

  7. Select Export from the Choose Action Type.

  8. Select Key File Type (for example, PKCS12 file) from the pulldown to export list.

  9. Type the certificate file name (for example. copy.p12) that you would like to export and the location where you want to store the certificate, or click Browse to select the name and location and click OK. The Password Prompt window displays.

  10. Enter a password for the password file, confirm the password, and click OK. The certificate is now extracted from the (source) database. To import a personal certificate to the (target) key database, follow these steps:

  11. Start iKeyman, if it is not already running.

  12. Click Key Database File . Open. The Open window is displayed.

  13. Select the (target) key database to which you would like to import the certificate that has been exported above and click Open. The Password Prompt window is displayed.

  14. Type the password and click OK. The IBM Key Management window is displayed. The title bar shows the name of the key database file you selected, indicating that the class is open and ready.

  15. Select the Personal Certificates from the pulldown list.

  16. If the target key database has no personal certificate, click the Import pushbutton to import keys from a PKCS#12 file or another database. The Import Key window displays. If target key database has one or more personal certificates, do:
    • Click the Export/Import key pushbutton, the Export/Import key window displays.
    • Select Import from the Choose Action Type.

  17. Select the same key file type that you specified from the export. For more information, see step 10 on page 16, and click OK. The Password Prompt window is displayed.

  18. Specify the password from when you exported.

    The certificate is now imported to the (target) database.

 

Requesting a Digital Certificate

A digital certificate is required to run the SSL-enabled server code and might be required for client applications. To acquire a digital certificate, generate a request using iKeyman and submit the request to a CA. The CA will verify your identity and send you a digital certificate.

To request a digital certificate, follow these steps:

  1. Start iKeyman

  2. Click Key Database File | Open. The Open window is displayed.

  3. Select the key database file from which you want to generate the request and click Open. The Password Prompt window is displayed.

  4. Type the password and click OK. The IBM Key Management window is displayed. The title bar shows the name of the key database file you selected, indicating that the file is open and ready.

  5. Select Personal Certificate Requests from the pulldown list.

  6. Click New. The Create New Key and Certificate Request window is displayed, as shown in Figure 10 on page 19. 18

  7. Type a Key Label, such as Production Certificate for MyWeb at My Company, for the self-signed digital certificate.

  8. Type a Common Name and Organization and select a Country. For the remaining fields, either accept the default values, or type or select new values.

  9. At the bottom of the window type a name for the file, such as certreq.arm.

  10. Click OK. A confirmation window is displayed, verifying that you have created a request for a new digital certificate.

  11. Click OK. The IBM Key Management window is displayed. The Personal Certificate Requests field shows the key label of the new digital certificate request you created.

  12. Send the file to a CA to request a new digital certificate, or cut and paste the request into the request forms of the CA.s Web site.

 

Receiving a Digital Certificate

After the CA sends you a new digital certificate, you need to add it to the key database from which you generated the request.

To receive a digital certificate, follow these steps:

  1. Start iKeyman, if it is not already running.

  2. Click Key Database File . Open. The Open window is displayed.

  3. Select the key database file from which you generated the request and click Open. The Password Prompt window is displayed.

  4. Type the password and click OK. The IBM Key Management window is displayed. The title bar shows the name of the key database file you selected, indicating that the file is open and ready.

  5. Select Personal Certificates from the pulldown list.

  6. Click Receive. The Receive Certificate from a File window is displayed.

  7. Click Data type and select the data type of the new digital certificate, such as Base64-encoded ASCII data. If the CA sends the certificate as part of an e-mail message, then you might need to cut and paste the certificate into a separate file.

  8. Type the Certificate file name and Location for the new digital certificate, or click Browse to select the name and location.

  9. Click OK. The Enter a Label window is displayed.

  10. Type a label, such as RALVS6 Banking Certificate, for the new digital certificate and click OK. The IBM Key Management window is displayed. The Personal Certificates field shows the label of the new digital certificate you added.

 

Deleting a Digital Certificate

If you no longer need one of your digital certificates, you need to delete it from your database.

Note: Before deleting a digital certificate, create a backup copy in case you later want to re-create it.

To delete a digital certificate, follow these steps:

  1. Start iKeyman, if it is not already running.

  2. Click Key Database File . Open. The Open window is displayed.

  3. Select the key database file from which you want to delete the digital certificate and click Open. The Password Prompt window is displayed.

  4. Type the password and click OK. The IBM Key Management window is displayed. The title bar shows the name of the key database file you selected, indicating that the file is open and ready.

  5. Select Personal Certificates from the pulldown list.

  6. Select the digital certificate you want to delete and click Delete. The Confirm window is displayed.

  7. Click Yes. The IBM Key Management window is displayed. The label of the digital certificate you just deleted no longer appears in the Personal Certificates field.

 

Change a Database Password

The iKeyman tool allows you to change a database password. To change a database password, follow these steps:

  1. Start iKeyman, if it is not already running.

  2. Click Key Database File . Open. The Open window is displayed.

  3. Select the key database file in which you want to change the password and click Open. The Password Prompt window is displayed. 20

  4. Type the password and click OK. The IBM Key Management window is displayed. The title bar shows the name of the key database file you selected, indicating that the file is open and ready.

  5. Click Key Database File . Change Password. The Change Password window is displayed.

  6. Type a new password in the Password field, and type it again in the Confirm Password field.

  7. Click OK. A message in the status bar indicates that the request completed successfully.

 

Home