InfoCenter Home >
5: Securing applications -- special topics >
5.5: Tools for managing keys >
5.5.6: Tools for managing certificates and keys >
5.5.6.1: The CFWK tools for certificate and key management >
5.5.6.1.4: The VaultTool tool

5.5.6.1.4: The VaultTool tool

The VaultTool command supports a suite of subcommands for creating and managing keyrings. This tool maintains a master database of certificates and keys, the vault, from which selected contents can be exported to keyrings for individuals users.

The tool does not directly manipulate keyring files; all manipulation is done in the vault. For example, to add a new certificate to a server's keyring, you add the certificate to the vault and export a new edition of the keyring file for the server to use.

Common syntax

When invoking VaultTool, you must specify a password and the file in which the vault is stored. The password simply protects access to the vault file. This syntax is common to all VaultTool commands. Each subcommand takes a specific set of arguments.

java com.ibm.cfwk.tools.VaultTool --password U_vaultpasswd U_vaultfile
subcommand subcommand-args

Subcommands

The tool supports the following subcommands;

  • list: lists the contents of the vault
  • delete: deletes specific information from the vault
  • add public cert: adds the certificate for a CA to the vault
  • add private key: places a private key in the vault
  • add public chain: adds a chain of certificates to the vault
  • container: writes information from the vault to a keyring file

Although each VaultTool subcommand takes its own set of arguments, they are drawn from a common set. The following lists the arguments used by the VaultTool subcommands.

U_label
A string used to categorize information for a specific principal; all keys, certificates, and chains used by a principal should have the same label.
U_info
User information to be stored with an entry. This information can be stored in one of three encodings, hexadecimal, binary, or base 64. The U_info itself is expressed as a string appended by -hex, -bin or -b64, for example, A1269E-hex.
U_keyfile
The file holding a user's keys.
U_certfile
A file containing a certificate.
U_signerfile
A file containing a certificate for a principal that has signed certificates for others, used when adding a chain to the vault.
U_sslightpassword
The password for the keyring database.
U_class
The class name for the keyring file (an SSLight database). Do not include the .class file extension.

list: Lists the contents of the vault, in a short or long format.
Syntax:

list --long

delete: Removes entries under a specific label from the vault.
Syntax:

delete U_label

add public cert: Adds the certificate for a trustworthy CA to the vault. Use this to build the trust base for your application.
Syntax:

add public cert U_label
[U_info]
U_certfile
Example:
java com.ibm.cfwk.tools.VaultTool --password "WebAS"
d:\projects\websphere\keyrings\WebAS.Test.Vault.vlt
add public cert
WebAStestCA 00-hex d:\projects\websphere\keyrings\WebAS.TestCA.cert

The example above adds the self-signed certificate for the local TestCA to the vault. This entry in the vault is stored under the label WebAStestCA.

add private key: Copies the private key from a keyfile and adds it to the vault.
Syntax:

add private key U_label
[U_info]
U_keyfile
Example:
java com.ibm.cfwk.tools.VaultTool --password "WebAS"
d:\projects\websphere\keyrings\WebAS.Test.Vault.vlt
add private key
WebAStestServer 00-hex d:\projects\websphere\keyrings\WebAS.TestServer.key

The example above adds the private key for the TestServer, stored in the file WebAS.TestServer.key, to the vault stored in the file WebAS.Test.Vault.vlt. This entry in the vault is stored under the label WebAStestServer.

add public chain: Adds a chain of certificates to the vault. A certificate chain includes a server includes the server's certificate and the certificate of each prior issuing CA (there may be more than one). The complete chain must be added at one invocation of the tool, and each certificate must be read from a separate file.
Syntax:

add public chain U_label
[U_info]
U_certfile
U_signerfile+

When adding both a key and a certificate chain for the same owner to the vault, the values specified for U_label and U_info must match in both the "add private key" and "add public chain" invocations.

Example:

java com.ibm.cfwk.tools.VaultTool --password "WebAS"
d:\projects\websphere\keyrings\WebAS.Test.Vault.vlt
add public chain
WebAStestServer 00-hex d:\projects\websphere\keyrings\WebAS.TestServer.cert
d:\projects\websphere\keyrings\WebAS.TestCA.cert

The example above a chain of certificates for the TestServer to the vault. The chain includes two certificates: the TestServer's certificate and the certificate the issuing CA. Note that the U_label ("WebAStestServer") and the U_info ("00-hex") used in this example match those used in the "add private key" example for the TestServer.

container: Writes the contents (or labeled components) of the vault out to a keyring file. The keyring class is written to the current directory, regardless of the specified Java package name. You must then copy it to a location matching the Java package.
Syntax:

container -p U_sslightpassword
U_class
[U_label*]
Example:
java com.ibm.cfwk.tools.VaultTool --password "WebAS"
d:\projects\websphere\keyrings\WebAS.Test.Vault.vlt
container -p "WebAS" com.ibm.websphere.DummyKeyring
WebAStestServer WebAStestCA

The example above exports the information in the vault for the TestServer and TestCA (requested by the labels "WebAStestServer" and "WebAStestCA") to the WebSphere provided keyring file called DummyKeyring. This keyring file is protected with the password "WebAS."

Note   This is a general-purpose tool with applications beyond those discussed here. This page discusses only the subset of options relevant to managing certificates for WebSphere Application Server programs.

Go to previous article: MakeCertTool Go to next article: Example: test certificates

 

 
Go to previous article: MakeCertTool Go to next article: Example: test certificates