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

Generating and Uploading License

Execute this License Generator workflow to generate and download the license file.
Note: The Customer Success Manager (CSM) is responsible to execute this workflow and share the license with the customer representative.
  1. Login to https://license.appviewx.com/ and go to (Menu) > Automation > Service Request > View/Run.
  2. From the Catalog screen, click License Generator, select Modern License Generator - For Customers and click Run.
  3. Enter the details in the fields as follows:
    Fields Description
    General
    *Activate License For ? Select the type of license from the dropdown list:
    • First time license
    • Existing license
    • Prospect
    • Temporary
    *Deployment Type Select the mode of AppViewX deployment:
    • Enterprise
    • Provisioning
    • Managed_K8s
    *Environment Select the type of environment which is to be licensed. (Example: Production, Non-Production, Lab, Staging)
    *Activation Type Select the purpose of license activation. (Example: New, License Activation Failure)
    *Version Select the AppViewX version.
    *License Issuer Name Field is non-editable and contains the email id of the logged in issuer.
    *Get License Via Choose how to obtain the license:
    • Download
    • Email
    License Key
    *License Key Enter the license key.
    Note: License Key is unique to each deployment, copy license key from License info settings.
    Subscriptions
    *Account Name Select the SFDC Account name from the dropdown.
    *Account Owner Non-editable field populated based on the selected account name.
    *Subscription List of subscribed products for the selected account.
    Consolidated License Details
    Get License Summary Button to fetch the licence details.
    *License Meta Consolidate license summary which is used to generate license when license is not edited.
    *Enable HSM License This field is displayed only if the Version = 2026.2.0 or higher. Select the values as follows:
    • False
    • True
    *Number of HSM Accounts

    This field is displayed only if the Enable HSM License = True.

    Number of HSM accounts that can be created in AppViewX from the HSM configuration page. The system stores this value as part of the license details.
    License Customisation
    *Do you want to customize License details? Select
    • No - the license metadata displayed is the final licence generated for the account.
    • Yes - the following fields are displayed (Enter the details for each mandatory field)
      • *Product Names
      • *Invoice Number
      • *Product Type
      • *License Generated Date
      • *License Expiry Date
      • *Product Quantity
      • *Final License Summary
    Final Validation
    Validate License Click Validate License button to check if license is valid or not.
    *License Status Displays the validation status of the license.
    *Mark this is as Active ? Select yes or no, to mark the as active license.
    *Multi Year License Select yes or no, to mark the multi year license.
    Other Metadata Contains the minimum threshold values for the tenant for the following. Values can be edited.
    • *Tenant Type
    • *Tenant Name
    • *Tenant Id
    • *ADC Threshold
    • *Firewall Threshold
    • *Cert Threshold
    • *DDI Threshold
    • *Threshold (Days)
    * : Mandatory fields
  4. Click Submit and download the license at the end of the Request.
  5. Login to the AppViewX node.
    If its a new environment, the Upload license page is displayed. proceed with uploading the license. If its an upgrade license scenario, then follow the steps below.
  6. Go to Menu > Platform > SYSTEM ADMINISTRATION > License, expand any of the products and click Upgrade License.
  7. Click Browse and select the license file to be uploaded and click Upload.

Executing the HSM Vendor Credentials Workflow (OnPrem)

The workflow handles the storage and regional push of Fortanix HSM credentials to the database. You will be allowed to onboard the HSM accounts to AppViewX only after executing this workflow.
Note: To trigger the workflow, please reach out to your CSM for assistance with the execution process.
  1. Login to the AppViewX UI using valid credentials.
    The Dashboard page is displayed by default.
  2. Go (Menu) > Automation > SERVICE REQUEST > View/Run
    The Catalog page is displayed with all the enabled workflows
  3. Search for HSM Vendor Credential Update.
  4. Select HSM Vendor Credential Update worflow and click Run.
  5. Enter the fields in the HSM Details section as follows:
    Table 1. Field descriptions for HSM Details section
    Fields Description
    *Enter Region Select the HSM region.
    *Enter Username Enter the Fortanix credentials/username.
    *Enter Password Enter the Fortanix credentials/password.
    * : Mandatory fields
  6. Click Submit.
    The workflow is executed successfully and the Fortanix credentials are stored/pushed in the database of the selected region.

Auto-Onboarding a New HSM Account

AppViewX provisions a new HSM account and automatically generates the required API key as part of the setup process. The account is securely onboarded and registered in the HSM inventory upon successful provisioning.

HSM accounts provisioned through AppViewX are counted against your licensed HSM account limit.

Note: HSMs created through this workflow are auto-onboarded and cannot be deleted from the UI. Please contact AppViewX support for deletion.
  1. Login to the AppViewX UI using valid credentials.
    The Dashboard page is displayed by default.
  2. Go (Menu) > Platform > VAULT & SECURITY > HSM
    The HSM inventory page is displayed.
  3. 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.
  4. Enable the toggle button Setup New Account to provision and auto-onboard a new HSM account.
    The info message License Usage : 0 / X Accounts used is displayed below the field.
  5. In the General Information section, enter the following fields as follows:
    Table 2. Field descriptions for General Information section
    Fields Description
    *Name Enter a name for the HSM account.
    Description Enter a short description for the HSM account.
    *Data center Select the datacenter to which the calls to HSM can be routed.
    *Region Select the region where the HSM is to be setup.
    Enable Proxy Enable the toggle button to communicate to the HSM through the node without any internet connection.
    * : Mandatory fields
  6. Click Setup and Onboard.
    The HSM account is created and displayed in the HSM inventory with the tag as Auto-Onboarded.

Steps to Integrate

To manually 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. Go (Menu) > Platform > VAULT & SECURITY > HSM
    The HSM inventory page is displayed.
  8. 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.
  9. In the General Information section, enter/select the following details:
    Table 3. Field descriptions for General Information
    Field Description
    Setup New Account Toggle button to auto-onboard the HSM account. Keep the button disabled to perform the manual onboarding.
    *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
  10. 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 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
  11. Click Save.
  12. 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.
  13. If the implementation type is CSR Generation, refer to the CLM User Guide for steps on how to generate a CSR.

Integrating the Fortanix HSM with the AppViewX SaaS

Enabling HSM with License

The AppViewX SRE enables the HSM license during the Add Tenant process. On the Add Tenant page, the system enables the following fields after the SRE adds the required products:
  • * Enable HSM License - Toggle this option to enable the HSM license.
  • * Number of Allowed HSM Accounts - Number of HSM accounts that can be created in AppViewX from the HSM configuration page. The system stores this value as part of the license details.
Note:
  • This feature applies only to AppViewX version 2026.2.0 or later.
  • The system supports this feature only when the selected products on the Add Tenant page use a production license.
  • Only SREs can add tenants.

Executing the HSM Vendor Credentials Workflow (SaaS)

The workflow handles the storage and regional push of Fortanix HSM credentials to the database. You will be allowed to onboard the HSM accounts to AppViewX only after executing this workflow.
Note: The AppViewX SREs are required to trigger this workflow.
  1. Login to the AppViewX UI using valid credentials.
    The Dashboard page is displayed by default.
  2. Go (Menu) > Automation > SERVICE REQUEST > View/Run
    The Catalog page is displayed with all the enabled workflows
  3. Search for SaaS HSM Vendor Credential Update.
  4. Select SaaS HSM Vendor Credential Update worflow and click Run.
  5. Enter the fields in the Upload Details section as follows:
    Table 5. Field descriptions for Upload Details section
    Fields Description
    *Select Region Select the cluster region.
    *Select Cluster Select the specific cluster(s).
    * : Mandatory fields
  6. Enter the fields in the HSM Details section as follows:
    Table 6. Field descriptions for HSM Details section
    Fields Description
    *Enter Region Select the HSM region.
    *Enter Username Enter the Fortanix credentials/username.
    *Enter Password Enter the Fortanix credentials/password.
    * : Mandatory fields
  7. Click Submit.
    The workflow is executed successfully and the Fortanix credentials are stored/pushed in the database of the selected region.

Auto-Onboarding a New HSM Account

AppViewX provisions a new HSM account and automatically generates the required API key as part of the setup process. The account is securely onboarded and registered in the HSM inventory upon successful provisioning.

HSM accounts provisioned through AppViewX are counted against your licensed HSM account limit.

Note: HSMs created through this workflow are auto-onboarded and cannot be deleted from the UI. Please contact AppViewX support for deletion.
  1. Login to the AppViewX UI using valid credentials.
    The Dashboard page is displayed by default.
  2. Go (Menu) > Platform > VAULT & SECURITY > HSM
    The HSM inventory page is displayed.
  3. 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.
  4. Enable the toggle button Setup New Account to provision and auto-onboard a new HSM account.
    The info message License Usage : 0 / X Accounts used is displayed below the field.
  5. In the General Information section, enter the following fields as follows:
    Table 7. Field descriptions for General Information section
    Fields Description
    *Name Enter a name for the HSM account.
    Description Enter a short description for the HSM account.
    *Data center Select the datacenter to which the calls to HSM can be routed.
    *Region Select the region where the HSM is to be setup.
    Enable Proxy Enable the toggle button to communicate to the HSM through the node without any internet connection.
    * : Mandatory fields
  6. Click Setup and Onboard.
    The HSM account is created and displayed in the HSM inventory with the tag as Auto-Onboarded.

Steps to Integrate

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. Go (Menu) > Platform > VAULT & SECURITY > HSM
    The HSM inventory page is displayed.
  8. 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.
  9. In the General Information section, enter/select the following details:
    Table 8. 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
  10. In the Vendor specific details section, enter/select the following details:
    Table 9. 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
  11. Click Save.
  12. 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.
  13. If the implementation type is CSR Generation, refer to the CLM 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.