GSKit supports two installation methods: global and local. Both types of installations may be present on a system at the same time.
- On a global installation, a single GSKit instance is shared by multiple products. In this configuration, GSKit libraries and executable files are placed in a common location on the system outside of the product's installation directory. If more than one product uses the same GSKit version, these products will not create multiple copies of GSKit, but instead share the single global copy.
- On a local installation, each product has its own, private version of GSKit. In this configuration, GSKit files are placed somewhere within the product's directory structure and their location may or may not be documented. If a global installation exists on the system, it is ignored by the product, which uses only its local installation of GSKit.
Different major versions of GSKit (for example, version 7 and version 8) are separate and can coexist as global installations.
This tutorial discusses GSKit versions 7 and 8 only, not any prior versions. All examples are given for GSKit 8. Unless noted otherwise, the same commands and options that are provided in the examples also work in version 7.
The GSKit command-line tool is named as follows:
<version> is the GSKit major
version (either 7 or 8). The
_64 suffix is
added on 64-bit platforms. For simplicity, this tutorial omits the
suffix, and uses
gsk8capicmd in the
To locate the GSKit installation on your system:
- Read the product documentation for any guidance on locating and
running GSKit. Usually, if a product requires running the GSKit
command-line tool, it also documents its location. Some products
may provide their own wrapper scripts that set the correct GSKit
environment and pass the arguments to the correct instance of
GSKit command-line tool. If this is the case, skip the rest of
this section and the next section, "Configuring the
environment to run GSKit", and use the script name instead of
- Determine if there is a global installation of GSKit:
- On UNIX or Linux®, enter one of the following
gsk8capicmd, on the command line. If anything other than an error message is returned, GSKit is installed and ready to use.
Windows®, open Registry Editor and look for one of
the following keys:
These keys indicate where GSKit is installed.
- On UNIX or Linux®, enter one of the following commands,
- You can search the product's installation directories or the
entire file system/disk for files and directories containing
"gsk." There are two subdirectories,
bin, containing GSKit shared libraries and binaries.
The process to configure your environment to run GSKit varies depending on the type of platform you are using.
For global installations of GSKit, no configuration is needed. The command-line tool is already on the executable path, and the libraries are in their standard system location. The GSKit commands can be run from any terminal window.
For local installations of GSKit, add its shared libraries directory to your environment:
export <Shared library path environment variable>=<GSKit library path> export PATH=$PATH:<GSKit binary path>
The shared library path variable name depends on your platform:
Table 1. Shared library path environment variable name
For example, to set the environment on Linux, use:
export LD_LIBRARY_PATH=/path/to/gskit/lib export PATH=$PATH:/path/to/gskit/bin
Add both library and binary paths to the PATH environment variable. You can do this either in a command-line window for a single session, or change the global settings. To add the paths using a command line, type:
Some tasks in this tutorial use OpenSSL. See Resources for instructions on obtaining OpenSSL, and follow the OpenSSL instructions for installing it on your system.
GSKit stores public and private keys and certificates in a key
database. A key database consists of a file with a
.kdb extension and up to three other files
Your product may have already created a key database. If so, look at the product documentation to find its location. If you don't already have a key database, you need to create and initialize a new one.
To create and initialize a new key database, run the following command (depending on your version):
- Version 7:
gsk7capicmd -keydb -create -db <filename>.kdb -pw <password> -stash
- Version 8:
gsk8capicmd -keydb -create -populate -db <filename>.kdb -pw <password> -stash
-db parameter indicates the file name
for the new key database. The
indicates the password to use to protect the key database file. The
-populate parameter in version 8 is
optional and tells GSKit to populate the key database with a number of
predefined trusted CA certificates. Version 7 always populates the new
key database with the predefined trusted CA certificates. The
-stash parameter tells GSKit to save the
specified key database password locally in the .sth file so that it
doesn't have to be entered on the command line in the future.
In the example scenarios in this tutorial, the following key database names are used:
server.kdb: Server key database
client.kdb: Client key database
ca.kdb: Certificate Authority key database