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:
- initializing a new root CA
- generating new certificate requests
- signing certificate requests to create a valid certificate chain
- converting certificates to match platform-specific requirements.
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.
On this page:
Initializing a Certificate Authority
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:
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 address you provide in response to this prompt is shown to users that create certificate requests. Enter the address to which such requests should be sent.
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 when starting the script.
Upon completion, the script emits the following instructions:
In this example, the
ICE_CA_HOME environment variable was set to
C:\iceca. As the script states, the files
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.
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++ plug-in:
For .NET applications, you should import the certificate file into the proper store.
In Java, you need to add the certificate to your truststore:
The keytool program requires you to enter a password, which you could use as the value of the property
Now that your certificate authority is initialized, you can begin generating certificate requests.
Generating Certificate Requests
The script command
iceca request uses the files you created while initializing the CA to generate a request for a new certificate. It accepts the following command-line arguments:
The script looks for the files
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.
file is used as a prefix for the names of the two output files created by the script:
_key.pemcontains the private key
_req.pemcontains the certificate request
If the output files already exist, you must specify
--overwrite to force the script to overwrite them.
common-name argument defines the common name component of the certificate's distinguished name. If the optional
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_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 during initialization.
Signing Certificate Requests
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:
The input file
req is the certificate request, and the output file
cert is the resulting certificate chain. The script does not overwrite the file
cert unless you also specify
--dns options allow you to add subject alternative names to the certificate for IP and DNS addresses, respectively.
Continuing our previous example, we can sign the node's request with the following command:
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:
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 when generating the request, 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:
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:
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.
The equivalent command for .NET is shown below:
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
Certificate Authority Diagnostics
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:
This option causes the script to display the commands as it executes them.
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