The following tips are related to SSL decryption.

1. How to install, configure and add SSL keys to the nCipher nShield SSL card on the AMD.

Installing the AMD software

  1. Copy the file upgrade-amd_ncipher-<OS version>-<AMD version>.bin to the AMD. The correct file name depends on your OS and AMD versions.
  2. Log in to the AMD as root and go to the directory where you copied the above file.
  3. Run the command chmod a+x upgrade-amd_ncipher-<OS version>-<AMD version>.bin to make the file executable.
  4. Run the command /upgrade-amd_ncipher-<OS version>-<AMD version>.bin to install the AMD software with nCipher SSL card support.
  5. Edit the rtm.config file and update the ssl.engine property to reflect ssl.engine=nshield.
  6. The installation will shut down the AMD services, so run the command ndstart to start them all back up.

Configuring the nShield SSL card

  1. Log in to the AMD as root.
  2. Set the module switch on the back panel of the nShield card to the I position (pre-initialization mode).
  3. Run the command cd /opt/nfast/bin/ to go to the directory containing all the nShield executables.
  4. Run the command ./nopclearfail ca to clear the nShield module.
  5. Run the command ./new-world -m 1 -s 0 -Q 1/1 -k rijndael to create the security world.
  6. Insert a blank smart card into the Smart card connector on the back panel of the nShield, then press Enter.
  7. When prompted by the new-world utility, type a pass phrase for the Administrator Card, then press Enter.
  8. When prompted by the new-world utility, confirm the pass phrase. The utility should display a message saying that the security world has been generated.
  9. Remove the smart card and set the module switch on the back panel of the nShield to the O position (operational mode).
  10. Run the command ./nopclearfail ca to clear the nShield module.
  11. Run the command ./nfkminfo to check the status of the security world. The World and Module should show Usable in the state field.

Adding SSL keys to the nShield card

  1. Run the command cd /opt/nfast/bin/ to go to the directory containing all the nShield executables.
  2. Run the below command to add your PEM formatted SSL key to the nShield card.
    ./generatekey --import simple pemreadfile=/usr/adlex/config/keys/key1.pem ident=key1 plainname=key1name type=RSA protect=module nvram=no
    Note: On a 64-bit AMD (ncipher_pkcs11 engine), use pkcs11 after --import instead of simple.
    a. The value after pemreadfile= should be the path to your SSL key you are importing.
    b. The value after ident= is called the key identifier. It can be any number of numerical digits and lowercase letters. It cannot contain spaces, underscores (_) or hyphens (-).
    c. The value after plainname= can be any name of your choice to identify your key.
    d. The value after type= is the type of key you are importing (e.g. RSA, DES3, DES2, etc.). This will mostly likely be RSA.
    e. The value after protect= is the place to save the SSL key. For better security, make sure that this value is set to module to save the key on the SSL card hardware.
    f. The value after nvram= is Boolean (yes/no). This asks you if you want to save the key blob in NVRAM. It is suggested to set the value to no for ease and simplicity of administration. Setting it to yes requires you to insert the Administrator smart card for this step and potentially any subsequent operation performed on this key.)
  3. If necessary, repeat step 2 to import the rest of your SSL keys. Make sure that every key you import has a unique key identifier. During step 2, make note of all the keys you imported and the key identifiers you configured for them. You can also run the command /rocs (/opt/nfast/bin/rocs) and then type "list keys" to list all the keys that were imported. Type quit to exit out of the rocs utility. When you are done importing all of your SSL keys, continue to step 4.
  4. Edit the /usr/adlex/config/keys/keylist file and add/adjust the entries to show all the keys you just imported. The syntax is token,<appname>:<key id>,Description. Hence, for our example in step 2, we need to add the following line in the keylist file token,simple:key1,key for test software service.
    Note: On a 64-bit AMD (ncipher_pkcs11 engine), the default setting to read keys from the nCipher card is using the key label - not the key id. In this case, the keylist entries syntax needs to be adjusted to token,<appname>:<key name>,Description. Hence, for our example in step 2, we need to add the following line in the keylist file token,simple:key1name,key for test software service. If you are not sure if the AMD is expecting the key id or name, you can edit the rtm.config file and add the property ssl.engine.param=searchKeyBy:<value where <value> can be either id or label. On a 64-bit AMD (ncipher_pkcs11 engine), it is suggested to use the direct key access mode instead of the keylist file to reference the SSL keys. Setting the property ssl.import.all.keys.from.token in the rtm.config file to true, forces the AMD to read ALL the SSL keys that exist on the card and disregard any entries in the keylist file.
  5. Run the command ndstop;ndstart to restart the AMD services. This is required in order for the AMD to read all the keys that were just imported.
  6. Run the command rcmd show ssldecr keys to check if the AMD was able to read all the keys from the nShield card.

2. Keylist file format for nCipher SSL accelerator card.

CASE:

 SSL traffic can not be decoded regardless installed SSL keys seem to be valid and relevant.

SOLUTION:

In case of nCipher cards, the keylist file used for SSL keys mapping may need to be of the following format (unlike in case of other SSL accelerators):

token,<APPNAME>:<identifier>,<comment>

where APPNAME is an application name from nCipher's "security world".
APPNAME derives from a method used for installing PEM keys onto the SSL card, for example:

./generatekey --import simple pemreadfile=/usr/adlex/config/keys/s1.key protect=module ident=s1

In the above example, APPNAME = simple, hence the keylist file entry should look like:

token,simple:<identifier>,<comment>

The following command

/opt/nfast/bin/nfkminfo -k

will list the APPNAME for every SSL key stored in the card in the following order:

AppName <APPNAME> Ident <identifier>

what can help in preparing correct keylist file for AMD.

3. SSL engine performance and SSL threads.

CASE:

 AMD has stopped creating data files, though the rtm.log displays the opposite. Additionally, the number of matched SSL keys is constantly growing when checking 'ssl decr status'.

SOLUTION:

It is possible to boost SSL encryption performance by adding additional threads to the SSL engine.

In general, AMD uses 5 threads that relates to packet analysis. The whole AMD uses a lot more threads for other tasks, like SSL decryption, reading packets from NICs and dispatching them, sequenced transaction assembly, etc.

The maximum number of analysis threads on the AMD is 5.
It is 5 threads per AMD not per decode. The traffic for all decodes will be balanced between those 5 threads.

Additionally it is possible to set the number of threads performing SSL decryption. They are separate from the regular analysis threads.

Set the following parameter in the rtm.config:

rtm.config

 ssl.engine.param=threads:4

4 is a valid value if a machine has enough CPUs. Increasing it further won't help though.