Fortanix Data Security Manager with Imperva Cloud WAF

1.0 Introduction

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

2.0 Initial Fortanix DSM Setup

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 key available in multiple regions to provide faster TLS handshakes (the speed of the handshake depends on the distance between Imperva’s edge proxies and the nearest DSM SaaS region).

  1. Sign up for Fortanix DSM SaaS by following this guide.
  2. After signing up go to https://amer.smartkey.io and log in. This opens DSM SaaS for the AMER region. DSM SaaS supports multiple regions, as listed here.
    Image
    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.
    Image
    Figure 2: Fortanix DSM SaaS Dashboard
  3. 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 of the group (optional).
      Image
      Figure 3: Create Group
      Image
      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.
      Image
      Figure 5: Group Detailed View
  4. Create an application (API Key).
    Add Imperva Cloud WAF as an application to the group created in Step 3 in Section- Initial Fortanix DSM Setup. The API application will only have access within the parameters of the group that it is associated with. In this case, the API application will not have access to any groups or security objects that are in addition to your main account.
    An application can use Fortanix 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, and so on. An application can interact with Fortanix 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 (the group was created in Step 3 in Section- Initial Fortanix DSM Setup).
    Image
    Figure 6: Create an App
  5. Create or import a new security object (UI).
    1. Add a security object.
      Image
      Figure 7: Add Security Object
    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 cryptographic key that you will be importing.
      Image
      Figure 8: Create Security Object
    6. Select the value format of Base64 and upload or paste the RSA key in the text box.
    7. Select or clear the permitted key operations for this security object. 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.
  6. Now that you have successfully imported your security object, you must modify the Padding Policy to include Raw (Decryption only).
    Image
    Figure 9: Padding Policy

3.0 Details of Fortanix DSM Used in Imperva

Provide Imperva with 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 the 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
    Image
    Figure 10: Copy URI
  • REST API Key(s):
  • UUID of the security object created (that is, RSA Key).
    • This was created in Step 5 in Section- Initial Fortanix DSM Setup.
      Image
      Figure 13: Copy UUID
      NOTE
      Rotate Key is not supported today for 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.

host_name (Region) key_id (Key UUID) api_key Object Name
api.amer.smartkey.io UUID1 API1 mycompany.com web certificate.US
api.au.smartkey.io UUID2 API2 mycompany.com web certificate.AUS

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

Comments

Please sign in to leave a comment.

Was this article helpful?
0 out of 0 found this helpful