C Security Utilities Command-Line Reference

Oracle CEP provides the following command-line utilities for configuring security:

C.1 The cssconfig Command-Line Utility

Use the cssconfig command-line utility to generate a security configuration file (security.xml) that uses a password policy.

The cssconfig utility is located in the ORACLE_CEP_HOME/ocep_11.1/bin directory, where ORACLE_CEP_HOME is the main Oracle CEP installation directory, such as d:\oracle_cep. The utility comes in two flavors:

  • cssconfig.cmd (Windows)

  • cssconfig.sh (UNIX)

The Unix version of this utility starts with the #!/bin/ksh directive. On most Unix systems, this forces the Korn Shell program to be used when using the utility. If the ksh program is not present in the bin directory or if the shell language used cannot properly execute the utility, run the utility as shown below:

prompt> $PATH_TO_KSH_BIN/ksh -c cssconfig.sh

where PATH_TO_KSH_BIN is the fully qualified path to the ksh program.

C.1.1 cssconfig Syntax

cssconfig -p propertyfile [-c configfile] -i inputkeyfile [-d]

where:

  • propertyfile is a file that contains security configuration properties provided by the user to define the required configuration. This option is required. See Example 9-1 for an example.

  • configfile is the name of the generated file. This property is optional; default value is security.xml.

  • inputkeyfile is the fully qualified name of the input key file used to generate the security configuration file. Set this option to the security-key.dat file in the config directory.

  • -d enables debugging.

C.2 The encryptMSAConfig Command-Line Utility

Use the encryptMSAConfig encryption command-line utility to encrypt cleartext passwords, specified by the <password> element, in XML files. Examples of XML files that can contain the <password> elements include:

  • config.xml

  • security-config.xml

  • Component configuration files

The encryptMSAConfig utility is located in the ORACLE_CEP_HOME/ocep_11.1/bin directory, where ORACLE_CEP_HOME is the main Oracle CEP installation directory, such as d:\oracle_cep. The utility comes in two flavors:

  • encryptMSAConfig.cmd (Windows)

  • encryptMSAConfig.sh (UNIX)

C.2.1 encryptMSAConfig Syntax

encryptMSAConfig directory XML_file msainternal.dat_file

where:

  • directory refers to the directory that contains the XML file which in turn contains a cleartext <password> element.

  • XML_file refers to the name of your XML file.

  • msainternal.dat_file parameter refers to the location of the .msainternal.dat file associated with your domain; this file is located in the ORACLE_CEP_HOME/user_projects/domains/DOMAIN/SERVER directory, where ORACLE_CEP_HOME is the main Oracle CEP installation directory, such as d:\oracle_cep, DOMAIN refers to the domain directory (such as myDomain), and SERVER refers to the server instance (such as myServer).

For example:

prompt> pwd
C:\OracleCEP\user_projects\domains\ocep_domain\defaultserver
prompt> C:\OracleCEP\ocep_11.1\bin\encryptMSAConfig.cmd . config\config.xml .msainternal.dat

After you run the command, the value of the password element in XML_file will be encrypted.

C.3 The GrabCert Command-Line Utility

Use the GrabCert command-line utility to generate a trust keystore that includes the certificate from an existing trust keystore.

The GrabCert utility is located in the ORACLE_CEP_HOME/ocep_11.1/utils/security/wlevsgrabcert.jar file, where ORACLE_CEP_HOME refers to the Oracle CEP installation directory (such as d:/oracle_cep).

C.3.1 GrabCert Syntax

java GrabCert host:secureport [-alias=alias] [-noinput] [truststorepath]

where:

Table C-1 GrabCert Arguments

Option Description Default Value

host

The host name of the Oracle CEP server from which to copy the certificate.

 

secureport

The SSL port on host.

For more information, see Example 9-5 in Section 9.5.1, "How to Configure SSL Manually."

9003

alias

The alias for the certificate in the trust keystore.

host

-noinput

Use the -noinput option to instruct GrabCert to copy all certificates from host.

Omit the -noinput option to instruct GrabCert to list all available certificates from host and prompt you to select one.

 

truststorepath

The full pathname of the generated trust keystore file on host.

evstrust.jks


C.3.2 Examples of Using GrabCert

For example:

prompt> java GrabCert ariel:9003 -alias=ariel evstrust.jks

For other examples, see Section 9.5.3, "How to Configure SSL in a Multi-Server Domain for Oracle CEP Visualizer".

C.4 The passgen Command-Line Utility

Use the passgen command-line utility to hash user passwords for addition to a security database.

Note:

The passgen command line utility has been deprecated as of Version 10.3 of Oracle CEP. This is because the Configuration Wizard automatically performs the required task for you.

The passgen utility is located in the ORACLE_CEP_HOME/ocep_11.1/bin directory, where ORACLE_CEP_HOME is the main Oracle CEP installation directory, such as d:\oracle_cep. The utility comes in two flavors:

  • passgen.cmd (Windows)

  • passgen.sh (UNIX)

C.4.1 passgen Syntax

passgen [-a algorithm] [-s saltsize] [-h] [-?] [password]*

where:

Table C-2 passgen Arguments

Option Description Default Value
-a

algorithm specifies the hash algorithm to use:

  • SHA-1

  • MD2

  • MD5

  • SSHA

  • SHA-256

The actual list of algorithms that can be set depends on the security providers plugged into the JDK.

If not specified, the default is SHA-1.

-s

saltsize is the number of salt characters added to ensure a unique hash string.

If not specified, the default is 4.

-h, -?

Displays command line options and exits.

 
password

If passwords are specified on the command line they shall be hashed and printed out one per line in order from left to right. If no passwords are specified on the command line, then the tool shall prompt for passwords to hash interactively.

 

Note:

Windows operating systems must use the .cmd version of this utility, Unix platforms must use the .sh version.

The Unix version of this utility starts with the #!/bin/ksh directive. On most Unix systems, this forces the Korn Shell program to be used when using the utility. If the ksh program is not present in the bin directory or if the shell language used cannot properly execute the utility, run the utility as shown below:

$PATH_TO_KSH_BIN/ksh -c passgen.sh

where PATH_TO_KSH_BIN is the fully qualified path to the ksh program.

C.4.2 Examples of Using passgen

The following sections provide examples that use the passgen utility:

C.4.2.1 Using passgen interactively

The following is an example of using the passgen utility interactively:

$ passgen
Password ("quit" to end): maltese
{SHA-1}LOtYvfQZj++4rV50AKpAvwMlQjqVd7ge
Password ("quit" to end): falcon
{SHA-1}u7NPQfgkHISr0tZUsmPrPmr3U1LKcAdP
Password ("quit" to end): quit
{SHA-1}2pPo4ViKsoNct3lTDoLeg9gHYZwQ47sV

In this mode, a password is entered and the resulting hashed version of the password is displayed. The hashed version of the password can then be entered into the password field of a security database.

Note:

In example, the passwords are shown to be echoed to the screen for demonstration purposes. In most situations, the password would not be displayed unless your platform does not support invisible passwords.

C.4.2.2 Providing a Password on the Command Line

The following is an example using the passgen utility when providing the passwords to be hashed on the command line:

$ passgen maltese falcon
{SHA-1}g0PNXmJW0OBtp/GkHrhNAhpbjM+capNe
{SHA-1}2ivZnjnKD9fordC1YFkrVGf0DHL6SVP1

When multiple passwords are provided, they are hashed from left to right:

  • {SHA-1}g0PNXmJW0OBtp/GkHrhNAhpbjM+capNe is hashed from maltese

  • {SHA-1}2ivZnjnKD9fordC1YFkrVGf0DHL6SVP1 is hashed from falcon.

C.5 The secgen Command-Line Utility

Use the secgen command-line utility to generate a security key or a security configuration file that uses encrypted passwords.

Caution:

The secgen command line utility has been deprecated as of Version 10.3 of Oracle CEP. This is because the Configuration Wizard automatically performs the required task for you.

Note:

This utility creates a security file that does not use a password policy; if you require a password policy, use the cssconfig command-line utility instead. See Section C.1, "The cssconfig Command-Line Utility."

The secgen utility is located in the ORACLE_CEP_HOME/ocep_11.1/bin directory, where ORACLE_CEP_HOME is the main Oracle CEP installation directory, such as d:\oracle_cep. The utility comes in two flavors:

  • secgen.cmd (Windows)

  • secgen.sh (UNIX)

C.5.1 Generating a File-Based Provider Configuration File

Use the following command line options to generate a file-based security provider configuration file.

secgen -F [-o outputfile] [-i inputkeyfile] [-e] [-P PropertyFilePath]

where:

Table C-3 secgen Arguments for a File-Based Provider Configuration File

Option Description Comments
-F

Generate a file-based security provider file; mutually exclusive with the -k option.

If not present, -k is assumed.

-o

outputfile is the name for the generated file.

Default output file name is security.xml.

-i

inputkeyfile is the fully qualified name of the input key file.

If not present, a default input key file named security-key.dat is expected.

-e

Enables unanimous adjudication during authorization.

 
-P

PropertyFilePath is the fully qualified path to a secgen property file which you can use to customize provider configurations.

See Section C.5.3, "Using the secgen Properties File" for details.

A SecGenTemplate.properties template file is located at ORACLE_CEP_HOME/ocep_11.1/bin where ORACLE_CEP_HOME is the main installation directory of Oracle CEP, such as /oracle_cep.


C.5.2 Generating a Key File

Use the following command line options to generate a security key file.

 secgen [-k] [-o outputfile] 

where:

Table C-4 secgen Arguments for a Key File

Option Description Comments
-k

Generate a key file; mutually exclusive with the -F option.

If not present, -k is assumed.

-o

outputfile is the name for the generated file.

Default output file name is security-key.dat.


C.5.3 Using the secgen Properties File

When running secgen, you can use the -P option to specify a property file to customize provider configurations. A SecGenTemplate.properties template file is located in ORACLE_CEP_HOME/ocep_11.1/bin where ORACLE_CEP_HOME is the main installation directory of Oracle CEP, such as /oracle_cep.

You specify cleartext passwords the property file; however, these passwords will be stored encrypted in the generated configuration file.

The following example shows a property file used for file based provider customization:

#File based provider related
file.atn.file.store.path=myfileatnstore.txt
file.atn.file.store.password=firewall
file.atn.user.password.style=HASHED
file.atn.file.store.encrypted=true
file.atz.file.store.path=filatz
file.atz.file.store.password=firewall
file.rm.file.store.path=filerm
file.rm.file.store.password=firewall
file.cm.file.store.path=filecm
file.cm.file.store.password=firewall

The legal values for file.atn.user.password.style are:

  • HASHED

  • REVERSIBLEENCRYPTED

C.5.4 Examples of Using secgen

The following example shows how to use the secgen utility to generate a key file with the name myKeyFile.dat:

prompt> secgen -k -o myKeyFile.dat

The following example shows how to use the secgen utility to generate a file-based security provider configuration file named myConfigFile.xml which also uses the previously generated key file, myKeyFile.dat, and a properties file named mySecGen.properties:

prompt> secgen -F -i myKeyFile.dat -o myConfigFile.xml -P  c:\msa\myMSAConfig\mySecGen.properties

C.5.5 Limitations of secgen

Windows operating systems must use the .cmd version of this utility, Unix platforms should use the .sh version.

The Unix version of this utility starts with the #!/bin/ksh directive. On most Unix systems, this forces the Korn Shell program to be used when using the utility. If the ksh program is not present in the bin directory or if the shell language used cannot properly execute the utility, run the utility as shown below:

prompt> $PATH_TO_KSH_BIN/ksh -c secgen.sh

where PATH_TO_KSH_BIN is the fully qualified path to the ksh program.