Console tool methods and options

There are console methods available for manually creating certificate signing requests for external signing, as well as methods for creating grid-signed certificates.

The console methods can be called with the following command:

UNIX, Windows, IBM i, and Linux:

java -jar certificates.jar -create...

The jar file certificates.jar is placed in the /tools directory in the grid installation folder.

There are two methods and a number of options available for managing the certificates.

Console methods

Two methods are available in the console mode: create and import. The create command generates certificates or certificate requests. The import command imports a certificate after it has been signed by an external CA.

The create command

UNIX, Windows, IBM i, and Linux:

This command is used to generate certificates or certificate requests. The create method requires a command option which indicates what to create.


Command Option	Description
`gridcert`	The `create=gridcert` command creates a new self-signed grid root certificate/keypair and stores them in the provided grid keystore. If a grid root certificate is generated after the initial installation, it is necessary to regenerate all certificates that were signed by the previous grid root certificate. This includes all host, client, and SSL certificates that were not signed by an external CA. Note that the corresponding grid root password is not stored automatically when using this command. If you wish to create a new password, this must be stored in a file called `gridName`.pw next to the grid root keystore. It is also possible to reuse the existing `gridName`.pw by entering its contents as the -gridpassword argument. Note: This command should only be used when absolutely necessary.
`hostcert`	The `create=hostcert` command creates a new grid-signed host certificate for a grid host to be permitted to participate in a grid, and to communicate with the other hosts in that grid. Host certificates require the grid-admin role. When using this command, the corresponding host keystore password is recreated automatically and stored in server.pw next to server.ks. Note that the symmetric key must also be regenerated when a new host certificate is created. See the `create=symkey` command.
`clientcert`	The `create=clientcert` command creates a new grid-signed client certificate used to authenticate to the grid. This can be used in the scenarios described in ION Grid security overview. The roles provided when creating the certificate influences the permissions the user will have when connecting with that certificate. Note that the corresponding client keystore password is not stored automatically when using this command. If you wish to create a new password, this must be stored in a file called `clientName`.pw next to the client keystore. It is also possible to reuse the existing `clientName`.pw by entering its contents as the -clientpassword argument.
`sslcert`	The `create=sslcert` command creates a new grid-signed SSL certificate to be used by the routers of a specific grid host.
`certreq`	The `create=certreq` command creates a Certificate Signing Request (CSR) for an SSL server certificate. This CSR is then sent to an external Certificate Authority for signing. When the certificate has been signed, it can be imported using the `import=sslcert` command.
`symkey`	The `create=symkey` command is used to generate the secret key a grid host needs in order to decrypt/encrypt grid password properties. Password properties are stored encrypted by the grid. Note that existing password properties will not decrypt correctly if the symmetric key is regenerated. To avoid this, export the properties via the Configuration Manager before regenerating the symmetric key, and then import them back afterwards.

The import command

UNIX, Windows, IBM i, and Linux:

java -jar certificates.jar -import[=<sslcert|sslkey>]

This command is used to import an SSL certificate after it has been signed by an external CA. The same keystore must be specified during the import as when the Certificate Signing Request was generated. The command option indicates whether the private key of the new SSL certificate also should be imported.


Command option	Description
sslcert	Import an externally signed SSL certificate into the existing keystore. The private key that is stored in the https.ks keystore is used. The public key in the certificate must correspond to the private key.
sslkey	Import an externally signed SSL certificate together with the corresponding private key. The existing private key and certificate in the https.ks keystore will be replaced.

Console method options

Most of the following options are used in conjunction with the create command. A <p> after the option name indicates that a value is needed for the option.


Method Option	Description
`-address <p>`	An IP address that this certificate is valid for. Host names will be resolved using java.net.InetAddress.getByName(). May be specified more than once to enable the certificate to be valid for multiple IP addresses.
`-altname <p>`	Alternate fully qualified domain name or the IP address for the host for which this certificate is created. May be specified more than once to enable certificate to be valid for multiple fully qualified domain names.
`-certfile <p>`	The name of a file containing a signed certificate and/or certificates needed to establish a trust chain to the signed certificate. May be specified more than once.
`-clientkeystore <p>`	Path to the directory where keystore file for the client is to be saved.
`-clientname <p>`	Name of the client for which this certificate is created.
`-clientpassword <p>`	Client certificate password.
`-dname <p>`	The X.500 distinguished name to be used in the subject field in the certificate. It should not contain the CN attribute since this is automatically added, derived from the hostfqdn option.
`-from <p>`	Certificate valid from date in YYYYMMDD format (default today).
`-gridkeystore <p>`	Path to the grid keystore directory.
`-gridname <p>`	Name of the grid for which this certificate is created.
`-gridpassword <p>`	Grid certificate password.
`-hostfqdn <p>`	The fully qualified domain name or the IP address for the host for which this certificate is created. Note that if the host FQDN value should be used to identify the server in the SSL handshake, it must be specified as an altname value as well.
`-hostkeystore <p>`	Path to the host keystore directory.
`-hostname <p>`	Name of the host for which this certificate is created.
`-keyalg <p>`	Specifies the algorithm to be used to generate the keypair. The default is `RSA`.
`-keyfile <p>`	The absolute path to the keystore file to import into Grid. Used to import an SSL certificate with the private key.
`-keypassword <p>`	The password for the keystore referred to by the keyfile parameter.
`-keysize <p>`	Specifies the size of each key to be generated. The default is `1024`.
`-keystoretype[=<bks\|jks\|pkcs12>]`	Keystore type for client keystores, optional; default is `jks`.
`-role <p>`	A role attached to this principal. May be specified more than once. Only valid for client certificates.
`-serial <p>`	Certificate serial number, uniquely maintained by the CA.
`-sigalg <p>`	Specifies the algorithm that should be used to sign certificates and CSRs. The default is `SHA256WITHRSA`.
`-sslkeystore <p>`	Path to the SSL keystore directory.
`-symkeypath <p>`	Path to the host secret key directory.
`-to <p>`	Certificate valid to date in YYYYMMDD format (default in 90 days in the future).
`-unresolved`	Modify the meaning of address to not resolve host names.