Using a list file to specify RSA private keys

Create a text file containing the list of the private keys that are to be used for encryption on the NAM Probe, with each entry containing a reference to a PEM-encoded file or a key stored on the accelerator card.

Before you begin

For the purpose of this procedure, it is assumed that you are using OpenSSL and have the required PEM-encoded keys ready. Key extraction is described in Extracting Web Server Private SSL Keys.

Specifying RSA private keys

Ensure that the NAM Probe is configured to use keys listed in the list file.

Edit the rtm.config configuration file and make sure that the ssl.import.all.keys.from.token configuration property is set to false :

 ssl.import.all.keys.from.token=false

Optional: Specify the directory to store the list file and the PEM-encoded key files.

This directory is, by default, /usr/adlex/config/keys . You do not need to modify this setting unless you want to store the files in a different location. To change the configuration, edit the rtm.config configuration file and modify the server.key.dir configuration property. The following example line shows the default setting:

 server.key.dir=/usr/adlex/config/keys

Optional: Specify the name of the list file.

The default name of the file listing the keys is keylist . You do not need to modify this setting unless you want to use a different file name. To change the configuration, edit the rtm.config configuration file and modify the server.key.list configuration property. The following example line shows the default setting:

 server.key.list=keylist

Note that the file lists the keys to be used, but does not provide a mapping of servers to keys. This is because the NAM Probe is able to match keys to SSL sessions automatically. The advantage of this approach—of not mapping a specific IP address of the server to the private key—is that servers residing behind load balancers can also be monitored, even though the same IP address is then apparently using a number of different SSL private keys.

Optional: Copy all key PEM-encoded key files to the correct directory.

All the PEM-encoded key files—if any are to be used—should be copied to the directory specified in the server.key.dir configuration property.

Figure 1. Copying RSA Key Files
Copying an individual file:

# cp key1.pem /usr/adlex/config/keys/

or all the *.pem files in the current working directory:

# cp *.pem /usr/adlex/config/keys/

Optional: Write keys to the accelerator card.

If an accelerator card is to be used, you may need to write the keys to the card before they can be used for encryption. Keys written to the card are referred to as “tokens”. Using tokens is more secure and therefore is recommended if the accelerator cards supports this option. For more information, see Management of RSA Private Keys on NAM Probe.

The commands used for managing – listing, organizing, and storing – keys on an accelerator card are specific to the card and are described in topics dedicated to individual cards:

Optional: For nCipher cards on a 32-bit platform only, determine the values of the key application names.

These parameters are used only for nCipher keys on 32-bit platforms.

To determine the value of the nCipher application name, use the rocs command provided with your nCipher card. For example:

# cd /opt/nfast/bin
# ./rocs
`rocs' key recovery tool
Useful commands: `help', `help intro', `quit'.
rocs> list keys
  No. Name                     App        Protected by
    1 k1                       simple     module
rocs> exit

In the above example, the name of the application is “simple”.

Optional: Specify the type of identification to be used as id or label.

For engine values of ncipher_pkcs11 and sca6000, the searchKeyBy parameter of the ssl.engine.param property can be set to id or label with the following default values for the respective engines:

ncipher_pkcs11

Default key identification is by label.

sca6000

Default key identification is by key identifier.

Figure 2. Specify the Type of Identification to be Used

 ssl.engine.param=searchKeyBy:id

Determine the values of the key identifiers for keys stored on the accelerator card.

For keys stored in files, it is the name of the PEM-encoded file that contains an RSA private key.

For keys stored on the accelerator card, it is the key identifier as given by the utilities that list keys. For the appropriate engines, distinguish between key identifiers and key labels as specified in Step 7. For CryptoSwift and nCipher SSL cards, the identifier is an 8-digit hexadecimal value. For a NITROX XL FIPS Acceleration Board, the length of the identifier can vary.

The commands used for managing – listing, organizing, and storing – keys on an accelerator card, are specific to the card and are described in topics dedicated to individual cards:

Create the list file.

Use a text editor to create and edit the list file as a plain text file. The file should be located in the directory specified in the server.key.dir configuration property and named as specified in the server.key.list configuration property.

Each line should describe a single key and be composed of the following fields. Note that the square brackets (“[ ]”) imply that the given item is optional, and the brackets themselves should not be included in the actual entry.

key_type, [app_name :]key_identifier [, comment ]

where:

  •   *key_type*  specifies whether the private key is contained in a PEM-encoded file or in a hardware accelerator token:
    

    file

    key_type value file means that the private key is stored in a PEM-encoded file (possibly encrypted).

    token

    key_type value token means that the private key is stored in a hardware accelerator.

  •   *app_name*  is the application name within the nCipher context.
    
Note
  Specify this field only for nCipher cards, as explained in [Step 6](#anchor_task_c4e55597e3284f1091b0e086bad1242c__step_172b53ef2125465b91da823c7de86795), and only in the case of files stored on the accelerator card. For other accelerator cards, or for files stored in PEM-encoded files, leave this field empty and do not include the colon in the syntax.
  •   *key_identifier*  identifies the key:
    
    •      For keys stored in files, it is the name of the PEM-encoded file that contains an RSA private key.
      
    •      For keys stored on the accelerator card, it is the key identifier as given by the utilities that list keys.
      
  •   The *comment*  part is optional.
    

Figure 3. Sample Entries Listing RSA Private Keys

 token,0A0412DC,key for 10.1.1.12 stored in hardware
file,server1.pem,key for 10.1.1.36 on port 443
file,server2.pem,key for 10.1.1.36 on port 444
file,server2.pem,key for 10.1.1.36 on port 445

Optional: Delete PEM files after keys have been loaded into the accelerator.

After the keys have been loaded into the accelerator, it is advised, for security reasons, that the PEM files be deleted.

You can securely delete the source files, by means of the shred command. This is a Linux command that allows secure deletion so that the information stored in the deleted file is not simply un-referenced by the file system but is actually overwritten. This makes it impossible for any disk recovery tool to re-create the deleted file. Use the -fuz options to the shred command to hide the shredding operation by overwriting the file with 0s and to actually delete the file name form the directory listing while overriding any read protection. For example:

 [root@amd-35 keys]# shred -fuz my.pem
Caution:

Secure deletion is not a necessary step. This is a security measure that you can follow if you do not want the un-encrypted file to remain on the system. Remember that this command removes the file without any means of recovering the removed information.

Optional: If using OpenSSL and the kpadmin utility, re-start the kpa daemon and re-run the kpadmin .

After updating the keylist file you need to re-start the kpa daemon and re-run the kpadmin utility. For more information, see Using KPA to make keys available to the NAM Probe process.

Apply the configuration changes.

When the configuration is changed, apply the changes to the NAM Probe. To do so, log on to the NAM Probe as user root and execute the following commands:

# ndstop
# ndstart

This restarts the NAM Probe and applies the configuration changes.

What to do next

If the NAM Probe is connected to a Central Analysis Server installation, then, for SSL decryption to be used for selected servers, add software service definitions for these servers using the NAM Console. Add a software service (named, for example, “SSL decoded”) and specify that the SSL (with decryption) analyzer is to be used for that definition.