Console tool guide

The grid provides console tools to generate CSRs for an external CA to sign, to create grid-signed certificates, and to import certificates. These certificates are then used in a router for SSL connections to a specific host. To create CSRs and certificates or to import certificates using the console tool, use these methods and options.

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:

java -jar certificates.jar -create[=<gridcert|hostcert|clientcert|sslcert|certreq|symkey>]

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.

NoteThis 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 Grid-provided services.

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.

Example console commands

Creating a grid root certificate

Command to create a new grid root certificate for the Grid called "demoGrid". The key size is set to 2048 bits using the default key algorithm and signature algorithm. The key will be valid from today until the 20th of November 2022. The keystore will be saved in the "ks folder":


-create=gridcert –gridkeystore <ks folder> -gridname demoGrid 
-gridpassword <password> -keysize 2048 –serial <unusedSerialNumber> –to 20221120
Creating a host certificate

Command to create a host certificate for the server demogrid.infor.com. The keystore is saved in the "ks folder". Default key size and algorithms are used.

-create=hostcert -hostfqdn demogrid.infor.com -to YYYYMMDD –hostkeystore 
<ks folder> -hostname demogrid –gridkeystore <ks folder> -gridpassword 
<password> -gridname demoGrid  -serial <unusedSerialNumber> -address <IPAddress> -role grid-admin
Creating an SSL certificate

Command to create an SSL certificate for a server with multiple network interfaces (demogrid.infor.com using IP address 10.10.10.10 and extdemo.infor.com using IP address 172.30.10.10). The keystore is saved in the "ks folder". Default key size and algorithms are used.

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.

-create=sslcert -address 10.10.10.10 -address 172.30.10.10 -altname 
demogrid.infor.com -altname extdemo.infor.com -to YYYYMMDD -sslkeystore 
<ks folder> –gridkeystore <ks folder> -gridpassword <password> 
-gridname demoGrid -hostfqdn <hostFQDN>
Creating a client certificate

Command to create a client certificate for the user "MyID" with the roles "grid-admin" and "other-role". If the YYYYMMDD values were "20130601" and "20150615", the certificate would be valid from June 1st 2013 to June 1st 2015.

-create=clientcert –clientkeystore <ks folder> -clientname MyID 
-clientpassword <password> -from <YYYYMMDD> -to <YYYYMMDD> -role grid-admin 
-role other-role –gridkeystore <ks folder> -gridpassword <password> 
-gridname demoGrid –serial <unusedSerialNumber>
Creating an SSL Certificate Signing Request

Command to create an SSL Certificate Signing Request. The CSR is written to the file <ks folder>/<hostname parameter>.csr.txt. The CSR can then be used in the external CA to get a signed certificate back.

-create=certreq -address 10.10.10.10 -address 172.30.10.10 -altname 
demogrid.infor.com -altname extdemo.infor.com –hostname demogrid -sslkeystore <ks folder> 
-hostfqdn <hostFQDN> –serial <unusedSerialNumber>
Importing an externally signed certificate

Command to import an externally signed certificate. The <ks folder> must be the same path as was used during the create=certreq command.

-import=sslcert -certfile <path to a file containing the signed certificate> -sslkeystore <ks folder>
Importing an externally signed certificate and the private key

Command to import an externally signed certificate and the corresponding private key.

-import=sslkey -keyfile <key file path> -keypassword <key file password> -keystoretype=<pkcs12|bks|jks> -sslkeystore <directory path of https.ks>
Creating a symmetric key

Command to create a new symmetric key used for encryption of password properties. Note that changing the key will make any presently encrypted properties unusable. If the key needs to be changed, first export the properties, then re-import them.


-create=symkey -gridpassword <password> -gridname <gridName> -gridkeystore <ks folder> 
-symkeypath <ks folder> -hostkeystore <ks folder> -hostname <hostName>