The DataSync Agent provides a plugin to support decrypting data that is edge encrypted. In order to enable support for Edge Encrypted replicated data you must obtain configuration information that was defined decrypt this, you will need the following:
- Edge Encryption enabled in your ServiceNow instance
- Edge
proxy configuration file edgeencryption.properties. The exception is the keystore password you created when you created the keystore. Once this information is available you'll use that information to populate your DataSync Agent's task configuration. The Edge Decryption plugin will decrypt Edge Encrypted replicated datas when shared to the DataSync Agent. In order to support decryption, you will need the following:
Edge Encryption enabled in your ServiceNow instance Set up the encryption configurations (see above, Edge Encryption)- Encryption proxy server installed and configured
- Keystore containing the encryption key used for Edge Encryption. This keystore can be stored in an Azure Key Vault cloud key management or stored locally on a filesystem the Agent as access to.
With this information available, add the following configuration directives to your task definition within your agent.xml file:
UI Text Box |
---|
|
All attributes are required to access the keystore from the Azure Key Vault. |
For Azure Key Vault, add the following:
Directive | Parameters | Required? | Example Value |
---|
<plugin> | Plugin that will decrypt Edge Encrypted replicated data. Parameter | Description |
---|
keystore | Specifies where the keystore is located. Value: azure | vault_tenant | tenant_id for the Azure Key Vault containing the keystore* | vault_url | URL to the Azure Key Vault* | vault_principal | principal_id for the Azure Key Vault* | principal_secret | password for the Azure Key Vault* | secret_name | Name of the keystore^ | keystore_password | password for the keystore^ | keystore_alias | Name of the key alias^ | alias_password | Password for the key^ |
*See Authentication in Azure Key Vault for more information on these configurations. ^See Edge Encryption properties for more information on these configurations.
|
Keystore containing the encryption key must be saved locally or in an Azure Key VaultWith this information available, add the following configuration directives to your task definition within your agent.xml file:
UI Text Box |
---|
|
All attributes are required to access the key vault and open the keystore from the Azure vault. |
If the keystore containing the encryption key is saved in an Azure Key Vault, add the following:
Directive | Parameters | Required? | Example Value |
---|
<plugin> | Plugin that will decrypt Edge Encrypted replicated datas. Parameter | Description |
---|
keystore | Specifies where the keystore is located. Value: azure | vault_tenant | tenant_id for the vault containing the keystore | vault_url | URL to the Azure KeyVault | vault_principal | principal_id for the KeyVault | principal_secret | password for the KeyVault | secret_name | Name of the keystore | keystore_password | password for the keystore | keystore_alias | Name of the key alias | alias_password | Password for the key |
Code Block |
---|
<config>
<agent>
<subscribe>
<task>
...
<plugin keystore="azure"
vault_tenant="VAULT_TENANT_GOES_HERE"
vault_url="VAULT_URL_GOES_HERE"
vault_principal="VAULT_PRINCIPAL_GOES_HERE"
principal_secret="PRINCIPAL_SECRET_GOES_HERE"
secret_name="SECRET_NAME_GOES_HERE"
keystore_password="KEYSTORE_PASSWORD_GOES_HERE"
keystore_alias="KEYSTORE_ALIAS_GOES_HERE"
alias_password="ALIAS_PASSWORD_GOES_HERE">com.perspectium.replicator.sql.plugin.SQLSubscriberDecryptColumnPlugin</plugin>
</task>
</subscribe>
</agent>
</config> |
| Yes | See example below. |
Example of a complete agent.xml configuration with the keystore in an Azure Key Vault
Code Block |
---|
|
<?xml version="1.0" encoding="ISO-8859-1" ?>
<config>
<agent>
<max_reads_per_connect>1</max_reads_per_connect>
<polling_interval>5</polling_interval>
<test_mode/>
<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="USER" password="PASSWORD" queue="psp.out.replicator.dev1234">https://URL.perspectium.net</message_connection>
<use_cache/>
<instance_connection user="USER" password="PASSWORD">https://dev1234.service-now.com</instance_connection>
<database_type>sqlserver</database_type>
<database_port>1234</database_port>
<database_server>SERVER_URL</database_server>
<database_user>USER</database_user>
<database_password>PASSWORD</database_password>
<database_parms>lockTimeout=15000;queryTimeout=15</database_parms>
<database>DATABASE_NAME</database>
<skip_columns_log_interval>200</skip_columns_log_interval>
<plugins>
<plugin keystore="azure"
vault_tenant="12345678-ab12-ab12-ab12-123456789ab"
vault_url="https://url.vault.azure.net/"
vault_principal="12345678-ab12-ab12-ab12-123456789ab"
principal_secret="3213156165-adasdasd_a1s5d6a5s1d6a"
secret_name="some_secret_name"
keystore_password="efg123"
keystore_alias="128bitkey"
alias_password="abc123">com.perspectium.replicator.sql.plugin.SQLSubscriberDecryptColumnPlugin</plugin>
</task>
</subscribe>
<share>
<task>
<task_name>attachment_processor</task_name>
<handler>com.perspectium.replicator.sql.subscriber.edge.SysAttachmentHandler</handler>
<encryption_key>some_encryption_key_here</encryption_key>
</agent>
</config> |
If the keystore containing the encryption key is saved locally in the filesystem that the Agent has access to, add the following:
Directive | Description | Required? | Example Value |
---|
<plugin> | Plugin that will decrypt Edge Encrypted replicated data. Parameter | Description |
---|
keystore | Specifies where the keystore is located. Value: local | keystore_path | File path to the keystore^ | keystore_password | Password for the keystore^ | keystore_alias | Name of the key alias^ | alias_password | Password for the key^ |
^See Edge Encryption properties for more information on these configurations.
Code Block |
---|
<config>
<agent>
<subscribe>
<task>
...
<plugin keystore="local"
|
|
<message_connectionuser="USER" password="PASSWORD" queue="psp.out.replicator.dev5678">https://URL.perspectium.net</message_connection> keystore_path="KEYSTORE_PATH_GOES_HERE"
|
|
<polling_interval>60</polling_interval> keystore_password="KEYSTORE_PASSWORD_GOES_HERE"
|
|
<max_writes_per_connect>1</max_writes_per_connect>
<skip_queue/>
<skip_report/>
<topic>topic_here</topic>
<type>type_here</type>
<key>key_here</key>
<name/>
<database_type>sqlserver</database_type>
<database_port>1234</database_port>
<database_server>SERVER_URL</database_server>
<database_user>USER</database_user>
<database_password>PASSWORD</database_password>
<database_parms>lockTimeout=15000;queryTimeout=15</database_parms>
<database>DATABASE_NAME</database>
<edge_encryption
keystore="azure"
vault_tenant="12345678-ab12-ab12-ab12-123456789ab"
vault_url="https://url.vault.azure.net/"
vault_principal="12345678-ab12-ab12-ab12-123456789ab"
principal_secret="3213156165-adasdasd_a1s5d6a5s1d6a"
secret_name="some_secret_name"
keystore_password="efg123"
keystore_alias="128bitkey"
alias_password="abc123">true</edge_encryption>
</task>
</share>
</agent>
</config>If the keystore containing the encryption key is saved locally, add the following:
Directive | Description | Required? | Example Value |
---|
keystore_alias="KEYSTORE_ALIAS_GOES_HERE"
alias_password="ALIAS_PASSWORD_GOES_HERE">com.perspectium.replicator.sql.plugin.SQLSubscriberDecryptColumnPlugin</plugin>
</task>
</subscribe>
</agent>
</config> |
| Yes | See example below. |
Example of a complete agent.xml configuration with the keystore in a local filesystem the Agent has access to:
Code Block |
---|
|
<?xml version="1.0" encoding="ISO-8859-1" ?>
<config>
<agent>
<max_reads_per_connect>1</max_reads_per_connect>
<polling_interval>5</polling_interval>
|
<plugin> | Plugin that will decrypt Edge Encrypted replicated datas.
Parameter | Description |
---|
keystore | Specifies where the keystore is located. Value: local. |
keystore_path | File path to the keystore |
keystore_password | Password for the keystore |
keystore_alias | Name of the key alias |
alias_password | Password for the key |
Code Block |
---|
<config>
<agent>
<subscribe>
<task>
...
<plugin keystore="local"
keystore_path="KEYSTORE_PATH_GOES_HERE"
keystore_password="KEYSTORE_PASSWORD_GOES_HERE"
keystore_alias="KEYSTORE_ALIAS_GOES_HERE"
alias_password="ALIAS_PASSWORD_GOES_HERE">com.perspectium.replicator.sql.plugin.SQLSubscriberDecryptColumnPlugin</plugin>
</task>
</subscribe>
</agent>
</config> |
Yes | See example below. | Example of agent.xml
Code Block |
---|
|
<?xml version="1.0" encoding="ISO-8859-1" ?>
<config>
<agent>
<max_reads_per_connect>1</max_reads_per_connect>
<polling_interval>5</polling_interval>
<test_mode/>
<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="USER" password="PASSWORD" queue="psp.out.replicator.dev1234">https://URL.perspectium.net</message_connection>
<use_cache/>
<instance_connection user="USER" password="PASSWORD">https://dev1234.service-now.com</instance_connection>
<database_type>sqlserver</database_type>
<database_port>1234</database_port>
<database_server>SERVER_URL</database_server>
<database_user>USER</database_user>
<database_password>PASSWORD</database_password>
<database_parms>lockTimeout=15000;queryTimeout=15</database_parms>
<database>DATABASE_NAME</database>
<skip_columns_log_interval>200</skip_columns_log_interval>
<plugins>
<plugin keystore="azure"
vault_tenant="12345678-ab12-ab12-ab12-123456789ab"
vault_url="https://url.vault.azure.net/"
vault_principal="12345678-ab12-ab12-ab12-123456789ab"
principal_secret="3213156165-adasdasd_a1s5d6a5s1d6a"
secret_name="some_secret_name"
keystore_password="efg123"
keystore_alias="128bitkey"
alias_password="abc123">com.perspectium.replicator.sql.plugin.SQLSubscriberDecryptColumnPlugin</plugin>
</task>
</subscribe>
<share>
<task>
<task_name>attachment_processor</task_name>
<handler>com.perspectium.replicator.sql.subscriber.edge.SysAttachmentHandler</handler>
<encryption_key>some_encryption_key_here</encryption_key>
<message_connection user="USER" password="PASSWORD" queue="psp.out.replicator.dev5678">https://URL.perspectium.net</message_connection>
<polling<test_interval>60</polling_interval>mode/>
<subscribe>
<max_writes_per_connect>1</max_writes_per_connect>
<task>
<skip<polling_queueinterval>5</>polling_interval>
<skip_report/> <task_name>oracle_subscriber_automated_test</task_name>
<topic>topic_here</topic>
<handler>com.perspectium.replicator.sql.SQLSubscriber</handler>
<type>type_here</type>
<key>key<decryption_key>some_decryption_key_here</decryption_key>
<name/>
<message_connection user="USER" <database_type>sqlserver</database_type>
password="PASSWORD" queue="psp.out.replicator.dev1234">https://URL.perspectium.net</message_connection>
<database_port>1234</database_port>
<database_server>SERVER_URL</database_server><use_cache/>
<database_user>USER</database_user>
<instance_connection user="USER" password="PASSWORD">https://dev1234.service-now.com</instance_connection>
<database_password>PASSWORD</database_password>
<database_parms>lockTimeout=15000;queryTimeout=15<type>sqlserver</database_parms>type>
<database>DATABASE_NAME</database>
<database_port>1234</database_port>
<edge_encryption
<database_server>SERVER_URL</database_server>
keystore="azure"
<database_user>USER</database_user>
vault_tenant="12345678-ab12-ab12-ab12-123456789ab"
<database_password>PASSWORD</database_password>
vault_url="https://url.vault.azure.net/"
<database_parms>lockTimeout=15000;queryTimeout=15</database_parms>
<database>DATABASE_NAME</database>
vault_principal="12345678-ab12-ab12-ab12-123456789ab<skip_columns_log_interval>200</skip_columns_log_interval>
<plugins>
<plugin keystore="local"
principal_secret="3213156165-adasdasd_a1s5d6a5s1d6a keystore_path="abcdefg"
keystore_password="efg123"
secret_name="some_secret_name"
keystore_password="efg123"
keystore_alias="128bitkey"
alias_password="abc123">true</edge_encryption>>com.perspectium.replicator.sql.plugin.SQLSubscriberDecryptColumnPlugin</plugin>
</task>
</share>subscribe>
</agent>
</config> |