Fortanix

Prerequisites

  1. The Fortanix HSM device setup should be available.
  2. HSM slot initialization and crypto user credential creation should be done.
  3. Communication to the HSM and AppViewX nodes in the case of and the cloud connector in the case of should be available to integrate with AppViewX. The port details are as follows:
    • Port 443: This is the primary port used for HTTPS communication with the Fortanix DSM.
    • Port 8443: This is used for administrative access to the DSM.
    • Port 9443: This port is used for API access.
  4. The slot id and partition password from the Fortanix device should be available to use in the AppViewX.
For references to the Fortanix documentation, see the References section.

Integrating the Fortanix HSM with the AppViewX Onprem

To integrate the Fortanix HSM with the AppViewX:
  1. Login to the AppViewX server on which the AppViewX is installed.
  2. From the command line interface, navigate to the properties folder path: {APPVIEWX_INSTALLATION_PATH}/appviewx_dependencies/properties
  3. Open the hsm file using the following command: 
    vi hsm
  4. Check and confirm if the HSM file has the following lines. If not, uncomment the following lines: 
    export FORTANIX_PKCS11_CONFIG_PATH= /appviewx/dependencies/hsm/fortanix/pkcs11.conf
    echo "FORTANIX Config Path : $FORTANIX_PKCS11_CONFIG_PATH"
  5. If the file is edited, you have to restart the avx-platform-hsm pod, using the following commands: 
    kubectl get pods -n <namespace>
    kubectl delete pods -n <namespace> <PodName>
  6. Login to the AppViewX UI using valid credentials.
    The Dashboard page is displayed by default.
  7. On HSM page, click Add HSM, from the navigation pane on the left, select Fortanix.
    The HSM > Add page is updated to display the fields required to integrate Fortanix with the AppViewX.
  8. In the General Information section, enter/select the following details:
    Table 1. Field descriptions for General Information
    Field Description
    *Name Enter a name for this integration.
    Description Enter a description for this integration.
    Connection Mode Select whether your application integrates with the Fortanix HSM using the below interfaces:
    • PKCS11
    • SDK
    HSM usage Select an HSM usage from the following options:
    • CSR generation
    • Master key encryption

      Click Proceed.

      To confirm this action enable the Master Key Encryption settings under HSM inventory > Settings
    • Code Signing
    • All
    *Data center Select the required data center from the list of applicable values in the dropdown menu.
    * : Mandatory fields
  9. In the Vendor specific details section, enter/select the following details:
    Table 2. Field descriptions for Vendor specific details
    Field Description
    FIPS Mode Enable the toggle to switch On for FIPS mode.
    *API Key Unique identification number of the slot in the HSM will be used to communicate with the end HSM device. Enter the API key.
    *Key handler name A reference name to create a Master Encryption key in HSM. This enables us to pick the right MEK for crypto operations over KEK.
    *So file This field is enabled when the Connection Mode = PKCS11

    The shared object (.so) file is used to facilitate the communication between the HSM and AppViewX. To upload the .so file:

    1. Click Browse.
    2. Navigate to the location of the .so file.
    3. Select the .so file, and click Open.
    *Config file This field is enabled when the Connection Mode = PKCS11

    The Config file containing connection and environment settings is used to facilitate the communication between the HSM and AppViewX. To upload the .conf file:

    1. Click Browse.
    2. Navigate to the location of the .conf file.
    3. Select the .conf file, and click Open.
    *API URL This field is enabled when the Connection Mode = SDK

    Enter the endpoint URL for the Fortanix API that AppViewX uses to communicate with the Fortanix service.
    * : Mandatory fields
  10. Click Save.
  11. Scroll to the end of this page to view the table or navigate to HSM inventory to view the HSM status. If the HSM has been configured correctly, the status for the HSM will be set to Available after checking the encryption and decryption logic. If the Status is Not Available:
    1. Check the installation path for the HSM.
    2. Ensure that all required permissions have been enabled.
    3. Go to Logs > Logging :: All. Search with HSM and see the Log message.
  12. If the implementation type is CSR Generation, refer to the Cert+ User Guide for steps on how to generate a CSR.

Integrating the Fortanix HSM with the AppViewX SaaS

To integrate the Fortanix HSM with the AppViewX:
  1. Login to the AppViewX server on which the Cloud Connector is installed.
  2. From the command line interface, navigate to the properties folder path: {CC_INSTALLATION_PATH}/deps/properties
  3. Open the hsm file using the following command: 
    vi hsm
  4. Check and confirm if the HSM file has the following lines. If not, uncomment the following lines: 
    export FORTANIX_PKCS11_CONFIG_PATH= /appviewx/dependencies/external_libs/hsm/fortanix/pkcs11.conf
    echo "FORTANIX Config Path : $FORTANIX_PKCS11_CONFIG_PATH"
  5. If the file is edited, you have to restart the avx-mid-server-platform pod, using the following commands: 
    kubectl get pods -n <namespace>
    kubectl delete pods -n <namespace> <PodName>
  6. Login to the AppViewX UI using valid credentials.
    The Dashboard page is displayed by default.
  7. On HSM page, click Add HSM, from the navigation pane on the left, select Fortanix.
    The HSM > Add page is updated to display the fields required to integrate Fortanix with the AppViewX.
  8. In the General Information section, enter/select the following details:
    Table 3. Field descriptions for General Information
    Field Description
    *Name Enter a name for this integration.
    Description Enter a description for this integration.
    HSM usage Select an HSM usage from the following options:
    *Data center Select the required data center from the list of applicable values in the dropdown menu.
    * : Mandatory fields
  9. In the Vendor specific details section, enter/select the following details:
    Table 4. Field descriptions for Vendor specific details
    Field Description
    FIPS Mode Enable the toggle to switch On for FIPS mode.
    *API Key Unique identification number of the slot in the HSM will be used to communicate with the end HSM device. Enter the API key.
    *Key handler name A reference name to create a Master Encryption key in HSM. This enables us to pick the right MEK for crypto operations over KEK.
    *So file The SO file is used to facilitate the communication between the HSM and AppViewX. To upload the .so file:
    1. Click Browse.
    2. Navigate to the location of the .so file.
    3. Select the .so file, and click Open.
    *Config file The Config file is used to facilitate the communication between the HSM and AppViewX. To upload the .conf file:
    1. Click Browse.
    2. Navigate to the location of the .conf file.
    3. Select the .conf file, and click Open.
    * : Mandatory fields
  10. Click Save.
  11. Scroll to the end of this page to view the table or navigate to HSM inventory to view the HSM status. If the HSM has been configured correctly, the status for the HSM will be set to Available after checking the encryption and decryption logic. If the Status is Not Available:
    1. Check the installation path for the HSM.
    2. Ensure that all required permissions have been enabled.
    3. Go to Logs > Logging :: All. Search with HSM and see the Log message.
  12. If the implementation type is CSR Generation, refer to the Cert+ User Guide for steps on how to generate a CSR.

Configuring Fortanix HSM using Proxy

Format for the environment variable

To configure a proxy for Fortanix HSM, the following environment variable has to be added to the HSM properties file. Use the below format to form the environment variable.
  1. If the proxy is http 
    export FORTANIX_PROXY=http://<username>:<password>@<proxy_server_ip>:<proxy_server_port>
  2. If the proxy is https 
    export FORTANIX_PROXY=https://<username>:<password>@<proxy_server_ip>:<proxy_server_port>
Example

Consider the following proxy details:

Proxy IP: 199.199.199.199

Proxy Port: 9999

Username: testuser

Password: Testuser@123

export FORTANIX_PROXY=http://testuser:Testuser%[email protected]:9999
Where the special characters have to be encoded. The encoding for the following special characters is as follows:
Special Character Encoding
@ %40
: %3A
# %23
? %3F
/ %2F
& %26
= %3D
+ %2B
Space ( ) %20

These encodings are required as all the linux distros considers

  • @ separates credentials from the host
  • : separates username and password
  • # denotes a fragment, which is ignored
  • &, ?, and others have special meanings in query strings

If the password contains these characters and are left un-encoded, such characters may cause the URL parser to misinterpret the proxy string, leading to authentication failures or incorrect proxy behavior. Percent-encoding ensures that the credentials are correctly parsed and securely transmitted.

OnPrem Proxy Configurations

For OnPrem proxy configurations, steps are as follows:
  1. Execute the command below. Provide the datacentre in the <namespace>. 
    kubectl get pods -n <namespace>
  2. Login into the HSM pod using the command below. 
    kubectl exec -it <hsm_pod_name>-n <namespace> -- bash
  3. Go to this location /appviewx/dependencies/properties/ and execute the command below. 
    vi hsm
  4. Now, add the following environmental variable which has been formed using the above format. 
    export FORTANIX_PROXY=http://testuser:Testuser%[email protected]:9999
  5. Once added, exit the pod and restart the HSM pod.
  6. After the pod has restarted, update the HSM in the AppViewX application.

SaaS Proxy Configurations

For SaaS proxy configurations, steps are as follows:
  1. Login into the cloud connector server.
  2. Login into the pod using the command below. 
    ./k3s kubectl exec -it <mid-server-platform-pod-name> -n cc -- bash
  3. Go to this location /appviewx/dependencies/properties/ and execute the command below. 
    vi hsm
  4. Now, add the following environmental variable which has been formed using the above format. 
    export FORTANIX_PROXY=http://testuser:Testuser%[email protected]:9999
  5. Once added, exit the pod and restart the platform midserver pod.
  6. After the pod has restarted, update the HSM in the AppViewX application.