Skip to content

Installation Guide

Pre-requisites

  • OS: Linux (RHEL/Rocky -- 9 -- /Ubuntu -- 20,22,24 -), Windows Server 2019/2022.

  • CPU: minimum 4 vCPU

  • RAM: 8 GB

  • Disk: 1 GB available

  • Architecture: 64-Bit

  • Java runtime: java jdk/jre 17+ (tested on Oracle Java / OpenLogic-OpenJDK)

  • Tomcat 11: package delivered in a compressed Tomcat 11

Package

A zip file is delivered with the already program packages installed that are composed by:

  • Tomcat 11:

  • SQLProxyWS: Core BIP Proxy

  • Proxy-Config-Manager: Web Interface for managing SQLProxyWS parameters

Enforcement of key and credentials

Create the following credentials and policies in KMS (CipherTrust Manager):

Create administrative credentials in KMS for the BIP SQL Proxy

  • Create a user and password (that will be designed to be admin of the new domain)

Tip

Go to Access Management -> Users, and click on "Add User", then fill out the parameters "Full Name", UserName (can be the same of "Full Name"), Password, Password Match, and then click on "Add User"

  • Create a Domain and assign the above user as administrator of that Domain

Tip

Go to "Admin Settrings" -> Domains, and click on "Add Domain", in the Add Domain dialog, fill out the form by setting "Name" (domain name), "Admins" (select the recently created user to be admin of that Domain), "Parent CA" (Select the default CA or if there is another configured), and check on "Allow Subdomain user Management" (this is very necessary to create the credential to be used by the BIP SQL Proxy.).

Create the application credentials and policies for BIP SQL Proxy

  • Login as Domain admin using the credentials created in the above procedure

  • Limit the IP addresses from where this credential will connect from:

Tip

For this, it is necessary to use the CipherTrust API Playground, since a new policy will be created.

  • At the top bar click on "API" and a new browser tap will be opened already authenticated.

  • On the left panel write in the search textbox the word "Policies" and scroll down to the section named just "Policies".

  • Click on the option "create" under /v1/admin/policies/

  • In the middle of the panel, there is a textbox named "body \<body>", modify the "values" to your list of IP addresses.

{
  "name": "AllowIPFromSQLProxyOnly",
  "effect": "deny",
  "resources": [],
  "actions": [ "IssueJWT"],
  "conditions": [  {
            "negate":true,
            "op": "equals",
            "path": "context.environment.client_ip",
            "values": [
               "192.168.0.125, 192.168.1.48"
            ]
        }]
}
  • Click on blue button "POST", and check a 201/200 response is received, at that point the policy has been created.
  • Create a new user (this will be the credential to be provided later to the BIP SQL Proxy)

Tip

Go to "Admin Management" -> Users, and click "Add User" and fill the form specifics fields (full name/Username/Password/Password Match); Uncheck the option "Allow user to login using CipherTrust web app", since this user will be used only from application accessing.

  • Create a group to assign to attach the above policy.

Tip

Go to "Access Management" -> Groups, and then click on "Create New Group", follow the below instructions.

  • Set a name and click Next

  • Select the user recently created (not the administrator user) just the user that will be provided to the BIP Proxy SQL and click Next.

  • Click on "Add Group"

  • Go again to the API Playground browser tab to attach the policy to the recently created group.

Tip

In the top-left search box write "policy attachments", and the section "Policy Attachments" will appear, click on the "Attach" below of /v1/admin/policy-attachments/, and in the center of the page paste the below json.

{
   "policy": "AllowIPFromSQLProxyOnly",
   "principalSelector": {
      "cust": {
         "groups": [
            "AllowedIPs"
         ]
      }
   }
}

  • Click on blue button "Post" and check that a 201/200 http code response has been produced.

  • Go to the CipherTrust Web application and assign the app user to the following groups.

Tip

Go to "Access Management" -> Users, and click on the name of the app user (below the column Username), click in "GROUP MEMBERSHIPS" and click on button "+Add group", in the top search box write the groups "Key Users" and "AllowedIPs" and click on the checkbox in each one by clicking on the blue button in the bottom-right "Add Group", that way the app user is limited only to consume keys and objects and can access only from the IP addresses defined for the BIP SQL Proxy.

Create the parameters-objects to be used for the BIP SQL Proxy

As the BIP SQL Proxy requires certain credentials type, instead of persist that information in the config.properties file in Tomcat, it will leverage the KMS vault to store sensitive information as a security approach, for that reason the following objects must be created.

Encryption key

The encryption key to be used for protecting columns in tables designed to be protected.

Tip

Go to "Keys" and click on "Add Key", then fill the field "Key Name" and click Next, the Algorithm and Size are already selected (AES 256), click Next, and click "Add Key".

Assign permissions to use the Encryption key to the group "Key Users" (where APP user belongs to)

Tip

Go to "Keys" and click on the Encryption Key Name recently created, go to "KEY ACCESS" area, in tab "General" area select the toggle on the right "Show All Groups" and in the search box above write "Key Users" and check the right check button called "All" and press the blue button "Update" and move to the left the toggle button, that way, both Admin and "Key Users" group has access to the key.

Additional object parameters

The following objects must be created as a secret objects within the CipherTrust Manager, as these secrets will contain sensitive information needed by the BIP SQL proxy.

  • DB_PASSWORD: this will contain the password for the DB user needed to start the SQL SERVER connection pool and for encrypt existing data and new incoming data.

  • CADP_PASSPHRASE_CACHE_KEY: in case of using CipherTrust Application Data Protection connector, this value will protect the encryption key when in file cache form.

  • CADP_IV: in case of using CipherTrust Application Data Protection connector, and using AES-CBC encryption, this is the Initialization Vector (IV) that will be use along with the encryption key (for encrypt/decrypt).

  • TWEAK: This value is used as part of encryption method FPE.

The above four secrets will be created in the API Playground using the bellow instructions

  1. Go to API Playground and in the left search box write "secrets"

  2. Click under the Section "Secrets" in the option "create" under /v1/vault/secrets

  3. In the center area of the page paste the below json

{
  "name": "DB_PASSWORD",
  "dataType": "seed",
  "material": "password123!"
}

Info

Do the same for the other three parameters.

Warning

Not adding the parameters will have the effect of BIP SQL server will not be able to start the SQL Pool threads and the encryption will no work.

Assign permissions to use the secret objects to the group "Key Users" (where APP user belongs to)

Tip

Go to "Keys" and click on each of the secrets objects name recently created, go to "KEY ACCESS" area, in tab "General" area select the toggle on the right "Show All Groups" and in the search box above write "Key Users" and check the right check button called "All" and press the blue button "Update" and move to the left the toggle button, that way, both Admin and "Key Users" group has access to the key.

Unzip and apply the initial configuration in config.properties

As the delivery package comes within a Tomcat preconfigured, the procedure to start initial configuration is based on unzip and review/modify configuration in config.properties file.

  • Unzip the compressed file delivered to you e.g.: apache-tomcat-11.0.9.zip

Linux

unzip apache-tomcat-11.0.9.zip

Windows

Expand-Archive -LiteralPath \'apache-tomcat-11.0.9.zip\' -DestinationPath C:\\apache-tomcat-11.0.9
  • Go to the unzipped path \<unzipped path>\apache-tomcat-11.0.9\webapps\sql-proxy\WEB-INF\classes and edit the config.properties and configure the parameters as explained above of each parameter
#SQL server host/IP where the data will be encrypted
SQL_SERVER_HOST=192.168.0.85
#SQL server por to forward packets from BOP Proxy SQL
REMOTE_PORT=1433
#Port to serve to SQL clients
LOCAL_PORT=1473

#DB JDBC URL CONNECTION FOR ASYNCRONOUS INSERTIONS - credential must have permissiosn for inserts/updates
JDBC_URL=jdbc:sqlserver://192.168.0.85:1433;databaseName=AdventureWorks2019;encrypt=false;trustServerCertificate=true
DB_USER=sa
DB_PASSWORD=[DB_PASSWORD]

#CADP properties
CADP_PROPERTY_FILE=G://SQLProxyWS//resources//CADP_for_JAVA.properties
CADP_CREDENTIALS.user=appuserkms
CADP_CREDENTIALS.password=kmsappapaswer123!
CADP_KEK_ID=sqlproxykey
#POSSIBLE VALUES THALES CADP = CADP | BOUNCYCASTLE = BC
CRYPTO_PROVIDER=BC

#THALES CADP SECTION SPECIFICS 
#IT MUST BE A 128 BITS (16 BYTES IN HEXA STRING) - actually 15 characters
#IS IN PROTERTY COLLECTION  - between [] is the variable name in CipherTrust Manager 
CADP_PASSPHRASE_CACHE_KEY=[CADP_PASSPHRASE_CACHE_KEY]
#In case of using CADP (hexastring of 16 character length) - between [] is the variable name in CipherTrust Manager
CADP_IV=[CADP_IV]

#COMMON FOR CADP AND BC (hexastring larger than 16 characters)- between [] is the variable name in CipherTrust Manager
TWEAK=[TWEAK]

#SPECIFIC FOR BC 
# TLS VERIFICATION values VERIFY or NO_VERIFY
BC_KMS_API_TLS_CONNECTION=NO_VERIFY
#KMS -only supported CIPHERTRUST MANAGER
KMS_DOMAIN=kmsdomainenterprise.com


#VALUES YES or NO | DEFAULT: YES if incorrect value or omitted 
#IF YES: ALL TABLES.COLUMNS IN PARAMETER TABLEFIELDSTOPROTECT WILL BE ENCRYPTED 
#IF NO: ALL TABLES.COLUMNS IN PARAMETER TABLEFIELDSTOPROTECT WILL BE DECRYPTED - USE WHEN ENCRYPTION IS NOT REQURED ANYMORE
ENCRYPT=YES
#possible values for ENCRYPTMODE: NORMAL or FPE (MUST BE IN UPPERCASE otherwise will not work) | for BC (BouncyCastle ONLY FPE IS SUPPORTED
ENCRYPT_MODE=FPE


#Permissions #IS IN PROTERTY COLLECTION
#ENCRYPTUSERALLOWED=sa#production
ENCRYPTUSERALLOWED=produccion#GoDynasty707
DECRYPTUSERALLOWED=produccion#GoDynasty707
#EVERY TABLE-COLUMN MUST BE SEPARATED BY # IN THE FORM <SCHEMA>.<TABLE>.<COLUMN>.<TYPE> EX. DBO.TABLE1.COLUMN1.A#SALES.TABLE2.COLUMN2.N ETC
#TYPE CAN BE: A = ALFANUMERIC ; N = NUMERIC ; D = DATE ; M = NUMERIC TO BE USED WITH PREFIX 100000
TABLEFIELDSTOPROTECT=person.person.firstname.a#person.person.lastname.a#sales.creditcard.cardnumber.a#person.personphone.phonenumber.a#person.personphone.phonenum.a#person.emailaddress.emailaddress.a#humanresources.vemployeedepartment.firstname.a#humanresources.vemployeedepartment.lastname.a#production.product.standardcost.n#production.product.listprice.n#sales.salesperson.salesytd.n#sales.salesperson.saleslastyear.n

#TINY HTTP SERVER FOR RECEIVING UPDATES PARAMETERS IN MEMORY
HTTP_SRV_PARAM_UDATES_PORT=9091

#FILE PATH TO BE USED TO CHECK IF A TABLE HAS UNENCRYPTED DATA
FILE_CHECK_UNENCRYPTED_DATA=C:\\ProgramData\\SQLProxy\\checknotencrypted
#START THREAD FOR CHECKING PERIODICALLY FOR UNENCRYPTED DATA 
LIVE_CHECK_UNENCRYPTED_DATA=TRUE
LIVE_CHECK_FILE_UNENCRYPTED_DATA=C:\\ProgramData\\SQLProxy\\livecheck
LIVE_CHECK_TIMER=5000
LIVE_BATCH_SIZE=1000

#PARAMETER KEY ENCRYPTION NAME (FOR DECRYPTING PASSWORD AND OTHER SENSITIVE PROPERTY INFORMATION)
PARAMETER.KEY=NONAME

#HIKARI CONFIG - SQL CONNECTIONS FOR DECRYPTING DATA 
MAXIMUMPOOLSIZE=20
MINIMUMIDLE=5

Tip

Following paths must be created manually

  • Windows: C:\ProgramData\SQLProxy

  • Linux: /etc/sqlproxy

Provide the corresponding permissions to the user defined to run Tomcat

Initial startup and licensing

After initial config.properties file configuration, is time to start tomcat by running the following commands

Start Tomcat

Linux

./catalina.sh start

Windows

.\\catalina.bat start

Check Tomcat is running

You can open Tomcat by accessing at http://localhost:8080

Tip

Even when is http access, sensitive parameters can not be modified or handled this interface, just the Proxy-Config-Manager to modify on the fly non-sensitive parameters.

Check in initial logs output for the following:

  • Port for TCP proxy opened confirmation
? Starting TCP Proxy Server on port 1473\...
  • Sensitive parameters loaded from KMS (CipherTrust Manager) confirmation
02-Nov-2025 23:19:31.456 INFO \[Thread-1\] SQLSecurityProxy.main \[PROXY ACTIVITY\] \| ID=PRX-011 concept=\'Loading sensitive parameters from KMS\' value=\'Loading DB_PASSWORD, CADP_PASSPHRASE_CACHE_KEY, CADP_IV and TWEAK from KMS from KMS succeded\' user=\'N/A\'
  • Encryption key fetched from KMS confirmation
02-Nov-2025 23:19:34.176 INFO \[Thread-1\] controllers.bc.FipsFpe.bootstrap \[PROXY ACTIVITY\] \| ID=PRX-007 concept=\'Fetching authenticated key from KMS with BC FIPS mode ON\' value=\'BC fips mode on: true\' user=\' \'

Tip

Above three logs output confirm that BIP SQL Proxy has started successfully.

Generate the licensing request json

  • Open in the browser the below uri
<http://localhost:8080/sql-proxy/license/challenge>

Tip

It will prompt for a credential, you should find that credential at \<Unzipped Tomcat path>/apache-tomcat-11.0.9\conf\tomcat-users.xml where there are several users, use the user and password for username licadmin.

After hitting the url, a json response will be generated similar to the below output

{
  "challenge": "F+iSiAGupSSKDNocrnduncb43qiLXNDmkMyDzxjfCxxLcsynJn5gMO+FOpAQrPxssA2ymIBdmhChKPwJCKx9StzG3gjm341iJl6JDo6fQl4pAyt3DgQKAhre+gulUGelNLzHukeWkhK1+UEFBVjPYJjy9szj5IIGJpfJToEMZCLAvFIJufZaYsJcY9eSQkbXf6+1wY/KObIXIYRYhhEBPlRLRlOuVwg1gmVWUB2HGDrVNjsAodnDXpuXvU9ucNTSXjVPpMsaCDzHrkUrSylnb2Mch5glfZW3UY0rJInX0DBwionDBg3bPRgx/qsaAKWHcQOtCzN0Ds/oPdrlbSNkgynw5VC2ySFuOyXVZeoCbekh/pty/iOhrwMXemSwQ0sWOG5afZ7O5f+tYbWggwwE2ovT2uC7YBDOGXFItWQwgRLMoOHLyuc77VjSQAh1aELuUaBA77DxZfRviHsLVR+W+sGnJ9zD4xYBTxjCpaACX7yUD7I/oLTpPNWCcLPnnt+31PLbmQUD5rui3LP4lZs3Pns5xXDDzSFZdpM0p6DmiHf/H48hr0IGjYc4C8rkRK/kHo0x1BSt9YpxcgHOE8MCZgLGfRREnmm/k7ZwrUYKRUXo1ukxxhvcn1pVoHUo+aGzJziEHhZOa2mhGxTg5/wG4r89vuQ59J98XWCy82+2i7U="
}

Send that output to the Bitarq support team, to generate the final file license.

Warning

You must change the passwords of each user aligned with internal policies, and/or configure a Tomcat realm to configure an AD or LDAP credential management.

<role rolename="manager-gui"/>
<role rolename="admin-gui"/>
<user username="admin" password="changeme123!" roles="manager-gui,admin-gui"/>
<role rolename="proxy-admin"/>
<user username="proxyadmin" password=" changeme123!" roles="proxy-admin"/>
<role rolename="app-user"/>
<user username="licadmin" password=" changeme123!" roles="app-user"/>

Installing the license

Copy content of the license.jwt received in the server where BIP SQL Proxy is running into the file either at:

Windows: "C:\ProgramData\SQLProxy\license.jwt"

Linux: "/etc/sqlproxy/license.jwt"

Tip

  • No need to restart the Tomcat server, BIP SQL Proxy will load the license immediately.
  • After loading the valid license, log errors about "Licensing verification failed" stop.

Warning

BIP SQL proxy starts sending logs of expiration as a warning 10 days prior to the expiration day and critical errors 5 days prior to the expiration day.