Useful XWS-Security Command-Line Tools

In this release, the following command-line tools are included. These tools provide specialized utilities for keystore management or for specifying security configuration files:

pkcs12import

The pkcs12import command allows Public-Key Cryptography Standards version 12 (PKCS-12) files (sometimes referred to as PFX files) to be imported into a keystore, typically a keystore of type Java KeyStore (JKS).

When would you want to do this? One example would be a situation where you want to obtain a new certificate from a certificate authority. In this scenario, one option is to follow this sequence of steps:

Another option is to let the certificate authority generate a key-pair. The authority would return a generated certificate signed by itself along with the corresponding private key. One way the certificate authority can return this information is to bundle the key and the certificate in a PKCS-12 formatted file (generally .pfx extension files). The information in the PKCS-12 file would be encrypted using a password that would be conveyed to the user by the authority. After receiving the PKCS-12 formatted file, you would import this key-pair (certificate/private-key pair) into your private keystore using the pkcs12import tool. The result of the import is that the private-key and the corresponding certificate in the PKCS-12 file are stored as a key entry inside the keystore, associated with some alias.

The pkcs12import tool can be found in the directory <JWSDP_HOME>/xws-security/bin, and can be run from the command line by executing pkcs12import.sh (on Unix systems) or pkcs12import.bat (on Windows systems). The options for this tool listed in Table 3-25.

Table 3-25 Options for pkcs12import tool
Option	Description
`-file` `pkcs12-file`	Required. The location of the PKCS-12 file to be imported.
`[ -pass` `pkcs12-password` `]`	The password used to protect the PKCS-12 file. The user is prompted for this password if this option is omitted.
`[ -keystore` `keystore-file` `]`	Location of the keystore file into which to import the contents of the PKCS-12 file. If no value is given, defaults to `${user-home}/.keystore`.
`[ -storepass` `store-password` `]`	The password of the keystore. User is prompted for the password of the truststore if this option is omitted.
`[ -keypass` `key-password` `]`	The password to be used to protect the private key inside the keystore. The user is prompted for this password if this option is omitted.
`[ -alias` `alias` `]`	The alias to be used to store the key entry (private key and the certificate) inside the keystore.

keyexport

This tool is used to export a private key in a keystore (typically of type Java Keystore (JKS)) into a file.

Note: The exported private key is not secured with a password, so it should be handled carefully. For example, you can export a private key from a keystore and use it to sign certificate requests obtained through any means using other key/certificate management tools. These certificate requests are then sent to a certificate authority for validation and certificate generation.

The keyexport tool can be found in the directory <JWSDP_HOME>/xws-security/bin/, and can be run from the command line by executing keyexport.sh (on Unix systems) or keyexport.bat (on Windows systems). The options for this tool are listed in Table 3-26.

Table 3-26 Options for keyexport tool
Option	Description
`-keyfile` `key-file`	Required. The location of the file to which the private key will be exported.
`[ -outform` `output-format` `]`	This specifies the output format. The options are DER and PEM. The DER format is the DER encoding (binary format) of the certificate. The PEM format is the base64-encoding of the DER encoding with header and footer lines added.
`[ -keystore` `keystore-file` `]`	Location of the keystore file containing the key. If no value is given, this option defaults to `${user-home}/.keystore`.
`[ -storepass` `store-password` `]`	Password of the keystore. User is prompted for the password if this option is omitted.
`[ -keypass` `key-password` `]`	The password used to protect the private key inside the keystore. User is prompted for the password if this option is omitted.
`[ -alias` `alias` `]`	The alias of the key entry inside the keystore.

wscompile

The wscompile tool generates the client stubs and server-side ties for the service definition interface that represents the Web service interface. Additionally, it generates the WSDL description of the Web service interface which is then used to generate the implementation artifacts.

XWS-Security has been integrated into JAX-RPC through the use of security configuration files. The code for performing the security operations on the client and server is generated by supplying the configuration files to the JAX-RPC wscompile tool. The wscompile tool can be instructed to generate security code by making us of the -security option to specify the location of the security configuration file that contains information on how to secure the messages to be sent. An example of using the -security option with wscompile is shown in How Do I Specify the Security Configuration for the Build Files?.