Fortanix Key Insight - Getting Started With On-Premises Connection

1.0 Introduction

This article helps you get started with the Fortanix Key Insight on-premises connection. It also describes:

• How to sign up and log in to Fortanix Key Insight.

• Configure the on-premises connection to scan keys and resources from both databases and the Fortanix DSM on-premises environment.

• Manage the on-premises connections on Fortanix Key Insight.

• Manage cryptographic policies for on-premises connections.

2.0 Terminology References

Refer to Fortanix Key Insight – On-Premises Concepts Guide for the on-premises terminologies.

3.0 Fortanix Key Insight - Log in and Create Account

Fortanix Key Insight is a solution on the Fortanix Fortanix Armor platform. So, you need to create an account on the platform if you do not already have one.

3.1 Sign Up and Log In to Fortanix Platform - New Users

If you are accessing Fortanix Key Insight for the first time, you need to sign up for Fortanix Armor to access Key Insight. For the subsequent access, you can log in to Fortanix Armor directly.

For more details on how to sign up or log in and create an account for Key Insight, refer to Fortanix Armor – Getting Started Guide.

3.2 Log In to Fortanix Armor Platform - Existing Users

You can directly log in to the Fortanix Armor platform to access Key Insight if you have already signed up and have an account.

For more details on how to log in and create an account on Fortanix Armor, refer to Fortanix Armor – Getting Started Guide.

4.0 Fortanix Key Insight - Configure On-Premises Connections

After you access the Fortanix Key Insight solution through Fortanix Armor, you must configure the on-premises connection to scan your keys and resources.

4.1 Prerequisites

The following are the prerequisites to configure an on-premises connection on Fortanix Key Insight:

• Server Specifications

  • The server hosting the scanner must have at least 2 virtual Central Processing Units (vCPUs) allocated.

  • The server must have a minimum of 8 GB of Random Access Memory (RAM) to support the scanner.

  • The server should have at least 20 GB of storage capacity for temporarily storing scanned data.

• Operating System and Libraries

  • Supported operating systems include Ubuntu 20.04, Ubuntu 22.04, Ubuntu 24.04, and RHEL 9 (or Rocky Linux 9). The necessary packages are available in .deb or .rpm formats.

• Network

  The on-premises scanner must be allowed to make outgoing connections to:

  • armor.fortanix.com on port 443

  • Databases on their configured ports

  NOTE

  The on-premises scanner does not expose any ports.

• Configuration File

  The on-premises scanner requires a configuration file that includes a list of databases with their corresponding credentials, as well as the Fortanix DSM on-premises credentials. This configuration file is in plain text, and it is your responsibility to secure the file and its credentials.

• Database Permissions

  You must have read permissions to access the catalog table views in the database.

4.2 On-Premises Scanner Installation

You must install the on-premises scanner package to manage your databases and Fortanix DSM on-premises keys and resources.

1. Download the scanner package to your local machine. The deb or rpm package is provided with the downloaded package for the supported operating systems.

2. Run the following command to install the scanner package:

   • Ubuntu 20.04

     $ sudo apt install ./fortanix-scanner_<version>-focal_amd64.deb

   • Ubuntu 22.04

     $ sudo apt install ./fortanix-scanner_<version>-jammy_amd64.deb

     NOTE

     You can ignore the message N: Download is performed unsandboxed as root as file '..../fortanix-scanner_<version>-jammy_amd64.deb' couldn't be accessed by user '_apt'. - pkgAcquire::Run (13: Permission denied) during the installation of the scanner package.

   • Ubuntu 24.04

     $ sudo apt install ./fortanix-scanner_<version>-noble_amd64.deb

   • RHEL9

     $ sudo dnf install ./fortanix-scanner-<version>-1.x86_64.rpm

3. Generate the scanner configuration file as detailed in Section 4.3: On-Premises Scanner Configuration.

   NOTE

   • You must create the configuration file in the /opt/fortanix/scanner/conf directory.

   • A sample configuration file is present in /opt/fortanix/scanner/conf/fortanix-scanner.yaml.example.

4. Initiate the scanning process as detailed in Section 4.4: Execute the Scanner.

NOTE

After you start the scanner, any changes made to the scanner configuration file require a restart of the scanner to apply the latest updates.

4.3 On-Premises Scanner Configuration

After installing the scanner package, you must configure it with the following information:

• For database scanning: Connection ID, API key, and database credentials. You can obtain the connection ID and API key from the On-Premises connection details page. For more details, refer to the Section 6.1: View the On-Premises Connection Details.

• For Fortanix DSM on-premises environment scanning: Connection ID, API key, and Fortanix DSM credentials, such as the admin application (app) ID and certificates.

The fortanix-scanner is the on-premises scanner executable. The current version supports scanning databases and Fortanix DSM on-premises keys. It requires the path to .yaml configuration file as a command-line argument:

$ fortanix-scanner -c /path/to/config.yaml

NOTE

The configuration file is processed in the order they are provided.

The scanner configuration file includes:

• Credentials for authenticating with Fortanix Key Insight.

• A list of databases, including their Uniform Resource Identifiers (URIs) (URLs and query credentials.

• Credentials for authenticating with Fortanix DSM on-premises environment.

To facilitate integration with a secrets manager, the scanner can be configured to read all the credentials from either an environment variable or a separate credentials file.

1. Sample configuration file:

   armor:
     url: 'https://armor.fortanix.com'
   connections:
     - connection_id: 9d4c54e0-ba56-481b-8d19-36f70f71af87
       credential:
         type: apikey
         apikey:
           value: ...
       dsm:
         url: 'https://onprem.dsm.host'
         app_id: <Uuid>
         credential:
           type: certificate
           authentication_key:
             value: ...
           authentication_cert:
             value: ...
     - connection_id: 2b6427fb-f19a-46e9-aa56-3293a218d917
       credential:
         type: apikey
         apikey:
           value: ...
       databases:
         - uri: 'oracle://host:port/db'
           username:
             value: ...
           password:
             value: ...
         - uri: 'mssql://host:port'
           username:
             value: ...
           password:
             file: ...
         - uri: 'mssql://host:port'
           username:
             value: ...
           password:
             value: ...

2. Sample configuration file where Fortanix credentials are read from environment variables:

   armor:
     url: 'https://armor.fortanix.com'
   connections:
     - connection_id: 9d4c54e0-ba56-481b-8d19-36f70f71af87
       credential:
         type: apikey
         apikey:
           env_var: ARMOR_API_KEY_1
       dsm:
         url: 'https://onprem.dsm.host'
         app_id: <Uuid>
         credential:
           type: certificate
           authentication_key:
             env_var: DSM_APP_AUTH_KEY
           authentication_cert:
             env_var: DSM_APP_AUTH_CERT
     - connection_id: 2b6427fb-f19a-46e9-aa56-3293a218d917
       credential:
         type: apikey
         apikey:
           apikey:
           env_var: ARMOR_API_KEY_2
       databases:
         - uri: 'oracle://host:port/db'
           username:
             env_var: DB1_USERNAME
           password:
             env_var: DB1_PASSWORD
         - uri: 'mssql://host:port'
           username:
             env_var: DB2_USERNAME
           password:
             env_var: DB2_PASSWORD
         - uri: 'mssql://host:port'
           username:
             env_var: DB3_USERNAME
           password:
             env_var: DB3_PASSWORD

NOTE

• The paths specified in the configuration file are relative to /opt/fortanix/scanner/bin directory by default.

• If the configuration file has duplicate database URIs, the last specified URI and its associated credentials will override any previous entries.

• If you are using the older configuration file (prior to the KI 25.04 release), you can continue with it. However, to scan the Fortanix DSM on-premises environment—or both the Fortanix DSM on-premises environment and databases—you must use the new configuration file mentioned above.

If you use secret manager tools (for example, Hashicorp Vault) to manage credentials, refer to Fortanix Key Insight - On-Premises Scanner Integration with Hashicorp Vault for on-premises scanner configuration.

4.4 Execute the Scanner

Refer to the following sections to initiate the scanner for various databases:

NOTE

Any database information in the configuration file that is not relevant to the specified scan type (Oracle, MSSQL, or Fortanix DSM On-Premises Environment) will be ignored during the scanning process.

4.4.1 Scan Oracle Only

1. Perform the following steps to install the Oracle Instant Client package: This will help you to connect to the Oracle database from the scanner.

   1. Open the Oracle Instant Client version 23.5.0.

   2. Download the instantclient-basic-linux.x64-23.5.0.24.07.zip file.

   3. Run the following command to create folders for installing Oracle Instant Client:

      $ mkdir -p /opt/oracle

   4. Run the following commands to extract the files: This would create a directory instantclient_23_5 in /opt/oracle:

      $ sudo cp instantclient-basic-linux.x64-23.5.0.24.07.zip /opt/oracle
      $ cd /opt/oracle
      $ sudo unzip instantclient-basic-linux.x64-23.5.0.24.07.zip

   5. Run the following command to modify or create /etc/ld.so.conf.d/oracle.conf file and add it to the directory  instantclient_23_5:

      $ echo /opt/oracle/instantclient_23_5 | sudo tee /etc/ld.so.conf.d/oracle.conf

   6. Run the following command to update the dynamic link:

      This allows the Oracle Cloud Infrastructure (OCI) libraries to be accessible to other applications on the host, ensuring that they can find and use these shared libraries when needed.

      $ sudo ldconfig

2. Run the following command to start the scanner:

   $ sudo -u fortanix -E -H /opt/fortanix/scanner/bin/fortanix-oracle-scanner start -c /opt/fortanix/scanner/conf/config.yaml

   Or

   The fortanix-oracle-scanner can be run as a systemd service. A sample unit file is provided at /opt/fortanix/scanner/conf/fortanix-oracle-scanner.service.example. Create a systemd unit file based on the example in /usr/lib/systemd/system/.

   $ sudo systemctl enable fortanix-oracle-scanner
   $ sudo systemctl start fortanix-oracle-scanner

4.4.2 Scan MSSQL Only

Run the following command to start the scanner:

$ sudo -u fortanix -E -H /opt/fortanix/scanner/bin/fortanix-mssql-scanner start -c /opt/fortanix/scanner/conf/config.yaml

Or

The fortanix-mssql-scanner can be run as a systemd service. A sample unit file is provided at /opt/fortanix/scanner/conf/fortanix-mssql-scanner.service.example. Create a systemd unit file based on the example in /usr/lib/systemd/system/.

$ sudo systemctl enable fortanix-mssql-scanner 
$ sudo systemctl start fortanix-mssql-scanner 

4.4.3 Scan Fortanix DSM On-Premises Environment Only

Run the following command to start the scanner:

$ sudo -u fortanix -E -H /opt/fortanix/scanner/bin/fortanix-dsm-scanner start -c /opt/fortanix/scanner/conf/config.yaml

Or

The fortanix-dsm-scanner can be run as a systemd service. A sample unit file is provided at /opt/fortanix/scanner/conf/fortanix-dsm-scanner.service.example. Create a systemd unit file based on the example in /usr/lib/systemd/system/.

$ sudo systemctl enable fortanix-dsm-scanner 
$ sudo systemctl start fortanix-dsm-scanner 

4.4.4 Scan All

Perform the following steps to scan Oracle, MSSQL, and/or Fortanix DSM on-premises environment keys and resources:

1. Refer to Step 1 from Section 4.4.1: Scan Oracle Only to install the Oracle client libraries.

2. Run the following command to start the scanner:

   $ sudo -u fortanix -E -H /opt/fortanix/scanner/bin/fortanix-scanner start -c /opt/fortanix/scanner/conf/config.yaml

   Or

   The fortanix-scanner can be run as a systemd service. A sample unit file is provided at  /opt/fortanix/scanner/conf/fortanix-scanner.service.example. Create a systemd unit file based on the example in /usr/lib/systemd/system/.

   $ sudo systemctl enable fortanix-scanner
   $ sudo systemctl start fortanix-scanner

4.5 Troubleshooting

When running the Fortanix Key Insight or Fortanix DSM On-Premises scanners on different Linux environments, you may encounter missing library errors.

wget http://archive.ubuntu.com/ubuntu/pool/main/o/openssl/libssl1.1_1.1.1f-1ubuntu2_amd64.deb

dpkg -i libssl1.1_1.1.1f-1ubuntu2_amd64.deb

apt-get install -f

apt-get update

apt-get install libaio-dev -y

ln -s /lib/x86_64-linux-gnu/libaio.so.1t64 /lib/x86_64-linux-gnu/libaio.so.1

wget https://yum.oracle.com/repo/OracleLinux/OL9/appstream/x86_64/getPackage/compat-openssl11-1.1.1k-3.el9.x86_64.rpm

dnf install ./compat-openssl11-1.1.1k-3.el9.x86_64.rpm -y

4.6 Limitations

Here are the known limitations of Oracle and MSSQL databases in terms of their encryption key management:

5.0 Fortanix Key Insight - Onboard an On-Premises Connection

After you create a Fortanix Armor account, you will be redirected to the Fortanix Armor Available Solutions page.

To onboard an on-premises connection:

1. Click GO TO KEY INSIGHT.

2. On the Let's Connect to Your Cloud, On-Premises or External Key Source Provider page, select On-Premises Connections option.

3. Click NEXT.

   

4. On the Add on-premises scanner page,

   1. Enter the Scanner name.

   2. You must install the on-premises scanner package to manage your on-premises keys and resources. For more details, refer to Section 4.2: On-premises Scanner Installation, Section 4.3: On-premises Scanner Configuration, and Section 4.4: Execute the Scanner.

   3. Select to enable I have downloaded and installed the Scanner package check box to confirm the scanner installation.

   4. Click NEXT.

      

5. The Fortanix Key Insight System Defined Policy is selected by default on the Key Insight Policy page. This policy is designed to facilitate the scanning of keys and services based on predefined key sizes and permitted operations, ensuring compliance with standard security configurations. If necessary, you can later select and apply any user-defined cryptographic policy created in the Policy Center, allowing you to meet specific requirements or use cases.

   For more details, refer to Section 7.0: Fortanix Key Insight - Manage Policy Center.

   

6. Click NEXT.

7. On the Select External Key Source page, you can select to integrate Fortanix Key Insight with an external key source, that is Fortanix DSM (SaaS or On-Premises) to correlate keys and improve key management.

   You can select any of the following options:

   1. Yes, connect now: Selecting this option allows you to add the external key source for your on-premises connection to correlate keys using the ADD EXTERNAL KEY SOURCE feature. For more details, refer to Fortanix Key Insight - Getting Started With External Key Source Connection.

      After adding, you must select the new external key source to complete the onboarding.

      

   2. No, I’ll connect later: Selecting this option allows you to onboard the on-premises connection without adding an external key source. You can add it later if needed.

      

8. Click ADD SCANNER & GENERATE API KEY to add the scanner using the generated API key. You will be authenticating with Fortanix Key Insight using the API key.

9. On the API Key Details dialog box, click COPY API KEY to copy the API key value. This value is used to authenticate between the on-premises scanner and the Fortanix Key Insight.

10. The new on-premises connection will be added to the ON-PREMISES tab on the Connections page.

    The CONNECTION STATUS column displays one of the following statuses:

    1. Connected: The scanner package has been successfully added, and all keys and resources have been scanned without issues.

    2. Pending: The scanner package has been added, but resources are still pending. For on-premises connections in this state:

       • You must use the generated API key to connect with Fortanix Key Insight.

       • To begin scanning, you need to add the resources after establishing the connection.

    3. Disconnected: The scanner package is connected, but the session has been terminated. For on-premises connections that are disconnected, you will need to restart the scanner to re-establish the connection.

    NOTE

    The scanner polls to the Fortanix Key Insight platform every 15 seconds to check for any new commands or scan results. The frequent polling ensures that the scanner is always up to date with the latest commands and can act on them promptly.

11. If you added an external key source, such as (Fortanix DSM (SaaS or On-Premises) during on-premises connection onboarding, the Overview page will display the following after a successful scan:

    NOTE

    • If your Fortanix Armor account is deactivated and you are accessing the Fortanix Key Insight On-Premises connection, you will not be able to view data under the Overview, Assessments, Keys, Resources, or PQC Central pages. You will only have access to view and delete items within the Connections, Policy Center, and Authentication pages.

    • After creating the on-premises connection, a group with the same name will be created on the Fortanix IAM Groups page. For more details, refer to Fortanix Armor Identity and Access Management-IAM.

    • If you added an external key source (Fortanix DSM (SaaS or On-Premises) during on-premises connection onboarding, the Overview page will display the following after the successful scan:

      • The total key counts in all sections will be updated to include correlated keys from the external key source.

      • The “Fortanix” key source field will display the correlated keys count.

    

    For more information on the on-premises Overview page and its features, refer to the Fortanix Key Insight- On-Premises User Interface Components.

    For more information on the on-premises connection PQC Central features, refer to the Fortanix Key Insight User Interface Components - PQC Central.

6.0 Fortanix Key Insight - Manage On-Premises Connections

The Connections page allows you to manage the cloud, on-premises, and externak key source connections added to the Fortanix Key Insight.

NOTE

For on-premises connections, the left navigation panel will show the Resources instead of Services.

The ON-PREMISES tab on the Connections page shows all the on-premises connections configured for the selected Fortanix Key Insight account.

You can perform the following on the On-Premises Connections page:

• You can copy the connection ID if required.

• You can view the CONNECTION STATUS of the scanner. The values can be Connected, Pending, or Disconnected.

• You can check the PERIODICAL POLL time. If you encounter any warnings, you must address them by following the appropriate troubleshooting steps. By default, the periodic poll interval is set to 15 seconds.

  NOTE

  The "polling interval" for an on-premises connection is the frequency at which Fortanix Key Insight checks for updates or status changes from connected resources. This interval ensures the connection remains active and retrieves any new data.

• You can use the Search field to search for a specific on-premises connection by entering its Name.

• You can add a new on-premises connection using ADD ON-PREMISES SCANNER. For more details on how to add a new on-premises connection, refer to Section 5.0: Fortanix Key Insight - Configure an On-premises Connection.

  NOTE

  When adding or editing an on-premises connection,

  • You can select any policies you have configured in the Policy Center instead of the default policy on the Key Insight Policy page. If you change the policy while adding or editing the connection, you must rescan the connection to apply the new policy.

  • You cannot map more than one Fortanix DSM (SaaS or On-Premises) connection to a single on-premises connection.

  • You cannot map the external key source to any on-premises connection unless it is properly configured and mapped to Fortanix DSM (SaaS or On-Premises).

• You can click on each connection to navigate to its corresponding Overview page.

For each on-premises connection, you can perform the following:

• View connection details

• EDIT connection

• DELETE connection

• RESCAN connection

NOTE

Users with the Account Administrator and Group Administrator roles can only perform add, edit, delete, and rescan operations for the on-premises scanner.

6.1 View the On-Premises Connection Details

• Click DOWNLOAD PACKAGE to download the package again in case you changed your machine, your current package has errors, or was not installed correctly.

• Click EDIT to edit the details of the connection. For more details, refer to Section 6.2: Edit the On-Premises Connection.

• Click DELETE to remove the on-premises connection. For more details, refer to Section 6.3: Delete an On-Premises Connection.

• Scanner Details

  This section provides details about the scanner's connection status, hostname, number of resources, last scan, periodic polling interval, and the date and time it was created.

• Access Type

  This section offers details about the API key, including the following:

  • Click SHOW API KEY to view the API key details. Click COPY API KEY to copy the API key if required.

    

  • Click REGENERATE API KEY to modify the current API key details if the existing API key is no longer suitable for the on-premises connection.

    On the Regenerate API Key dialog box, you can:

    • Set the API key expiration: Select the appropriate option to revoke the previous access immediately or after a specified duration.

    • Review and acknowledge the check boxes.

    • After updating the details, click UPDATE to apply the configured information.

    

  NOTE

  Users with the Account Administrator and Group administrator roles can only view, copy and regenerate an API key for the on-premises scanner.

• Resources

  This section displays the resources associated with the current on-premises connection. For more details on resources, refer to Fortanix Key Insight- On-Premises User Interface Components. If no resources are listed, you can add them through the on-premises scanner configuration file configured in your environment.

6.2 Edit the On-Premises Connection

Use this feature to update the name of the on-premises connection.

1. Select the required on-premises connection and click → EDIT.

2. On the Edit On-Premises Scanner dialog box, enter the Scanner name.

3. Click NEXT.

4. Select the required policy on the Key Insight Policy page.

   NOTE

   When you change the policy on the Key Insight Policy page while updating the on-premises connection, you must rescan the connection to apply the new policy.

5. Click SAVE to update the details.

6.3 Delete the On-Premises Connection

Use this feature to remove an on-premises connection and its associated information.

1. Select the required on-premises connection and click → DELETE.

2. Read all the details and enter the scanner name in the text box.

3. Click CONFIRM.

   WARNING

   Deleting the on-premises connection cannot be undone.

4. After deletion, the on-premises connection will no longer appear in the list on the ON-PREMISES Connections page.

6.4 Rescan the On-Premises Connection

Use this feature to retrieve the latest resources available for the on-premises scanner.

Perform the following steps to rescan an On-premises connection:

1. Select the required on-premises connection and click → RESCAN.

2. Click START SCANNING to restart the scan. If the scan is successful, it will update the LAST SCAN column with the latest scan date and time.

7.0 Fortanix Key Insight - Manage Policy Center

Refer to Manage Policy Center for details on how to manage policies for on-premises connections.