Topic - (1) Using keytool to generate a public-private key pair
The first step in configuring a VT Display session for SSH client authentication using a public key is to use the keytool program to generate a public-private key pair.
About keytool
keytool is a multipurpose utility program, included in the Java 2 Version 1.4 JRE and distributed with Z and I Emulator for Web, for managing keys and certificates.
A perspective from Unix-like platforms
Because keytool is a multipurpose tool for managing keys and certificates, you may find it easier to understand the generating of a public-private key pair by looking first at a less complex tool available on Unix-like platforms, named ssh-keygen . (This is for illustration purposes only. You cannot use ssh-keygen to generate public-private keys for Z and I Emulator for Web.)
Getting keytool
You can get access to keytool from the Z and I Emulator for Web server in either of two ways:
-
keytool is distributed with the Java run-time utilities installed with Z and I Emulator for Web. On the Windows
platform this tool is at the following location:
<install_directory>\jre\bin\keytool.exe
-
keytool is included in the Java 2 Version 1.4 JRE for the Windows platform that is distributed with Z and I Emulator
for Web. This is the JRE that clients running on Windows can download from the server. The file containing the JRE is
IBM-Win32-JRE.exe
. On the Windows platform of the Z and I Emulator for Web server this file is at the following location:<install_directory>\<publish_directory>\JREInstall\IBM-Win32-JRE.exe
- You must run the above .EXE file on a Windows platform to install the Java 2 Version 1.4 JRE on that platform.
Invoking keytool to generate a public-private key pair.
Here is an example of invoking keytool to create a public-private key pair. (In the example below the parameters are written on multiple lines for the purpose of clarity. When you invoke keytool, you must type the program name and its parameters all on one line.)
keytool
-genkey
-keystore f:\tm\keys\johnkeystore
-alias johnkey02
-storepass johnstorepass
-keypass johnstorepass
-dname "CN=John Smith, OU=Development, O=Standard Supplies Inc.,
L=Anytown, S=North Carolina, C=US"
The parameters have the following significance:
Parameter: | Significance: |
---|---|
-genkey | Tells keytool to generate a public-private key pair. |
-keystore | Specifies the path and file name of the keystore to be created (if it does not already exist) or to be added to (if it already exists). A keystore is a file that contains one or more public-private key pairs. |
-alias | Specifies the alias for the public-private key pair. An alias is a character string that identifies the public-private key pair within the keystore. |
-storepass | Specifies the password required to access the keystore. |
-keypass | Specifies the password required to access the public-private key pair. |
-dname | Specifies the distinguished name for a certificate associated with the key. Notice that the distinguished name is
enclosed in double quotation marks. The six parameters inside the quoted string have the following significance:
|
The items in the following list provide additional comments on each parameter in the example invocation of keytool above.
-
-genkey
keytool is a multi-purpose tool. This is the option that tells keytool to generate a public-private key pair. -
-keystore f:\tm\keys\johnkeystore
In contrast to ssh-keygen (the tool available on Unix-like platforms), which generates separate files for the public key and the private key, keytool stores both keys as a single entry in a file called a keystore. By running keytool multiple times, you can add multiple public-private key entries to the same keystore. Here the path and file name of the keystore isf:\tm\keys\johnkeystore
. -
-alias johnkey02
Because keytool allows more than one key pair to be stored in a keystore, keytool requires that an alias be specified for each new key pair. An alias is an identifying character string, such asmykey
orjohnkey02
, that distinguishes a key pair from other key pairs stored in the same keystore. An alias must be unique within a single keystore. -
-storepass johnstorepass
keytool requires you to specify a password for the keystore. Here the password isjohnstorepass
.If the keystore does not already exist, keytool creates the keystore and associates this password with it (encrypted). When you subsequently want to access the keystore, either to read from it or to write into it, you must specify the keystore password. If you forget the keystore password, there is no way to recover it.
Somewhat similarly, ssh-keygen (the tool available on Unix-like platforms) allows you to specify a password that is required to access the private key file.
-
-keypass johnstorepass
keytool also requires you to specify a password for the individual entry containing the public-private key pair. That is, not only do you need a password to open the keystore, but you also need a password to access an individual entry (containing a public-private key pair) in the keystore.If you like, you can simplify things somewhat by using the same password for the keystore password and the key password. Here the key password is the same as the keystore password,
johnstorepass
. -
-dname "CN=John Smith, OU=Development, O=Standard Supplies Inc., L=Anytown, S=North Carolina, C=US"
This information is needed to create a self-signed certificate. keytool wraps the public key in an X.509 v1 self-signed certificate.Although you must specify this information when you generate a public-private key pair with keytool, this certificate is not used by Z and I Emulator for Web or the SSH server during SSH client authentication using a public key.
There are a few other options that are used with the -genkey option. However, normally you should not specify these additional options. When you do not specify these options, keytool uses the default value. The following table shows the additional options and the default values that are used when you do not specify these additional options.
Parameter: | Significance (default value): |
---|---|
-keyalg | Algorithm used to generate the public-private key pair (DSA). |
-sigalg | Algorithm used to sign the certificate (when DSA is the default key algorithm, the default certificate-signing algorithm is SHA1withDSA). |
-keysize | Size of the public key and of the private key (1024 bits). |
-storetype | Format of the keystore (JKS, a proprietary keystore format of Sun Microsystems). |
-validity | Number of days before the self-signed certificate expires (180 days). Because the self-signed certificate is not used in SSH public key authentication, the expiration of the certificate does not affect a Z and I Emulator for Web session configured to use SSH with public key authentication. Public key authentication continues to function securely even after the self-signed certificate expires. |
Other operations you can perform with keytool
Click here to see a few of the other operations that you can perform with keytool.