IBM Tivoli Netcool/OMNIbus, Version 7.4

nc_gskcmd command-line options

The nc_gskcmd command-line utility provides more functions than the iKeyman GUI.

To manage certificates from the command line, run the following command:

$NCHOME/bin/nc_gskcmd object action options

In this command:

object is a command-line option that indicates that an action is required on an object, typically a key database, certificate, or certificate request. This option must be the first command-line option specified.
action is a command-line option that defines a specific action to be taken on the object. This option must be the second command-line option specified.
options are mandatory and optional command-line options that are valid for the specified object and action pair. These command-line options can be in any order.

Note: Not all actions and their associated options are applicable for use in Tivoli Netcool/OMNIbus.

For more information about the usage of these command-line options, see the IBM® Global Security Kit Secure Sockets Layer Introduction and iKeyman User's Guide.

The following table lists each object and its associated set of actions for the nc_gskcmd command.

Table 1. Objects and corresponding actions for nc_gskcmd
Object	Action	Description
-keydb	-changepw	Changes the password for a key database.
	-convert	Converts the format of the key database.
	-create	Creates a key database.
	-delete	Deletes the key database.
	-expiry	Displays the expiry date of the password for a key database.
	-list	Displays the supported types of key database.
	-stash	Stashes the password of a key database into a file.
-cert	-add	Adds a CA certificate from a file into a key database.
	-create	Creates a self-signed certificate.
	-delete	Deletes a certificate.
	-details	Shows the details of a specific certificate.
	-export	Exports a personal certificate and its associated private key from a key database into a PKCS#12 file or another key database.
	-extract	Extracts a certificate from a key database.
	-getdefault	Shows the default personal certificate.
	-import	Imports a certificate from a key database or a PKCS#12 file.
	-list `string`	Lists the certificates in the key database. The values are all, personal, CA, and site. The default is to list all certificates. Specifying -list on its own also lists all certificates.
	-modify	Modifies a certificate. Note: Currently, the only field that can be modified is the Certificate Trust field.
	-receive	Receives a certificate from a file into a key database.
	-setdefault	Sets a personal certificate as the default certificate.
	-sign	Signs a certificate that is stored in a file with a certificate that is stored in a key database, and then stores the resulting signed certificate in a file.
-certreq	-create	Creates a certificate request.
	-delete	Deletes a certificate request from a certificate request database.
	-details	Shows the details of a specific certificate request.
	-extract	Extracts a certificate request from a certificate request database into a file.
	-list	Lists all certificate requests in the certificate request database.
	-recreate	Re-creates a certificate request.
-help		Displays help information for the nc_gskcmd command.
-version		Displays version information about the nc_gskcmd command and exits.

The following table lists the options that are valid for the specified object and action pair.

Table 2. Options for object and action pairs
Option	Description
-ca TRUE \| FALSE	Adds the Basic Constraint extension to the self-signed certificate. Note: Do not create self-signed certificates with -ca set to false.
-crypto `string`	Indicates a PKCS#11 cryptographic device operation.
-db `string`	Specifies the fully qualified path name of a key database.
-default_cert YES \| NO	Sets a certificate as the default certificate to be used for client authentication. The default is no.
-dn `string`	Specifies the X.500 distinguished name. Enter the value as a quoted string in the following format: "CN=`common_name`,O=`organization`,OU=`organization_unit`, L=`location`,ST=`state_province`,ZIP=`postal_code`,C=`country`" For example: "CN=Jane Doe,O=IBM,OU=Java Development,L=Endicott,ST=NY,ZIP=13760,C=country" Only CN is mandatory.
-encryption `string`	Specifies the strength of encryption that is used in the certificate export command. The value can be strong or weak. The default is strong.
-expire `integer`	Specifies the expiration time of either a certificate or a key database password (in days). The duration is 0 to 7300 (that is 20 years). The default is 60 days for a key database password. An expiry of 0 means that the password associated with the key database does not expire. For a self-signed certificate, specify a range from 366 to 7300.
-file `string`	Specifies the file name of a certificate or a certificate request (depending on specified `object`).
-format `string`	Specifies the format of a certificate. The value can be either ascii for Base64_encoded ASCII, or binary for binary DER data. The default is ascii.
-label `string`	Specifies the descriptive text that is used to identify a certificate or a certificate request in the key database. Tip: To help identify the certificate as self signed within the iKeyman GUI, append the words `Certification Authority` or `CA` to the label text.
-new_format `string`	Specifies a new format for the key database.
-new_label `string`	Specifies a new certificate label or alias to replace an existing label.
-new_pw `string`	Specifies a new key database password.
-old_format `string`	Specifies the old format of the key database.
-pfx	Interprets a PKCS#12 file as a Microsoft .pfx file.
-pw `string`	Specifies the password for the key database or PKCS#12 file. In FIPS 140-2 mode, passwords for key databases must meet the following requirements. If passwords do not meet these requirements, the key database is created, but you are unable to create, sign, or receive certificates and an error is written to the ObjectServer log. The minimum password length is 14 characters. A password must have at least one lower case character, one upper case character, and one digit or special character. Each character must not occur more than three times in a password. No more than two consecutive characters of the password can be identical. All characters are in the standard ASCII printable character set within the range from 0x20 to 0x7E inclusive.
-size `integer`	Specifies the key size. The values are 512, 1024, and 2048. The default is 1024.
-stash	Stashes the key database password to a `key_database_name`.sth file in the same location as the key database file.
-san_dnsname	Adds one or more DNS names to the Subject Alternate Name attribute. Must be in "preferred name syntax" according to RFC 1034.
-san_emailaddr	Adds one or more email addresses to the Subject Alternate Name attribute. Must be an "addr-spec" as defined in RFC 822.
-san_ipaddr	Adds one or more IP addresses to the Subject Alternate Name attribute. Must be a string according to RFC 1338 and RFC 1519.
-secondaryDB	Specifies secondary key database support for PKCS#11 device operations.
-secondaryDBpw	Specifies the password for the secondary key database for PKCS#11 device operations.
-showOID	Displays the entire certificate or certificate request.
-sig_alg	Specifies the signing algorithm used during the creation of self-signed certificates. This algorithm is used to create the signature associated with the new self-signed certificate. The generated key type is chosen to match this signing algorithm.
-target `string`	Specifies the destination file or key database into which a certificate is being exported or imported.
-target_pw `string`	Specifies the password for the key database if -target specifies a key database.
-target_type `string`	Specifies a type for the database that is specified by the -target command-line option. The allowable value for Tivoli Netcool/OMNIbus is cms, which specifies a CMS key database.
-tokenlabel `string`	Specifies a label for a PKCS#11 cryptographic device.
-trust `string`	Specifies the trust status of a CA certificate. The value can be enable or disable. The default is enable.
-type `string`	Specifies the type of database. The allowable value for Tivoli Netcool/OMNIbus is cms, which indicates a CMS key database.
-usereasoncode	Returns a multi-valued error code if the nc_gskcmd command fails, or 0 if it is successful.
-x509version `integer`	Specifies the version of X.509 certificate to create. The values are 1, 2 and 3. The default is 3.