Cams Administrator's Guide

Securing Cams Communications using Secret Keys

Cams may be configured to use a secret key to encrypt and decrypt sensitive values (like authentication credentials) sent between Cams agents and a Cams server. Standard PKI algorithms: Blowfish, DES, and DESede (triple DES) are available using key sizes of 16, 8, and 24 bytes respectively. Cams includes a utility program for generating site-wide secret key parameters. In addition, steps should be taken to secure the file containing the secret key to keep its value out of the hands of would be hackers.

In summary, the following steps are required to secure a Cams environment using a secret key:

Generate a secret key and associated parameters
Configure the Cams Server with the secret key parameters
Configure Cams Agents with the secret key parameters
Set Configuration File Permissions

Generating a Cams Secret Key

The Cams secret key generator can be launched using scripts available in the CAMS_HOME/bin directory (Use: secretKeyGen.bat for Windows and secretKeyGen.sh for Unix).

To generate a Cams secret key, use command:

Linux/UNIX

$CAMS_HOME/bin/secretKeyGen.sh [-a algorithm] [-out file] [-debug]

Windows

%CAMS_HOME%\bin\secretKeyGen.bat [-a algorithm] [-out file] [-debug]

All command line arguments are optional and may have the values shown in Table 1.

Option	Description
-a	This option specifies one of the secret key algorithms: Blowfish, DES, DESede (also known as triple DES), or None. If not provided, Blowfish is the default. Blowfish was invented by Bruce Schneier of Applied Cryptography and is widely accepted as a secure and fast encryption/decryption algorithm. It uses a 16 byte key. DES was invented at RSA and uses a 7 byte (56 bit) key. It is not considered secure due to its key length, which can be cracked using easily available modern computing power. DESede is the "triple DES" algorithm invented by RSA, which uses a 24 byte key to encrypt, decrypt, then encrypt again: using different 8 byte keys for each of the three operations. This algorithm is considered secure, but has serious performance issues compared with Blowfish, which is preferred base on its relative performance and security. None indicates that secret key encryption/decryption should be disabled. WARNING - This mode should be avoided in production environments unless used in conjunction with other security measures (like SSL connectivity between agents and the Cams server).
-out	This option enables output to be written to a specified file. If not provided, output is written to stdout (System.out), which can easily be redirected to file if desired.
-debug	This option turns on debugging, which writes [DEBUG] messages to stderr (System.err).

Option

Description

-a

This option specifies one of the secret key algorithms: Blowfish, DES, DESede (also known as triple DES), or None. If not provided, Blowfish is the default.

Blowfish was invented by Bruce Schneier of Applied Cryptography and is widely accepted as a secure and fast encryption/decryption algorithm. It uses a 16 byte key.

DES was invented at RSA and uses a 7 byte (56 bit) key. It is not considered secure due to its key length, which can be cracked using easily available modern computing power.

DESede is the "triple DES" algorithm invented by RSA, which uses a 24 byte key to encrypt, decrypt, then encrypt again: using different 8 byte keys for each of the three operations. This algorithm is considered secure, but has serious performance issues compared with Blowfish, which is preferred base on its relative performance and security.

None indicates that secret key encryption/decryption should be disabled. WARNING - This mode should be avoided in production environments unless used in conjunction with other security measures (like SSL connectivity between agents and the Cams server).

-out

This option enables output to be written to a specified file. If not provided, output is written to stdout (System.out), which can easily be redirected to file if desired.

-debug

This option turns on debugging, which writes [DEBUG] messages to stderr (System.err).

Table 1 - Cams Secret Key Generator command line arguments.

Secret Key Parameters

The Cams secret key generator writes three parameters to stdout or the specified file:

cams.skey.algorithm - the selected encryption/decryption algorithm
cams.skey.key - a 24 byte secret key encoded in hexidecimal. The number of bytes used for encryption/decryption depend on the selected algorithm: Blowfish=16, DES=7, DESede=24
cams.skey.iv - an initialization vector, which wards against dictionary attacks by scrambling the first few bytes of encrypted values. Without an initialization vector, hackers can sometimes see similar starting patterns at the beginning of different encrypted values, making them more susceptible to cracking.

Example 1 shows sample output using the Cams secret key generator without any options specified

./secretKeyGen.sh
cams.skey.algorithm=Blowfish
cams.skey.key=ed28f2c7b60e978277d125d774bd25c1cad3c5c1a7f02757
cams.skey.iv=1a5dce1235fd429e

Example 1 - Sample Cams Secret Key Parameters generated from a Unix shell script

WARNING - Don't copy and paste these values into your configuration files. Generate your own values and keep them secret!

Configuring a Cams Server Secret Key

Cams server secret key parameters are stored in file: CAMS_HOME/conf/cams.conf.

NOTE - If you change your secret key settings while the Cams server is running, it can only be gracefully shutdown using the old settings. If your Cams server is currently running, you should either gracefully shutdown before reconfiguring cams.conf or decide to copy the current secret key parameters so the Cams server can be gracefully shutdown after modifications. See: Keeping Old Secret Key Parameters for Future Graceful Shutdowns for more details.

To change the secret key configuration settings, simply insert or update the cams.skey.* parameters in cams.conf as shown in Example 2.

...


# Encryption/Decryption Cipher properties:
#
# cams.skey.algorithm - the algorithm to be used when encrypting
#	and decrypting selected values sent to/received from the Cams agents.
#	Valid values include: None, Blowfish, DES, and DESede (triple DES).
#	If None, then selective encryption is disabled. Blowfish uses a 16
#	byte encryption key, DES uses an 8 byte key, and DESede
#	uses a 24 byte key.
#
# cams.skey.key - the secret encryption/decryption key in
#	hexidecimal format. The actual number of bytes used depends on the
#	algorithm, although it is legal to supply more key bytes than needed.
#
# cams.skey.iv - the encryption/decryption initialization vector
#	in hexidecimal format. This should be an 8 byte (16 hex digit) value.
#
# NOTE: Use ${cams.home}/bin/camsSecretKeyGen.bat or camsSecretKeyGen.sh
#	to generate these values.
#
cams.skey.algorithm=Blowfish
cams.skey.key=ed28f2c7b60e978277d125d774bd25c1cad3c5c1a7f02757
cams.skey.iv=1a5dce1235fd429e


...

Example 2 - Configuring Cams Server Secret Key Parameters

WARNING - Don't copy and paste these values into your configuration files. Generate your own values and keep them secret!

Keeping Old Secret Key Parameters for Future Graceful Shutdowns

Graceful shutdown of the Cams server is generally initiated using one of the scripts CAMS_HOME/bin/shutdown.bat (Windows) or CAMS_HOME/bin/shutdown.sh (Linux). The shutdown client executed by these scripts reads the Cams server configuration file, which contains the shutdown password and secret key values used to encrypt the password before sending it to the Cams server. If the Cams server is running while you change secret key configuration values, then later when you invoke the shutdown client it will encrypt the shutdown password using the new secret key. The Cams server will be expecting the shutdown password to be encrypted with the old secret key.

To avoid this situation, you can:

Gracefully shutdown the Cams server before modifying secret key values
Keep the old secret key parameters in CAMS_HOME/conf/cams.conf by appending ".old" to property names

The third solution is simple. When editing cams.conf, simply rename the secret key properties as follows:

cams.skey.algorithm to cams.skey.algorithm.old
cams.skey.key to cams.skey.key.old
cams.skey.iv to cams.skey.iv.old

If the shutdown client fails when using the primary secret key parameters, it will look for the "old" secret key parameters and try again.

...


# Encryption/Decryption Cipher properties:
#
# cams.skey.algorithm - the algorithm to be used when encrypting
#	and decrypting selected values sent to/received from the Cams agents.
#	Valid values include: None, Blowfish, DES, and DESede (triple DES).
#	If None, then selective encryption is disabled. Blowfish uses a 16
#	byte encryption key, DES uses an 8 byte key, and DESede
#	uses a 24 byte key.
#
# cams.skey.key - the secret encryption/decryption key in
#	hexidecimal format. The actual number of bytes used depends on the
#	algorithm, although it is legal to supply more key bytes than needed.
#
# cams.skey.iv - the encryption/decryption initialization vector
#	in hexidecimal format. This should be an 8 byte (16 hex digit) value.
#
# NOTE: Use ${cams.home}/bin/camsSecretKeyGen.bat or camsSecretKeyGen.sh
#	to generate these values.
#
cams.skey.algorithm=DESede
cams.skey.key=d774bd25c1cad3c5c1a7f02757ed28f2c7b60e978277d125
cams.skey.iv=35fd429e1a5dce12


#
# Remove these old values after Cams Server is gracefully shutdown
#

cams.skey.algorithm.old=Blowfish
cams.skey.key.old=ed28f2c7b60e978277d125d774bd25c1cad3c5c1a7f02757
cams.skey.iv.old=1a5dce1235fd429e


...

Example 3 - Renaming Cams Server Secret Key Parameters to "old" values

Configuring a Cams Agent Secret Key

Cafésoft-supplied Cams agents use the same configuration file format and secret key parameters. Simply edit the agent's configuration file using the same values configured under the Cams server, then start or restart the agent.

In addition, agents have numerous ways to authenticate with a Cams server. When a secret key is configured, using the EncryptedUsernamePassword authentication type will ensure that sensitive credentials are encrypted before being sent from an agent to the Cams server. Example 4 shows how a typical agent configuration file configures use of the EncryptedUsernamePassword authentication type.

...


#
#---	Configure general CamsClient parameters
#
# cams.client.authentication.type
#	The type of authentication the web agent will use to authenticate
#	connections that it establishes with the Cams server. Options
#	include: UsernamePassword and EncryptedUsernamePassword. The
#	encrypted version requires use of a secret key (See: cams.skey.*
#	configuration properties).
#
# cams.client.authentication.principal
#	The principal the web agent will use to authenticate connections
# it establishes with the Cams server.
#
# cams.client.authentication.credential
#	The credential the web agent will use to authenticate connections
#	it establishes with the Cams server.
#
# cams.client.authentication.timeout
#	The maximum time (in seconds) that the web agent will wait for a
# response from the Cams server.
#
cams.client.class=\
   com.cafesoft.security.common.client.StandardCamsClient
cams.client.authentication.type=EncryptedUsernamePassword
cams.client.authentication.principal=my-agent-username
cams.client.authentication.credential=my-agent-password
cams.client.authentication.timeout=10

...

Example 4 - Typical configuration of an agent to use encrypted authentication

Setting Configuration File Permissions

When using secret keys, it is important to set permissions on configuration files to keep their contents from would-be hackers. Specific information on setting Cams file permissions is available in Hardening Cams Security: Securing Cams Files and Directories. In summary, all configuration files and the directories containing them should be owned by the operating system user identity that runs the Cams server or agent and should have read/write permission only for that user. All other users and groups should have read, write, and execute permissions.

Back | Next | Contents