Configure Secure Plus Using the Command Line Interface
This section enables the user to configure Secure Plus using the Command Line Interface.
Start and Set Up the Secure+ CLI
The following sections describe the commands and parameters used to start and set up the command line environment.
Starting the Secure+ CLI
To start the Secure+ CLI:
Procedure
Control the Display of Commands
Set the following parameters to define how error messages are captured:
| Parameter | Definition | Values |
|---|---|---|
| -li | Switch to enable the display of commands to the terminal. | y | n |
| -lo | Switch to enable the display of output and error messages to the terminal. | y | n |
| -le | Switch to enable the display of errors to STDERR. | y | n |
| -e | Switch to tell the Secure+ CLI to exit when the
return code is higher than the specified number. If you do not include this parameter, Secure+ CLI continues to run even after an error has occurred. |
0 | 4 | 8 | 16 |
| -p | The full path of the default Secure+ parameters file directory. The Secure+ parameters file in this directory is opened automatically. | |
| -h | Switch to display the usage of the Secure+ CLl. |
Control Help
The Help command determines what help information is displayed. You can list all Secure+ CLI commands and display help for individual commands.
| Command | Description |
|---|---|
| help | Displays all the Secure+ CLI commands. |
| help <command> | Displays help for the specified command. |
Specify Delimiter Characters
Define the following commands to determine how error messages are captured:
| Command | Definition | Values |
|---|---|---|
| Set begdelim= enddelim= |
Defines beginning and ending character to use to enclose keywords that use blanks and other special characters. | Any character The default value is “ (double quotes). |
Encrypt Passwords to Use with the Secure+ CLI
The Secure+ CLI displays passwords in plain text. If your company security policy mandates that you use encrypted passwords, you can use the Local Connection Utility (LCU) to create an LCU file that contains non-encrypted information used to encrypt the password and the encrypted password. For more information on creating and using LCU files, see Encrypt Passwords for use with CLI.
Maintain the Secure+ Parameters File
The commands in the following table describe how to maintain the Secure+ parameters file from the command line interface.
| Command | Description | Parameter | Values |
|---|---|---|---|
| Init Parmfile | Creates the Secure+ parameters file. Must be initialized before you can define nodes. | localnode=Name of the local node where the Secure+ parameters file will be created. | local node name |
| path=Location where the Secure+ parameters file will be created. | directory location For example, d_dir/ndm/secure+/node |
||
| passphrase=Arbitrary set of characters that encrypts the Secure+ parameters file. | a string at least 32 characters long | ||
| Open Parmfile | Opens a Secure+ parameters file so that you can configure it. | path=Location where the Secure+ parameters file will be created. | directory location For example, d_dir/ndm/secure+/node |
| Close Parmfile | Closes the Secure+ parameters file. After this command is issued, no more updates can be performed on the Secure+ parameters file. | None | None |
| Refresh Parmfile | Refreshes the Secure+ parameters file. This will close the current parameters file and reopen it, bringing in any changes since last opened. | None | None |
| Validate Parmfile | Validates the Secure+ parameters file and ensures that it is a valid file. | None | None |
| Rekey Parmfile | Recreates the Secure+ parameters file if it becomes corrupted. | passphrase=Arbitrary set of characters that encrypts the Secure+ parameters file. | passphrase, up to 32 characters long |
| Sync Netmap | Imports remote node records defined in the IBM Connect:Direct network map. | path=Location and name of the network map file. | location of network map file |
| name=Name of the node in the network map. Use wildcard characters to resync more than one node at a time. | node name or wildcard Wildcard values are: Asterisk (*)—any number of characters. Example: kps.* syncs up all nodes with a name that starts with kps. Question mark (?)—a single character. Example: k?s.* syncs up kas.* and kbs.*. |
Display Information
The following commands are available to display information:
| Command | Description | Parameter |
|---|---|---|
| display info | Displays information about when the Secure+ parameters file was last updated. | None |
| display all | Displays all nodes in the Secure+ parameters file. | None |
| display localnode | Displays the values defined in the .Local node record. | None |
| display remotenode | Displays the values defined in remote node records. | node name or wildcard name—The name of the node to display information about. Use wildcard characters to display information about a group of remote node records. The options are: Asterisk (*)—Indicates any number of characters. For example, kps.* displays all nodes with a name that starts with kps. Question mark (?)—Indicates a single character. For example: k?s.* displays kas.* and kbs.*. |
| display client | Displays the values defined in the .Client node record. | None |
| display seaserver | Displays the values defined in the .SEAServer record. | None |
| display protocols | Displays supported security protocols which should be defined in a comma separated list . Supported protocols are: TLS1.2,TLS1.3 | None |
| display securitymodes | Displays supported security modes for additional security. These modes are: FIPS140-2 | SP800-131A_TRANSITION | SP800-131A_STRICT | SUITE_B-128 | SUITE_B-192 | None |
| display ciphersuites | Displays all supported Cipher Suites for Secure+ which can be defined either as a single cipher suite or in a comma separated list. | None |
Manage PKCS12 Keystore
The commands in the following table describe how to create and maintain the PKCS12 keystore file from the command line interface.
| Command | Description | Parameter | Values |
|---|---|---|---|
| create keystore | Will create a new PKCS12 Key Store file. | File=While a default keystore file is created at installation and can be used, you may need to create a new PKCS12 KeyStore File. | <path to PKCS12 KeyStore file (*.p12)> Default path is in: d_dir/ndm/secure+/certificates/cdkeystore.p12 |
| Passphrase=The password for the new KeyStore file. | A string with a minimum of three characters and a maximum of eighty
characters. *This password must be retained; it will be required to administer the Secure+ KeyStore. |
||
| PopulateRoots=Populate with standard certificate authorities. This will import all standard public CA Root certificates into the new KeyStore file. | y | n | ||
| update keystore | Updates the password used to access the PKCS12 KeyStore | File=Path to existing PKCS12 KeyStore and filename. | <path to PKCS12 KeyStore file (*.p12)> Default path is in: d_dir/ndm/secure+/certificates/cdkeystore.p12 |
| Passphrase=The password for the KeyStore file. | The retained password of the KeyStore. | ||
| import keycert | Imports existing keycerts into the keystore file. | File=Existing key certificate file. *This file contains the private key* |
Full path and filename to key certificate file to be imported. |
| Passphrase=Password of key certificate file to be imported. | Pre-defined password of key certificate file. | ||
| Label=(optional) Name of imported key certificate file. | A string of characters which can be an alias name but if it is not defined, the Common Name of the certificate will be the label used. | ||
| SyncNodes=Update node/certificate references | y | n | ||
| ImportMode=Type of import to be used. | Add | Replace | AddOrReplace | ||
| import trustedcert | Imports public certificate files from trading partners. | File=Trusted public file from trading partner. | Full path and filename to trusted certificate file to be imported. |
| ImportMode=Type of import to be used. | Add | Replace | AddOrReplace | ||
| delete keystoreentry | Deletes certificates from PKCS12 keystore. | File=Can be either key certificate file or trusted public trading partner file. | Full path and filename to certificate file. |
| Label=Specified label of imported certificate file. | Label which was defined at time of import of the certificate file. | ||
| DeleteChain=Defines whether to delete the entire chain, if it exists. | y | n | ||
| SyncNodes=Reset node/certificate references | y | n |
Update the .Local Node Record
The update localnode command configures the protocol for the .Local node record. The command has the following parameters:
| Command | Parameter | Values |
|---|---|---|
| update localnode | protocol=Specifies a comma delimited list of Protocols to use in the .Local node record. | Disable | TLS 1.2,TLS 1.3 (See Display Protocols) |
| SecurityMode | Disable | FIPS140-2 | SP800-131A_TRANSITION | SP800-131A_STRICT |
SUITE_B-128 | SUITE_B-192 (See Display SecurityModes) |
|
| override=Identifies if values in the remote node can override values defined in the .Local node record. | y | n | |
| AuthTimeout=Specifies the maximum time, in seconds, that the system waits to receive the IBM Connect:Direct control blocks exchanged during the IBM Connect:Direct authentication process. | 0–3600 The default is 120 seconds. |
|
| KeyCertLabel=Identifies the label of the key certificate. | keycert label | null Note: If no keycert label is specified, the following
should be noted:
Pnode sessions will fail if the remote node requires client authentication. Snode sessions will fail. |
|
| EncryptData=If no is specified, Encrypt Only Control Block Information; data is sent unencrypted. Default is Yes - data and control block information are encrypted. | y | n | |
| ClientAuth = Enables client authentication in a .Client node record. | y | n | |
| CipherSuites= Specifies the cipher suites
enabled. Note: Only certain cipher suites are supported in FIPS-mode. |
comma delimited list of cipher suites | all | null all—Enables all ciphers. null—Clears any existing values from the node definition. |
|
| SeaEnable=Enables certificate validation by Sterling External Authentication Server | y | n | |
| SeaCertValDef=Character string defined in Sterling External Authentication Server (SEAS). | character string | null null—Clears any existing values from the node definition. |
Manage Remote Node Records
This section contains the commands and parameters used to create, update, display, and delete remote node records.
Create a Remote Node Record
The create remotenode command creates a remote node record and configures the protocol settings. The command has the following parameters:
| Command | Parameter | Values |
|---|---|---|
| create remotenode | model=Name of an existing node to use as a model to copy from. | name of a valid remote node |
| Name=Identifies name of the remote node record. | name | |
| protocol=Specifies a comma delimited list of Protocols to use in the remote node record. | Disable | TLS 1.2,TLS 1.3 |DefaultToLN (See Display Protocols) |
|
| SecurityMode | Disable | FIPS140-2 | SP800-131A_TRANSITION | SP800-131A_STRICT | SUITE_B-128 |
SUITE_B-192 | DefaultToLN
(See Display SecurityModes) |
|
| override=Identifies if values in the copy statement can override values defined in the remote node record. | y | n | DefaultToLN | |
| AuthTimeout=Specifies the maximum time, in seconds, that the system waits to receive the IBM Connect:Direct control blocks exchanged during then Connect:Direct authentication process. | 0–3600 The default is 120 seconds. |
|
| KeyCertLabel=Identifies the label of the key certificate. | keycert label | null | |
| EncryptData=If no is specified, Encrypt Only Control Block Information; data is sent unencrypted. Default is Yes - data and control block information are encrypted. | y | n | DefaulttoLN | |
| ClientAuth = Enables client authentication with a remote trading partner. | y | n | DefaultToLN | |
| CertCommonName=The certificate common name defined in the certificate. | name | null null—Clears any existing values from the node definition. |
|
| CipherSuites= Specifies the cipher suites enabled. | comma delimited list of cipher suites | All | null | |
| SeaCertValDef=Character string defined in Sterling External Authentication Server (SEAS). | character string | null null—Clears any existing values from the node definition. |
Update the Remote Node Record
The update remotenode command creates a remote node record and configures the protocol settings. The command has the following parameters:
| Command | Parameter | Values |
|---|---|---|
| update remotenode | Name=Specifies name for the remote node record. | remote node name | wildcard Use wildcard characters to update a group of remote node records. The options are: Asterisk (*)—Any number of characters. Example: kps.* displays remote nodes with a name that starts with kps. Question mark (?)—Single character. Example: k?s.* displays kas.* and kbs.*. |
| protocol=Specifies a comma delimited list of Protocols to use in the remote node record. | Disable |TLS 1.2,TLS 1.3 | DefaultToLN
(See Display Protocols) |
|
| SecurityMode | Disable | FIPS140-2 | SP800-131A_TRANSITION | SP800-131A_STRICT | SUITE_B-128 | SUITE_B-192 | DefaultToLN | |
| override=Identifies if values in the copy statement can override values defined in the remote node record. | y | n | DefaultToLN | |
| AuthTimeout=Specifies the maximum time, in seconds, that the system waits to receive the Connect:Direct control blocks exchanged during the Connect:Direct authentication process. | 0–3600 The default is 120 seconds. |
|
| KeyCertLabel=Identifies the label of the key certificate. | keycert label | null | |
| EncryptData=If no is specified, Encrypt Only Control Block Information; data is sent unencrypted. Default is Yes - data and control block information are encrypted. | y | n | DefaulttoLN | |
| ClientAuth = Enables client authentication with a remote trading partner. | y | n | DefaultToLN | |
| CertCommonName=The certificate common name defined in the certificate. | name | null null—Clears any existing values from the node definition. |
|
| CipherSuites= Specifies the cipher suites
enabled. Note: Only certain cipher suites are supported in FIPS-mode. |
comma delimited list of cipher suites | All | null | |
| SeaEnable=Enables certificate validation by Sterling External Authentication Server. | y | n | DefaultToLN DefaultToLN—Defaults to the setting specified in the .Local node record |
|
| SeaCertValDef=Character string defined in Sterling External Authentication Server (SEAS). | character string | null null—Clears any existing values from the node definition. |
Display a Remote Node Record
The display remotenode command displays information about one or more remote node records. The command has the following parameter:
| Command | Parameter | Values |
|---|---|---|
| display remotenode | name=Name of the remote node record to display information about. | node name | wildcard value To display information about more than one remote node record, use wildcard characters. Use wildcard characters to display information about a group of remote node records. The options are: Asterisk (*)—Any number of characters. Example: kps.* displays remote nodes with a name that starts with kps. Question mark (?)—A single character. Example: k?s.* displays kas.* and kbs.*. |
Manage Remote Node Records
Create Alias
The create alias command will create an alias record for an existing node record in the Secure+ parmfile. The command has the following parameter:
| Command | Parameter | Value |
|---|---|---|
| create alias | name=The alias name to be used. | An alias name for an existing node name record. Important: Characters
used in Netmap Node Names (or Secure+ Node Names or Secure+ Alias Names) should be restricted to
A-Z, a-z, 0-9 and @ # $ . _ - to ensure that the entries can be properly managed by Control Center, Sterling
Connect:Direct Browser User Interface, or IBM Sterling Connect:Direct Application Interface
for Java™ for
Java (AIJ) programs.
|
| basename=The name of the existing node record. | The existing node name |
Delete a Remote Node Record
The delete remotenode command deletes one or more remote node records. The command has the following parameter:
| Command | Parameter | Values |
|---|---|---|
| delete remotenode | name=Name of the remote node record to display
information about. Use wildcard characters to delete a group of remote node records. |
remote node name | wildcard value To display information about more than one remote node record, use wildcard characters. Use wildcard characters to display information about a group of remote node records. The options are: Asterisk (*)—Any number of characters. Example: kps.* displays remote nodes with a name that starts with kps. Question mark (?)—A single character. Example: k?s.* displays kas.* and kbs.*. |
Update the .Client Node Record
The update client command creates a .Client node record and configures the protocol settings. The command has the following parameters:
| Command | Parameter | Values |
|---|---|---|
| update client | protocol=Specifies a comma delimited list of Protocols to use in the .Client record | Disable | TLS 1.2,TLS 1.3 | DefaultToLN (See Display Protocols) |
| SecurityMode | Disable | FIPS140-2 | SP800-131A_TRANSITION | SP800-131A_STRICT | SUITE_B-128 |
SUITE_B-192 | DefaultToLN
(See Display SecurityModes) |
|
| override=Indicates whether a client will be allowed to override the specified Secure+ protocol. For example, y will allow an unsecure client to connect when a secure protocol is configured. | y | n | DefaultToLN | |
| AuthTimeout=Specifies the maximum time, in seconds, that the system waits to receive the Connect:Direct control blocks exchanged during the Connect:Direct authentication process. | 0–3600 The default is 120 seconds. |
|
| KeyCertLabel=Identifies the label of the key certificate | keycert label | null | |
| EncryptData=If no is specified, Encrypt Only Control Block Information; data is sent unencrypted. Default is Yes - data and control block information are encrypted. | y | n | DefaulttoLN | |
| CipherSuites= Specifies the cipher suites enabled. | comma delimited list of cipher suites | All | null |
Maintain the Sterling External Authentication Server Record
This section contains the commands and parameters used to update and display the .SEAServer record.
Update the Sterling External Authentication Server Record
The update seaserver command configures properties for Sterling External Authentication Server (SEAS) in the .SEAServer record that is created at installation. The command has the following parameters:
| Command | Parameter | Values |
|---|---|---|
| update seaserver | Protocol=Specifies a comma delimited list of Protocols to use in the .SEAServer record. | Disable | TLS1.2,TLS 1.3 DefaultToLN
(See Display Protocols) |
| SeaHost=External authentication host name defined in SEAS. | host name | null null—Clears any existing values from the node definition |
|
| AuthTimeout=Specifies the maximum time, in seconds, that the system waits to receive the Connect:Direct control blocks exchanged during the Connect:Direct authentication process. | 0–3600 The default is 120 seconds. |
|
| SeaPort=External authentication server port number (listening) defined in SEAS. | port number | 61366 | |
| SeaCacheEnable=Enable caching External Authentication Server certificate validation response. | Y|N The default is N. |
|
| SeaCacheValidityTime=Time duration during which the local cache entry is valid for certificates | The default is 24 hours. Range: 1 to 720 hours |
|
| SeaGraceValidityTime=Number of hours when the local cache entry of certificate expires and External Authentication Server is unavailable such that Connect:Direct Secure Plus can accept it from its cache. | The default is 0 hours which means cache grace validity time does not
apply. Range: 0 to 720 hours |
Display the Sterling External Authentication Record
The display SEAServer command displays information about the .SEAServer record. This command has no parameters.
Strong Password Encryption
This section contains the commands and parameters used to update and display the .Password file.
Update the .Password File
The update password command enables or disables Strong Password Encryption. The update goes into effect after you start the IBM Connect:Direct Server. The command has one parameter, SpeEnable, which can be set to Y or N to enable or disable Strong Password Encryption. Following is an example:
| Update Password SpeEnable=<Y> ; |
If you enable or disable Strong Password Encryption, the server displays the following warning:
| SPCG741W=The IBM Connect:Direct Server must be restarted for the changes to Strong Password Encryption to become effective. |
Display the .Password File
The Display Password command displays the Strong Password Encryption setting and .Password history.