Fortanix Data Security Manager with Imperva Cloud WAF

1.0 Introduction

This article describes how to integrate Fortanix-Data-Security-Manager (DSM) with Imperva Cloud Web Application Firewall (WAF) (formerly Incapsula) services.

2.0 Configure Fortanix DSM

A Fortanix DSM service must be configured, and the URL must be accessible. To create a Fortanix DSM account and group, refer to the following sections:

2.1 Signing Up

To get started with the Fortanix DSM cloud service, you must register an account at <Your_DSM_Service_URL>. For example, https://eu.smartkey.io.

For detailed steps on how to set up the Fortanix DSM, refer to the User's Guide: Sign Up for Fortanix Data Security Manager SaaS documentation.

2.2 Creating an Account

Access <Your_DSM_Service_URL> in a web browser and enter your credentials to log in to Fortanix DSM.

For more information on how to set up an account in Fortanix DSM, refer to the User's Guide: Getting Started with Fortanix Data Security Manager - UI.

2.3 Creating a Group

Perform the following steps to create a group in the Fortanix DSM:

1. In the DSM left navigation panel, click the Groups menu item, and then click the + button to create a new group.

   

2. On the Adding new group page, do the following:

   1. Title: Enter a name for your group.

   2. Description (optional): Enter a short description of the group.

3. Click SAVE to create the new group.

The new group is added to the Fortanix DSM successfully.

2.4 Creating an Application

Perform the following steps to create an application (app) in the Fortanix DSM:

1. In the DSM left navigation panel, click the Apps menu item, and then click the + button to create a new app.

   

2. On the Adding new app page, do the following:

   1. App name: Enter the name for your application.

   2. ADD DESCRIPTION (optional): Enter a short description of the application.

   3. Authentication method: Select the default API Key as the authentication method from the drop down menu. For more information on these authentication methods, refer to the User's Guide: Authentication.

   4. Assigning the new app to groups: Select the group created in Section 2.3: Creating a Group from the list.

3. Click SAVE to add the new application.

The new application is added to the Fortanix DSM successfully.

2.5 Creating a Security Object

Perform the following steps to import an RSA key in the Fortanix DSM:

1. In the DSM left navigation panel, click the Security Objects menu item, and then click the + button to create a new security object.

   

2. On the Add new Security Object page, do the following:

   1. Security Object Name: Enter a name for your security object.

   2. Group: Select the group as created in Section 2.3: Creating a Group.

   3. Select the IMPORT radio button.

   4. In the Choose a type section, select the RSA key type.

   5. In the Place value here or import from file section, select the value format type as Hex, Base64, or Raw and click the UPLOAD A FILE button to upload the key file.

   6. In the Key operations permitted section, select the required operations to define the actions that can be performed with the cryptographic keys, such as encryption, decryption, signing, and verifying. For the Cloud WAF integration, Imperva recommends only selecting Encrypt and Decrypt permissions to limit functions specifically to what is needed by Imperva.

      NOTE

      Key operations are selected at the time of importing a security object or during the creation of a new security object from Fortanix DSM. The key operations can be removed after the security object has been created but permissions cannot be added after security object creation.

3. Click IMPORT to create the new security object.

4. You must modify the Padding Policy to include Raw (Decryption only). Click SAVE.

   

3.0 Details of Fortanix DSM Used in Imperva

Provide Imperva with the following from Fortanix DSM.

3.1 Identify the Data Security Manager Region(s)

At Imperva, Fortanix regions are referred to as hostnames. These hostnames appear at the beginning of the Fortanix API subdomain URL and help determine the correct regional endpoint for API requests.

For example: api.amer.smartkey.io, api.eu.smartkey.io, api.uk.smartkey.io, api.apac.smartkey.io, api.au.smartkey.io.

Perform the following steps to copy the Google EKMS URI from the Fortanix DSM:

1. In the DSM left navigation panel, click the Security Objects menu item and then click the security object created in Section 2.5: Creating a Security Object to go to the detailed view of the security object.

2. Click the COPY ID drop down menu and select the COPY GOOGLE EKMS URI option to copy the URI.

   

3.2 Copying the API Key

Perform the following steps to copy the API key from the Fortanix DSM:

1. In the DSM left navigation panel, click the Apps menu item, and then click the app created in Section 2.4: Creating an Application to go to the detailed view of the app.

2. On the INFO tab, click the VIEW API KEY DETAILS button.

3. From the API Key Details dialog box, copy the API Key of the app to use it later.

3.3 Copying the App UUID

Perform the following steps to copy the app UUID from the Fortanix DSM:

1. Click the Apps menu item in the DSM left navigation panel and click the app created in Section 2.4: Creating an Application to go to the detailed view of the app.

2. From the top of the app’s page, click the copy icon next to the app UUID to copy it to use to generate the certificate.

3.4 Summary

Together with the custom certificate, you will need to provide the following information from Fortanix DSM user interface (UI) as explained above.

Use the following APIs to provision your HSM certificate on Imperva:

1. Action: Upload Certificate
   URL: https://my.impervaservices.com/api/v2/sites/{extSiteId}/hsmCertificate/upload
   HTTP Method: PUT
   Headers:
         api_key: <your Imperva API key>

         api_id: <your Imperva API ID>

   Parameters:

        Path Parameter: extSiteId: This is a path parameter representing the external site ID for the Imperva site.

        Query Parameters: certificate: This is a query parameter and represents a certificate string, encoded in base64 format. For example: LS0tLS1CRUdJTiBDRVJUSUZJQ0...

   Body: your Fortanix connection details. The schema should look like the following:

   {"hsm_data":[
          {
          "key_id":"123abcde-1234-1234-abcd-123456789abc", 
          "api_key":"MTAyYThmMz...",
                        "host_name":"api.amer.smartkey.io"
          }]
   }

   Remarks:

   • key_id: Your security object UUID on Fortanix.

   • api_key: Your API key on Fortanix.

   • host_name: The address of your assets on Fortanix. NOTE - it should start with API. You can find your host address under your security object section, by clicking the COPY URI button.

   Response:

   If the certificate was uploaded successfully (and replaced the previous HSM custom certificate on the site, you should get the following response:

   Status Code: 200
   Response Message: succeed to save the certificate.

   The certificate is validated and connection to Fortanix service is done before the certificate is uploaded.

2. Action: Remove Certificate
   URL: https://my.impervaservices.com/api/v2/sites/{extSiteId}/hsmCertificate/remove
   HTTP Method: DELETE
   Headers:
         api_key:<your Imperva API keys>

         api_id: <your Imperva API ID>

   Parameters:

         Path Parameter: extSiteId- your Imperva Site ID.

   Response:

   If the certificate was removed successfully, you should get the following response:

   Status Code: 200
   Response Message: OK.

3. Action: Test Connectivity
   URL: https://my.impervaservices.com/api/v2/sites/{extSiteId}/hsmCertificate/testConnectivity
   HTTP Method: GET
   Headers:
         api_key: <your Imperva API key>

         api_id: <your Imperva API ID>

   Parameters:

         Path Parameter: extSiteId- your Imperva Site ID.

   Response:

   If connection with HSM performed successfully, you should get the following response:

   Status Code: 200
   Response Message: HSM connection established successfully.

4.0 References

For more information on Imperva’s documentation, refer to the Uploading a Custom Certificate with HSM support.