The DataSync Agent can be configured to decrypt ServiceNow records with data encrypted using Edge Encryption. Perspectium provides support for records encrypted using the AES-128 and AES-256 options.
The DataSync Agent provides a plugin to support decrypting data that is edge encrypted. In order to decrypt this, you will need the following:
- Edge Encryption enabled in your ServiceNow instance
- Edge 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:
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.
<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. |
Click here to see example of a complete agent.xml configuration with the keystore in an Azure Key Vault......
<?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>
</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.
<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. |
Click here to see example of a complete agent.xml configuration with the keystore in a local filesystem the Agent has access to..
<?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="local"
keystore_path="abcdefg"
keystore_password="efg123"
keystore_alias="128bitkey"
alias_password="abc123">com.perspectium.replicator.sql.plugin.SQLSubscriberDecryptColumnPlugin</plugin>
</task>
</subscribe>
</agent>
</config>
If you want to use attachment handling with edge encryption so the attachments are each saved as a complete file, see Merging Attachments in the Database.