The AMD 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 AMD, with each entry containing a reference to a PEM-encoded file or a key stored on the accelerator card.

  • The AMD can read the key names from the accelerator card and use those for a pool of available keys. Note that the AMD 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 AMD 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 AMD 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.

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.

Table 1. 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

Figure 1. 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 AMD 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.

  • No labels