Fortanix Data Security Manager with Imperva Cloud WAF

Introduction

This article describes how to integrate Fortanix Data Security Manager (DSM) and Imperva Cloud WAF (formerly Incapsula) services.

Initial Fortanix Data Security Manager Setup

1. Create a Data Security Manager Account in the preferred and/or multiple regions. Since Cloud WAF is globally deployed, if you have end-users around the world, it would be best to create a smart key available at multi-region in order to provide faster TLS handshakes (the speed of handshake depends on the distance between Imperva’s edge proxies and the nearest Smart Key region).
   1. Sign up for Fortanix Data Security Manager™. To get started with Fortanix Data Security Manager™, you must sign up at: https://fortanix.com/products/data-security-manager/saas/
   2. After signing up go to https://smartkey.io and log in. Figure 1: Log in
      After entering an account, you can view and manage groups, users, applications, and security objects belonging to the account. You are in the Fortanix environment, and your account will be with Fortanix. Figure 2: Fortanix DSM SaaS dashboard
2. Create a group for Imperva integration.
   1. Add a group: A group is a collection of security objects created by and accessible by users and applications which belong to the group. The user who creates a group automatically gets assigned the role of the group administrator. You can add more users to the group in the role of administrators or auditors. You can also add applications to the group to enable the applications to create and use security objects in that group.
      To add a group, specify the following:
      
      • The title of the group (required).
      • A short description for the group (optional).
      Figure 3: Fortanix DSM SaaS dashboard Figure 4: Group created
   2. Users: The users in your group are account members.
   3. Applications: Applications can be added to the group so that they use the security objects in the group. Figure 5: Group detailed view
3. Create an application (API Key).
   Add Imperva Cloud WAF as an application to the Group created in Step 2. The API Application will only have access within the parameters of the group that it's associated with. In this case, the API Application will not have access to any groups or objects that are in addition to your main account.
   An application can use Data Security Manager to generate, store, and use security objects, such as cryptographic keys, certificates, or an arbitrary secret. Examples of applications include web servers, PKI servers, key vaults, etc. An application can interact with Data Security Manager using the REST APIs or using the PKCS#11, JCE, or CNG providers.
   To add an application, specify the following:
   
   • Name of the application (required, for example: Imperva Cloud WAF).
   • Type of the application (leave blank).
   • A short description of the application. (For example, Cloud WAF, CDN, and DDoS).
   • For the Authentication method, choose the API key to use for authentication.
   • The group(s) to which the application belongs (Group was created in Step 2).
   Figure 6: Create an app
4. Create or Import a new Security Object (UI).
   1. Add a Security Object. Figure 7: Create SO
   2. Enter a name for the Security Object that you will be importing.
   3. Assign the Security Object to the appropriate Group.
   4. Select Import.
   5. Select the type of crypto key that you will be importing. Figure 8: Create SO
   6. Select the value format of Base64 and paste that value in the box provided below. Figure 9: Upload file
   7. Select/clear the Key Operations that you permit for this key object to be able to perform. 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. Key operations can be removed after the object has been created but permissions cannot be added after security object creation.
      Figure 10: Create SO
5. Now that you have successfully imported your Security Object, you must modify the Padding Policy to include Raw (Decryption only). Figure 11: Padding policy

Details of Fortanix DSM Used in Imperva

Provide Imperva the following from Fortanix DSM.

• Data Security Manager Region(s) -
  At Imperva, Fortanix regions are called hostnames.
  The hostname is the address that appears in the “COPY URI” link (in the security object detailed view, next to COPY UUID), starting with subdomain API.
  The available hostnames (regions) on Fortanix: api.amer.smartkey.io, api.eu.smartkey.io, api.uk.smartkey.io, api.apac.smartkey.io, api.au.smartkey.io Figure 12: Copy URI
• REST API Key(s):
  • This was created in step 3 in the previous section. Figure 13: Copy API key
• UUID of the created Security Object (that is, RSA Key).
  • This was created in step 4 in the previous section. Figure 14: Copy UUID
    NOTE

    Rotate Key is not supported today with regards to Imperva Cloud WAF integration.

To summarize:
Together with the custom certificate, you will need to provide the following information from Fortanix DSM GUI as explained above.

Use the following APIs to provision:

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- your Imperva Site ID.
         Query Parameters: certificate: certificate string in base64. 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 in 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 key>
          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.