Back | Next | Contents 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 web agents and a Cams policy server. Standard PKI algorithms including Blowfish, DES, DESede (triple DES) and AES are available using key sizes of 16, 8, 24 and 16 bytes respectively. Cams includes a utility program and a web application in the Jetty test server 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 with secret keys:

  1. Generate Secret Keys and Parameters
  2. Configure Cams Policy Server Secret Keys
  3. Configure Cams Web Agent Secret Keys
  4. Set Configuration File Permissions

Generate Secret Keys and Parameters

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 from the command line, use:

Linux/UNIX

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

Windows

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

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: AES, Blowfish, DES, DESede (also known as triple DES). If not provided, Blowfish is the default.

AES (Advanced Encryption Standard) was invented by two Belgian cryptographers, Joan Daemen and Vincent Rijmen and was adopted as an encryption standard by the U.S. government in 2002. AES was announced by National Institute of Standards and Technology (NIST) as U.S. FIPS PUB 197 (FIPS 197) in November 26, 2001 after a 5-year standardization process. It uses a 16, 24, or 32 byte key and a 16 byte initialization vector, though Cams supports only the most secure 32 byte key. Performance of AES is excellent compared with DESede.

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 and an 8 byte initialization vector.

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.

-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).
-help This option displays usage information

Table 1 - Cams Secret Key Generator command line arguments.

NOTE: The Jetty test web server that is included with the Cams policy server provides a web application to generate secret keys. To access the web application, start the Jetty test server and browse to:

http://localhost:8080/

Once there, you'll find complete instructions on how to proceed. By default, the Jetty test web server is configured to run without modification. However, if you have changed configuration values for your Cams policy server, you may have to change any associated values found in CAMS_HOME/jetty/etc/cams-webagent.conf.

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 secret key encoded in hexidecimal. The number of bytes in the key depends on the selected algorithm: AES=16, Blowfish=16, DES=8, 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. The number of bytes used depends on the selected algorithm: AES=16, Blowfish=8, DES=8, DESede=8.

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

./secretKeyGen.sh -a Blowfish
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 sample values into your configuration files. Generate your own values and keep them secret!

Configure Cams Policy Server Secret Keys

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

NOTE - If you change your secret key settings while the Cams policy server is running, it can only be gracefully shutdown using the old settings. If your Cams policy 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 policy 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: AES, Blowfish, DES, and DESede (triple DES).
#	AES uses 32 byte encryption key, Blowfish uses a 16 bytes,
#   DES uses an 8 bytes, and DESede uses 24 bytes.
#
# 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 16 byte (32 hex digit) value.
#   The number of IV bytes used by algorithm are: AES=16, Blowfish=8,
#   DES=8, DESede=8
#
# 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 policy server's 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 policy 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 policy server configuration file, which contains the shutdown password and secret key values used to encrypt the password before sending it to the Cams policy server. If the Cams policy 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 policy server will be expecting the shutdown password to be encrypted with the old secret key.

To avoid this situation, you can:

  1. Gracefully shutdown the Cams policy server before modifying secret key values
  2. 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: AES, Blowfish, DES, and DESede (triple DES).
#	AES uses a 24 byte encryptioin key, 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 16 byte (32 hex digit) value.
#   The number of IV bytes used by algorithm are: AES=16, Blowfish=8,
#   DES=8, DESede=8
#
cams.skey.algorithm=AES
cams.skey.key=7b6d0b4d440bf950ec2abb10db9ae77a144aacfe67aa6ad37e193e8fc9b79656
cams.skey.iv=b84e28464920a0bf959ca4c5675044bc


#
# Remove these old values after the Cams policy server is gracefully shutdown
#

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


...

Example 3 - Renaming the Cams policy server secret Key parameters to old values

Configure Cams Web Agent Secret Keys

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

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

...


#
#--- Cams Connection Authentication properties
#
# connection.authentication.type
# The type of authentication the Cams Web Agent will use to authenticate
# connections that it establishes with the Cams Policy Server.
#
# connection.authentication.principal
# The principal the Cams Web Agent will use to authenticate connections
# it establishes with the Cams Policy Server.
#
# connection.authentication.credential
# The credential the Cams Web Agent will use to authenticate connections
# it establishes with the Cams Policy Server.
#
# connection.authentication.timeout
# The maximum time (in seconds) that the Cams Web Agent will wait for a
# response from the Cams Policy Server.
# cams.client.class=\ com.cafesoft.security.common.client.StandardCamsClient cams.client.authentication.type=EncryptedParameters cams.client.authentication.principal=cams-web-agent cams.client.authentication.credential=password cams.client.authentication.timeout=5 ...

Example 4 - Typical configuration of a Cams web agent to use encrypted authentication

Set 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 policy server or web agent and should have read/write permission only for that user.

Back | Next | Contents

© Copyright 1996-2012 Cafésoft LLC. All rights reserved.