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.

• 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, 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 with a list of databases and their corresponding 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 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.

   • 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. This file should include the credentials for the Fortanix Armor platform and the list of databases to be scanned.

   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 for various databases 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 the scanner package installation, you must configure the package with the connection ID, API key, and database (DB) credentials.

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

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

The scanner configuration file includes:

• Credentials for authenticating with Fortanix Key Insight software as a service (SaaS).

• A list of databases, including their URIs and query credentials. To facilitate integration with a secrets manager, the scanner can be configured to read database credentials from either an environment variable or a separate credentials file.

1. Sample configuration file:

   # Config file
   fortanix:
     url: 'https://armor.fortanix.com'
     connection_id: 2b6427fb-f19a-46e9-aa56-3293a218d917
     credential:
       type: apikey
       apikey:
         value: "......"
   databases:
     - uri: "oracle://host:port/db"
       username:
         value: un
       password:
         value: pass
     - uri: "mssql://host:port"
       username:
         file: "/path/to/username_file"
       password:
         file: "/path/to/password_file"
     - uri: "mssql://host:port"
       username:
         env_var: "DB1_USERNAME"
       password:
               env_var: "DB1_PASSWORD"

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

   # Config file
   fortanix:
     url: 'https://armor.fortanix.com'
     connection_id: 2b6427fb-f19a-46e9-aa56-3293a218d917
     credential:
       type: apikey
       apikey:
         env_var: FORTANIX_API_KEY
   databases:
     - uri: "oracle://host1:port/db"
       username:
         env_var: "DB1_USERNAME"
       password:
         env_var: "DB1_PASSWORD"
     - uri: "mssql://host2:port"
       username:
         env_var: "DB2_USERNAME"
       password:
         env_var: "DB2_PASSWORD"
     - uri: "mssql://host3: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 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:

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 MS SQL 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 Both Oracle and MS SQL

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 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 or On-Premises 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 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.

7. 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.

   

8. 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.

9. You can navigate to the Fortanix Key Insight Overview page to access all the on-premises scanned keys and resources.

   NOTE

   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.

   

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

6.0 Fortanix Key Insight - Manage On-Premises Connections

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

NOTE

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

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

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

1. You can copy the Connection ID if required.

2. You can view the CONNECTION STATUS of the scanner. The valid values are Connected, Pending, and Disconnected.

3. 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.

4. 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 4.0: Fortanix Key Insight - Configure an On-premises Connection.

   NOTE

   On the Key Insight Policy page, when adding an on-premises connection, you can select any policies you have configured in the Policy Center, instead of the default policy. If you change the policy while adding the on-premises connection, you must rescan the connection to apply the new policy.

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

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 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.

NOTE

You cannot perform RESCAN for pending and disconnected on-premises connections.

7.0 Fortanix Key Insight - Manage Policy Center

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