During development, it is convenient to have a simple way of creating new certificates. OpenSSL includes all of the necessary infrastructure for setting up your own certificate authority (CA), but it requires getting more familiar with OpenSSL than is really necessary. To simplify the process, Ice includes the Python script
iceca, located in the
bin subdirectory of your Ice installation, that hides the complexity of OpenSSL and allows you to quickly perform the essential tasks:
You are not obligated to use this script; IceSSL accepts certificates from any source as long as they are provided in the appropriate formats. However, you may find this tool sufficient for your development needs, and possibly even for your deployed application as well.
Some of the script’s activities use a directory that contains configuration files and a database of issued certificates. The script selects a default location for this directory that depends on your platform, or you can specify the parent directory explicitly by defining the
ICE_CA_HOME environment variable and the script will use
$ICE_CA_HOME/ca for its files.
The script command iceca init initializes a new CA by preparing a database directory and generating the root CA certificate and private key. It accepts the following command-line arguments:
$ python iceca init [‑‑no‑password] [‑‑overwrite]
Upon execution, the script first checks the database directory to determine whether it has already been initialized. If so, the script terminates immediately with a warning unless you specify the
‑‑overwrite option, in which case the script overwrites the previous contents of the directory.
Next, the script displays the database directory it is using and begins to prompt you for the information it needs to generate the root CA certificate and private key. It offers a default choice for the CA’s distinguished name and allows you to change it:
To specify an alternate value for the distinguished name, enter n and type the new information, otherwise hit Enter to proceed.
The script shows its progress as it generates the certificate and private key, then prompts you for a pass phrase. If you prefer not to secure your CA’s private key with a pass phrase, use the
‑‑no‑password option.
The CA is initialized.
You need to distribute the following files to all machines that
can request certificates:
C:\iceca\req.cnf
C:\iceca\ca_cert.pem
These files should be placed in the user's home directory in
~/.iceca. On Windows, place these files in <ice‑install>/config.
In this example, the ICE_CA_HOME environment variable was set to
C:\iceca. As the script states, the files
req.cnf and
ca_cert.pem must be present on each host that can generate a certificate request. The script suggests a location for these files, which is the default directory used by the scripts if
ICE_CA_HOME is not defined.
The ca_cert.pem file contains the root CA’s certificate. Your IceSSL configurations must identify this certificate (in its proper form for each platform) as a trusted certificate. For example, you can use this file directly in the configuration of the C++ plugin:
$ keytool ‑import ‑trustcacerts ‑file ca_cert.pem ‑keystore ca.jks
Enter keystore password:
The script command iceca request uses the files you created in
Section 38.7.1 to generate a request for a new certificate. It accepts the following command-line arguments:
$ python iceca request [‑‑overwrite] [‑‑no‑password]
file common-name [email]
The script looks for the files req.cnf and
ca_cert.pem in the directory defined by the
ICE_CA_HOME environment variable. If that variable is not defined, the script uses a default directory that depends on your platform.
The purpose of the script is to generate two files: a private key and a file containing the certificate request. The request file must be transmitted to the certificate authority for signing, which produces a valid certificate chain.
The argument file is used as a prefix for the names of the two output files created by the script:
•
file_key.pem contains the private key
•
file_req.pem contains the certificate request
If the output files already exist, you must specify ‑‑overwrite to force the script to overwrite them.
The common-name argument defines the common name component of the certificate’s distinguished name. If the optional
email argument is provided, it is also included in the certificate request.
During execution, the script displays its progress as it generates the necessary files. It will prompt you for a pass phrase unless you used the
‑‑no‑password option, and finish by showing the names of the files it created as well as instructions on how to proceed. The example below shows the output from generating a request for an IceGrid node using a filename prefix of
node:
$ iceca request node "IceGrid Node"
Created key: node_key.pem
Created certificate request: node_req.pem
The certificate request must be signed by the CA. Send the
certificate request file to the CA at the following email
address:
ca‑[email protected]
The file node_key.pem is the new private key for the node; this file must be kept secure. The file
node_req.pem must be given to the certificate authority. As a convenience, the script displays the CA’s email address that you entered in
Section 38.7.1.
As a certificate authority, you are responsible for certifying the validity of certificate requests by signing them with your private key. The product of signing a request is a valid certificate chain that a person or application can use as an identity. The
iceca sign command performs this task for you and accepts the following command-line arguments:
$ python iceca sign ‑‑in <req> ‑‑out <cert> [‑‑ip <ip> ‑‑dns <dns>]
The input file req is the certificate request, and the output file
cert is the certificate chain. The script does not overwrite the file
cert unless you also specify
‑‑overwrite. The
‑‑ip and
‑‑dns options allow you to add subject alternative names to the certificate for IP and DNS addresses, respectively.
Continuing the example from Section 38.7.2, we can sign the node’s request with the following command:
$ python iceca sign ‑‑in node_req.pem ‑‑out node_cert.pem
If the CA’s private key is protected by a pass phrase, we must enter that first. Next, the script displays the relevant information from the certificate request and asks you to confirm that you wish to sign the certificate:
The Subject's Distinguished Name is as follows
organizationName :PRINTABLE:'Company.com'
commonName :PRINTABLE:'IceGrid Node TestNode'
Certificate is to be certified until Jun 15 18:32:36 2011 GMT
Sign the certificate? [y/n]:
After reviewing the request, enter y to sign the certificate, and
y again to finish the process. Upon completion, the script stores the certificate chain in the file
node_cert.pem in your current working directory. This file, together with the node’s private key we created in
Section 38.7.2, establishes a secure identity for the node.
For Java and .NET users, the private key and certificate chain must be converted into a suitable format for your platform. The script command
iceca import simplifies this process and accepts the following command-line arguments:
$ python iceca import [‑‑overwrite] [--key-pass password]
[--store-pass password] [‑‑java alias cert key keystore]
[‑‑cs cert key out‑file]
The script does not overwrite an existing file unless you specify ‑‑overwrite. To avoid interactive prompts for passwords, you can use the
--key-pass option to specify the password for the private key, and the
--store-pass option to define the password for the Java keystore. Completing our node example from prior sections, the command below imports the private key and certificate chain into a Java keystore:
$ python iceca import ‑‑java mycert node_cert.pem
node_key.pem cert.jks
The value mycert represents the alias associated with this entry in the keystore, and
cert.jks is the name of the new keystore file. In an IceSSL configuration, the property
IceSSL.Keystore refers to this file.
$ python iceca import ‑‑cs node_cert.pem node_key.pem cert.pfx
The file cert.pfx uses the PKCS#12 encoding and contains the certificate chain and private key. You can import this certificate into a store, or refer directly to the file using the configuration property
IceSSL.CertFile.
If you encounter a problem while using the iceca script, or simply want to learn more about the underlying OpenSSL commands used by the script, you can run the script with the
‑‑verbose option as shown below:
$ python iceca ‑‑verbose command ...
The script creates temporary files and directories that are normally deleted prior to the script’s completion. If you would like to examine the contents of these files and directories, use the
‑‑keep option:
$ python iceca ‑‑keep command ...
