Page History

Versions Compared

Old Version 11

changes.mady.by.user user-1bc08

Saved on Jul 08, 2021

compared with

New Version Current

changes.mady.by.user user-b885f

Saved on Jul 09, 2021

Key

This line was added.
This line was removed.
Formatting was changed.

AnchorTopTopThe DataSync Agent can be configured to decrypt

messages that have been published from a ServiceNow instance that is leveraging the ServiceNow Edge Encryption feature

ServiceNow records with data encrypted using Edge Encryption. Perspectium provides support for records encrypted using the

Standard

AES-128 and

Standard

AES-256 options.

Panel

title	What's on this page?

Table of Contents

maxLevel	2
absoluteUrl	true

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

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:

UI Text Box

type	note

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

Code Block
<config> <agent> <subscribe> <task> ... <plugin keystore="azure"

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 directiveAgent directiveedgeencryption.encrypter.static.ivinitialization_vectorkeystore passwordkeystore_passwordedgeencryption.proxy.signature.keystore.keyaliaskeystore_aliasedgeencryption.proxy.signature.keystore.passwordalias_password

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

Code Block

language	xml

<?xml version="1.0" encoding="ISO-8859-1" standalone="no"?> <config> <agent> <subscribe>

<task>

    vault_tenant="VAULT_TENANT_GOES_HERE"

<task_name>example_subscribe</task_name>

 vault_url="VAULT_URL_GOES_HERE"

<keystore_password>KEYSTORE_PASSWORD

vault_principal="VAULT_PRINCIPAL_GOES_

HERE</keystore_password>

HERE"

<keystore_alias>KEYSTORE_ALIAS

principal_secret="PRINCIPAL_SECRET_GOES_

HERE</keystore_alias>

HERE"

<alias_password>ALIAS_PASSWORD

secret_name="SECRET_NAME_GOES_

HERE</alias_password>

HERE"

<initialization_vector>INITIALIZATION_VECTOR

keystore_password="KEYSTORE_PASSWORD_GOES_

HERE</initialization_vector>

HERE"

. . . . </task> </subscribe>

 keystore_alias="KEYSTORE_ALIAS_GOES_HERE" 
  				 alias_password="ALIAS_PASSWORD_GOES_HERE">com.perspectium.replicator.sql.plugin.SQLSubscriberDecryptColumnPlugin</plugin>

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

Yes

See example below.

Example of a complete agent.xml configuration with the keystore in an Azure Key Vault

Code Block

language	xml
theme	Eclipse

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

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:

UI Text Box

type	note

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:

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

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>

YesSee example below.

Example of agent.xml

Code Block

language	xml
theme	Eclipse

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

DirectiveDescriptionRequired?Example Value<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"

<message_connection user="USER" password="PASSWORD" queue="psp.out.replicator.dev1234">https://URL.perspectium.net</message_connection>

keystore_password="KEYSTORE_PASSWORD_GOES_HERE"

<use_cache/>

keystore

<instance_

alias

connection user="

KEYSTORE_ALIAS_GOES_HERE" alias_

USER" password="

ALIAS_

PASSWORD

_GOES_HERE">com.perspectium.replicator.sql.plugin.SQLSubscriberDecryptColumnPlugin</plugin> </task> </subscribe> </agent> </config>YesSee example below.

Example of agent.xml

Code Block

language	xml
theme	Eclipse

<?xml version="1.0" encoding="ISO-8859-1" ?>
<config>
    <agent>
">https://dev1234.service-now.com</instance_connection>
                <database_type>sqlserver</database_type>
                <database_port>1234</database_port>
                <database_server>SERVER_URL</database_server>
                <max_reads_per_connect>1</max_reads_per_connect><database_user>USER</database_user>
        <polling_interval>5</polling_interval>
        <test<database_modepassword>PASSWORD</>database_password>
        <subscribe>
            <task><database_parms>lockTimeout=15000;queryTimeout=15</database_parms>
                <polling<database>DATABASE_interval>5<NAME</polling_interval>database>
                <task<skip_columns_name>oraclelog_subscriberinterval>200</skip_automatedcolumns_test</task_name>
log_interval>
				<plugins>
					<plugin keystore="azure"
                     <handler>com.perspectium.replicator.sql.SQLSubscriber</handler>
       vault_tenant="12345678-ab12-ab12-ab12-123456789ab"
         <decryption_key>some_decryption_key_here</decryption_key>
                <message_connection user="USER" password="PASSWORD" queue="psp.out.replicator.dev1234">https vault_url="https://URLurl.vault.perspectiumazure.net<net/message_connection>"
                <use_cache/>
            vault_principal="12345678-ab12-ab12-ab12-123456789ab"
    <instance_connection user="USER" password="PASSWORD">https://dev1234.service-now.com</instance_connection>
                        <database_type>sqlserver</database_type>
principal_secret="3213156165-adasdasd_a1s5d6a5s1d6a"
                     <database_port>1234</database_port>
           secret_name="some_secret_name"
							keystore_password="efg123"
            <database_server>SERVER_URL</database_server>
                <database_user>USER</database_user>keystore_alias="128bitkey"
                <database_password>PASSWORD</database_password>
                <database_parms>lockTimeout=15000;queryTimeout=15</database_parms>alias_password="abc123">com.perspectium.replicator.sql.plugin.SQLSubscriberDecryptColumnPlugin</plugin>
        </task>
        <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</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 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"

principal_secret="3213156165-adasdasd_a1s5d6a5s1d6a"

keystore_path="KEYSTORE_PATH_GOES_HERE"
                keystore_password="KEYSTORE_PASSWORD_GOES_HERE"

secret_name="some_secret_name"

    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

language	xml
theme	Eclipse

<?xml version="1.0" encoding="ISO-8859-1" ?>
<config>
    <agent>		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>
    <max_reads_per_connect>1</max_reads_per_connect>
        <polling_interval>5</polling_interval>
        <encryption_key>some_encryption_key_here</encryption_key><test_mode/>
        <subscribe>
    <message_connection user="USER" password="PASSWORD" queue="psp.out.replicator.dev5678">https://URL.perspectium.net</message_connection>       <task>
                <polling_interval>60<interval>5</polling_interval>
              <max_writes_per_connect>1</max_writes_per_connect>
  <task_name>oracle_subscriber_automated_test</task_name>
                <skip_queue/>
<handler>com.perspectium.replicator.sql.SQLSubscriber</handler>
                <skip_report/><decryption_key>some_decryption_key_here</decryption_key>
            <topic>topic_here</topic>
    <message_connection    user="USER" password="PASSWORD" queue="psp.out.replicator.dev1234">https://URL.perspectium.net</message_connection>
    <type>type_here</type>
            <key>key<use_here<cache/key>>
            <name/>
    <instance_connection        <database_type>sqlserver</database_type>
            <database_port>1234</database_port>
user="USER" password="PASSWORD">https://dev1234.service-now.com</instance_connection>
                <database_server>SERVER_URL<type>sqlserver</database_server>type>
                <database_user>USER<port>1234</database_user>port>
            <database_password>PASSWORD</database_password>
            <database_parms>lockTimeout=15000;queryTimeout=15</database_parms>
       <database_server>SERVER_URL</database_server>
     <database>DATABASE_NAME</database>

            <edge_encryption<database_user>USER</database_user>
                <database_password>PASSWORD</database_password>
    keystore="azure"
            <database_parms>lockTimeout=15000;queryTimeout=15</database_parms>
         vault_tenant="12345678-ab12-ab12-ab12-123456789ab"
       <database>DATABASE_NAME</database>
                vault_url="https://url.vault.azure.net/"
   <skip_columns_log_interval>200</skip_columns_log_interval>
				<plugins>
					<plugin keystore="local"
                 vault_principal="12345678-ab12-ab12-ab12-123456789ab		keystore_path="abcdefg"
                    principal_secret="3213156165-adasdasd_a1s5d6a5s1d6a			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>

↑ Go to top of page

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.

Content

Space Tools

Versions Compared

Old Version 11

New Version Current

Key

Prerequisites

Edge Encryption

Edge Decryption

Can't find what you're looking for?

See the FAQ or browse the Perspectium Community Forum.