Configure additional hardware
on the physical appliance

This topic describes how to configure the additional hardware on the physical appliance. It includes information on configuring the iDRAC management controller, and describes how to generate certificates and keys onboard the appliance using the Thales nShield Solo HSM.

Configure iDRAC

iDRAC Enterprise has a dedicated network interface card (NIC), which is configured by default to automatically retrieve a DHCP IP address. You can access the iDRAC web interface from a web browser using the following URL:

https://iDRAC_IP_ADDRESS

Log in using the default credentials, as specified in the following Dell documentation: Setup and Manage Your iDRAC.

You can also access iDRAC using telnet, Secure Shell (SSH), and other supported network management protocols, such as Intelligent Platform Management Interface (IPMI).

To change the network configuration of the iDRAC, for example to use a static IP address, see Configure the DELL Remote Access Controller.

Further information

For further information on iDRAC, see the Integrated Dell Remote Access Controller (iDRAC) User's Guide on the Dell Support website.

Configure Thales nShield Solo HSM

This section describes how to use the API Gateway Appliance with private keys stored on the Thales nShield Solo HSM.  It describes how to generate and use private keys stored in the HSM's security world.

You must perform the following tasks:

Create a security world for the HSM

You must create a security world so the HSM can be used with API Gateway and other applications for cryptographic operations.

Note   The module must be in preinitialization mode.

Perform the following steps:

  1. Set the module to preinitialization mode.
  2. Export the following path:
  3. # export PATH=$PATH:/opt/nfast/bin/
    
  4. Create the security world:
  5. # new-world -i -Q 1/2
  6. Select initialization mode on the HSM card.
  7. Follow the on-screen instructions (you should have two blank cards to complete it).
Note   Do not create ACS for which K is equal to N, because you cannot replace such an ACS if even one card is lost or damaged.
  1. Check the status (mode = initialization):
  2. # enquiry
    ...
    Module #1:
    enquiry reply flags  none
    enquiry reply level  Six
    serial number        XXXX-XXXX-XXXX
    mode                 initialization
    version              X.XX.X
    ...
  3. Check the module world (the output in bold must be non-zero):
  4. # nfkminfo -w
    World
    generation  2
    state       0x17270000 Initialised Usable Recovery !PINRecovery !ExistingClient RTC NVRAM FTO SEEDebug
    n_modules   1
    hknso       c8b7e7b38455641bf9d0e45a4c9df9d3cc024430
    hkm         9df31cb768830d9f0ad4b59fcae57bbc3ea6b4d2 (type DES3)
    hkmwk       1d572201be533ebc89f30fdd8f3fac6ca3395bf0
    hkre        cd5d10babb8d6ecaa993b7d61eda9c4cd06af041
    hkra        b43682b54fc72abb649b40457506dbeeda5714b5
    hkmc        31f541ef92b28f47b134e00fb2a77ab6975911be
    hkrtc       7a37e963400821179f470fe39c454a9b0c9bc6b7
    hknv        8fff67e0e51e2929cb5533c839aaa862bd619fc9
    hkdsee      9cfd7bfc3e545df8b955fc25fc52e76d0fe52848
    hkfto       76f4a6cf7c0108ca3dbfa2415e273c71b3235c7f
    hkmnull     1d572201be533ebc89f30fdd8f3fac6ca3395bf0
    ex.client   none
    k-out-of-n  1/1
    other quora m=1 r=1 nv=1 rtc=1 dsee=1 fto=1
    createtime  XXXX-XX-XX XX:XX:XX
    nso timeout 10 min
    
  5. Set the module in operational mode.
  6. Check the status (mode=operational):
  7. # enquiry
    Module #1:
    enquiry reply flags  none
    enquiry reply level  Six
    serial number        XXXX-XXXX-XXXX
    mode                 operational
    version              X.XX.X
    …
    

When a security world has been created, you can create and manage OCS and softcards, as well as create, import, and manage the keys it protects. For more information, see the Thales nShield Solo User Guide.

Generate a new private key on the HSM

Thales nShield Solo supports the RSA key type for the API Gateway's OpenSSL CHIL engine for all cryptographic operations. The following command shows how to generate a key of embed type on the HSM:

# generatekey -g embed plainname=key1 type=rsa size=2048 embedsavefile=key1.pem protect=module

This generates an RSA key with name key1 and size 2048. The key is added to the HSM key storage (/opt/nfast/kmdata/local/). The key1.pem file is generated, containing a specially encoded reference to the generated key. A certificate request and a self-signed certificate are also written to the key1_req.pem and key1_selfcert.pem files respectively.

When you have the certificate and private key, you can import them into the API Gateway's certificate store to use for the CHIL engine cryptographic operations in API Gateway.

Note   You can also use the preinstalled KeySafe Java application to manage OCS, softcards, and keys using its GUI. You must configure it depending on your security environment (see the Thales nShield Solo User Guide).

Import an existing private key into the HSM

If you already have a set of software keys, you can import them into the HSM and instead use the private keys stored on the HSM for all supported cryptographic operations on API Gateway.

The following key types can be imported to the HSM:

  • RSA keys in PEM-encoded PKCS #1 format (with no pass phrase);
  • DES, DES2 and Triple DES keys.

The following steps show how to import an RSA key to the HSM as embed type from a PKCS12 file:

  1. Extract the RSA private key from PKCS12 file:
  2. # openssl pkcs12 -in PKCS12.PFX -nocerts -out pkey_encrypted.pem
    Enter Import Password:
    MAC verified OK
    Enter PEM pass phrase:
    Verifying - Enter PEM pass phrase:
    
Note   Make sure the PEM pass phrase contains at least four characters.
  1. Remove the pass phrase from the private key file:
  2. # openssl rsa -in pkey_encrypted.pem -out pkey_no_pass.pem
    Enter pass phrase for pkey_encrypted.pem:
    writing RSA key
    
  3. Import the private key to HSM:
  4. # generatekey --import embed pemreadfile=pkey_no_pass.pem plainname=importedkey ident=RSAkey1 protect=module
    embedsavefile: Filename to write key to? []
    > key1.pem
    nvram: Blob in NVRAM (needs ACS)? (yes/no) [no] >
    key generation parameters:
    operation      Operation to perform         import
    application    Application                  embed
    verify         Verify security of key       yes
    type           Key type                     RSA
    pemreadfile    PEM file containing RSA key  pkey_no_pass.pem
    embedsavefile  Filename to write key to     key1.pem
    ident          unknown parameter            RSAkey1
    plainname      Key name                     importedkey
    nvram          Blob in NVRAM (needs ACS)    no
    Key successfully imported.
    Path to key: /opt/nfast/kmdata/local/key_embed_xxxxxxxxxxxxxxxx
    

Now you have the key1.pem RSA private enveloped key stored on HSM that you can import into the API Gateway's certificate store. The key1.pem is not a real private key, but an enveloped key that references the real key protected by HSM. The key1.pem cannot be used for cryptographic operations in isolation, for example, when the HSM that protects the real key is not accessible, or the real key is removed from the HSM.

Import the private key into API Gateway

You can  import the certificate and private key stored in the HSM using Policy Studio (see the API Gateway Policy Developer Guide). For example, you have the HSM private enveloped key key1.pem and the self-signed certificate key1_selfcert.pem (see Generate a new private key on the HSM or Import an existing private key into the HSM).

  1. In the Policy Studio tree, select Environment Configuration > Certificates and Keys > Certificates.
  2. Click Create/Import at the bottom right of the window to open the Configure Certificate and Private Key dialog.
  3. Import certificate and key in Policy Studio
  4. Click Import Certificate on the X.509 Certificate tab, and select the key1_selfcert.pem file.
  1. Set the Subject field as required for the certificate.
  2. Click the Private Key tab.
  3. Select the Private key stored locally option.
  4. Click Import Private Key, and select the key1.pem file.
  5. Click OK in the password dialog, leaving the password field blank (key1.pem is not password protected).
Note   Do not select the option Private key stored on Hardware Security Module (HSM) for the Thales nShield Solo HSM. This option is required for HSMs from other vendors.
  1. Click OK to save the imported certificate and private key in the certificate store.

Now the certificate store contains the certificate with the private enveloped key stored and protected in the security world of the nCipher nShield Solo HSM (/opt/nfast/kmdata/local/). You can use this certificate in filters that perform cryptographic operations with the OpenSSL CHIL engine.

Test the HSM installation

To check that the HSM is installed successfully and in operational mode, enter the following command:

# export PATH=$PATH:/opt/nfast/bin/
# enquiry

The following output indicates that the HSM is ready and in operational mode:

Server:
enquiry reply flags  none
enquiry reply level  Six
serial number        XXXX-XXXX-XXXX
mode                 operational
version              X.XX.XX
...
product name         nFast server
...
Module #1:
enquiry reply flags  none
enquiry reply level  Six
serial number        XXXX-XXXX-XXXX
mode                 operational
version              X.XX.X
...
product name         nC1003P/nC3023P/nC3033P
device name          #1 nFast PCI device, bus X, slot X.
...

Further information

This section refers to the Thales nShield Solo User Guide, which can be found in the following location on the appliance:

/opt/add-ons/ncss-linux64-use/document/nShield_User_Guide.pdf

Related Links