Feature available in Helium 6.0.2 release
The DataSync Agent plugin architecture allows the agent to modify inbound payloads before the data is inserted into a database or saved to a file. Thus, encrypting specified values using Voltage encryption can be applied before inserting the row into your database. When you specify the list of tables and column names in the encrypt_columns parameter in the format of <table>:<column>;<table>:<column>;etc., i.e. incident:comments, the plugin will encrypt these specific columns that contain sensitive information for your infrastructure to decrypt and process themselves.
NOTE: This is a custom feature for a specific use case to encrypt data saved using the Voltage API before saving it into the database. Contact Perspectium Support for more information.
Prerequisites
First, you will need to set up one of the Perspectium DataSync Agents.
You should also stop running your DataSync Agent before making any Agent configuration changes.
Procedure
To start using the Voltage API in your DataSync Agent, follow these steps:
Navigate to the directory where you saved your agent.xml file when installing your DataSync Agent.
Open your agent.xml file in a text editing application. Then, add the following attributes within the plugin directive:
| Parameters | Description | Required? |
|---|---|---|
url | REST url endpoint | Yes |
trace_id | Identifier for each request made to the API | No. If empty or not included, a GUID will be generated for each request otherwise all requests will use the specified trace_id. |
app_name | Name of the application, i.e. Perspectium Agent | Yes |
host_name | If empty or not included, then host_name will be set to the name of the computer/machine running the agent | No |
identity | Identifier for application using the API | No |
shared_secret | Secret phrase shared between clients using API | Yes |
encryption_type | Encryption method, i.e. AES = 3 | Yes |
encrypt_columns | List of tables and columns to be encrypted by the Voltage API. Lists need to be in the following format: | Yes |
In the <plugin> directive, add the following value: com.perspectium.replicator.sql.plugin.SQLSubscriberVoltageEncrypterPlugin.
<plugin url="https://example.com/api" trace_id="" app_name="agent" host_name="psp" identity="" shared_secret="secret" encryption_type="3" encrypt_columns="u_edge_testing:u_test_column1,u_edge_testing:u_notes,incident:comments">com.perspectium.replicator.sql.plugin.SQLSubscriberVoltageEncrypterPlugin</plugin>
Example of a complete agent.xml configuration with the Voltage API plugin applied:
<?xml version="1.0" encoding="ISO-8859-1" ?>
<config>
<agent>
<max_reads_per_connect>1</max_reads_per_connect>
<polling_interval>5</polling_interval>
<subscribe>
<task>
<polling_interval>5</polling_interval>
<task_name>oracle_subscriber_automated_test</task_name>
<handler>com.perspectium.replicator.sql.SQLSubscriber</handler>
<decryption_key>Some decryption key here</decryption_key>
<message_connection user="demo" password="demo" queue="psp.out.replicator.agent.example">https://example.perspectium.net</message_connection>
<use_cache/>
<instance_connection user="demo" password="demo">https://exmaple.service-now.com</instance_connection>
<database_type>sqlserver</database_type>
<database_server>localhost</database_server>
<database_port>1521</database_port>
<database_user>example</database_user>
<database_password>example</database_password>
<database_parms/>
<database>psp_db</database>
<skip_columns_log_interval>200</skip_columns_log_interval>
<plugins>
<plugin url="https://example.com/api"
trace_id=""
app_name="example"
host_name="psp"
identity=""
shared_secret="example"
encryption_type="3"
encrypt_columns="u_edge_testing:u_test_column1,u_edge_testing:u_notes,incident:comments">com.perspectium.replicator.sql.plugin.SQLSubscriberVoltageEncrypterPlugin</plugin>
</plugins>
</task>
</subscribe>
</agent>
</config>
After configuring your agent.xml, start running your DataSync Agent again.