Management of RSA private keys on NAM Probe

Overview

The NAM Probe supports two mutually exclusive modes of using RSA private keys.

  • A list of the private keys that are to be used for encryption can be contained in a text file on the NAM Probe, with each entry containing a reference to a PEM-encoded file or a key stored on the accelerator card.
  • The NAM Probe can read the key names from the accelerator card and use those for a pool of available keys. Note that the NAM Probe does not extract the actual key from the accelerator card.

These two mutually exclusive modes of operation are governed by the following configuration properties in the rtm.config configuration file:

server.key.dir

The directory in which to store PEM-encoded key files (by default, this is /usr/adlex/config/keys).

server.key.list

The file in the above directory that describes what keys are to be used for the monitored servers. The default name of the file is keylist . Note that the file lists 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.

ssl.import.all.keys.from.token

Mode selector:

  • Setting this configuration property to true overrides the settings specified in server.key.list and makes the NAM Probe import the list of available key names from the accelerator card.
    This is supported only for ssl.engine settings of nitroxfips, sca6000, or ncipher_pkcs11 . For more information on setting ssl.engine, see Selecting and configuring SSL engine.
  • Setting this property to false enables key resolution based on the information provided by the server.key.dir and server.key.list configuration properties.

File contents

The file listing the keys, as specified in server.key.list, is a plain-text file with each line describing a single key and being composed of the following fields. Note that the square brackets (“[ ]”) imply that the given item is optional and that the brackets themselves should not be included in the actual entry. Note also that this file may also be used by other protocols, so entries of other types may also appear there.

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. The value of this parameter depends on, among other things, the method used for writing the key to the card. For example, if the following method is used:
 ./generatekey --import simple pemreadfile=/usr/adlex/config/keys/s1.key protect=module ident=s1

the application name is “simple” and the syntax of the entries in the list is: token, simple:*key_identifier* [*, comment* ]

To determine the value you need to enter for each key on the card, 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

For other accelerator cards, 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. Note that some engines distinguish between key identifiers and key labels. Both of these identification methods can be used in the keylist file. However, you may need to specify the type of identification used, by setting the searchKeyBy parameter of the ssl.engine.param property to id or label, as appropriate. See Selecting and configuring SSL engine for more information on configuring this option. For 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 comment part in square brackets “[ ]” is an optional comment describing the entry in the line.

RSA key handling methods

The following table lists the possible RSA key handling methods for the supported SSL engines.

SSL Engine Entry of Type “file” in keylist Entry of Type “token” in keylist Can Import All Keys from Token
openssl YES
nfast YES
nshield YES YES
ncipher_pkcs11 YES YES
nitrox YES YES
sca6000 YES YES

Sample Entries with 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

If the NAM Probe is connected to a CAS installation, then, for SSL decryption to be used for selected servers, add the service definitions for these servers using the report server graphical user interface, Monitoring Configuration. Add an application named, for example, “SSL decoded” and specify that the SSL (with decryption) analyzer is to be used for that application.