Edge Encryption/Decryption for DataSync Agent

The DataSync Agent can be configured to decrypt messages that have been published from a ServiceNow instance that is leveraging the ServiceNow Edge Encryption feature. Perspectium provides support for the Standard AES-128 and Standard AES-256 options.

What's on this page?

Prerequisites

First, you will need to set up one of the Perspectium DataSync Agents.

You should stop running your DataSync Agent before making any Agent configuration changes.

Edge Encryption

In order to enable support for Edge Encrypted replicated data you must obtain configuration information that was defined in your ServiceNow 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 following table shows which proxy configuration directives are required and the associated replicator agent configuration directive.

Edge Proxy directive	Agent directive
edgeencryption.encrypter.static.iv	initialization_vector
keystore password	keystore_password
edgeencryption.proxy.signature.keystore.keyalias	keystore_alias
edgeencryption.proxy.signature.keystore.password	alias_password

With this information available add the following configuration directives to your task definition within your agent.xml file:

<?xml version="1.0" encoding="ISO-8859-1" standalone="no"?>
<config>
    <agent>
        <subscribe>
            <task>
                <task_name>example_subscribe</task_name>
                    <keystore_password>KEYSTORE_PASSWORD_GOES_HERE</keystore_password>
                    <keystore_alias>KEYSTORE_ALIAS_GOES_HERE</keystore_alias>
                    <alias_password>ALIAS_PASSWORD_GOES_HERE</alias_password>
                    <initialization_vector>INITIALIZATION_VECTOR_GOES_HERE</initialization_vector>
                .
                .
                .
                .  
            </task>
        </subscribe>
    </agent>
</config>

Additionally, you must obtain the keystore used by the ServiceNow proxy and place it within a directory called keystore within the Agent's root directory. The keystore file must be named keystore.jceks.

↑ Go to top of page

Edge Decryption

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)
Keystore containing the encryption key must be saved locally or in an Azure Key Vault

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

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

<?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_interval>60</polling_interval>
            <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

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

<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

<?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_interval>60</polling_interval>
            <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>

↑ Go to top of page

Content

Space Tools

Prerequisites

Edge Encryption

Edge Decryption

Can't find what you're looking for?

See the FAQ or browse the Perspectium Community Forum.