Versions Compared

Key

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

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.


Prerequisites


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

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


The DataSync Agent provides a plugin to support decrypting data that is edge encrypted. In order to decrypt this, you will need the following:

  1. Edge Encryption enabled in your ServiceNow instance 
  2. Edge Encryption proxy server installed and configured
  3. 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
typenote

All attributes are required to access the keystore from the Azure Key Vault.  

For Azure Key Vault, add the following:

DirectiveParametersRequired?Example Value
<plugin>

Plugin that will decrypt Edge Encrypted replicated data.

ParameterDescription
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_passwordpassword 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"
                 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 a complete agent.xml configuration with the keystore in an Azure Key Vault

Code Block
languagexml
themeEclipse
<?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:

DirectiveDescriptionRequired?Example Value
<plugin>

Plugin that will decrypt Edge Encrypted replicated data.

ParameterDescription
keystore

Specifies where the keystore is located. Value: local

keystore_path

File path to the keystore^

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


YesSee example below.

Example of a complete agent.xml configuration with the keystore in a local filesystem the Agent has access to:

Code Block
languagexml
themeEclipse
HTML
<style>
.release-box {
	height: 30px; 
	width: 100px; 
	padding-top: 8px;
	text-align: center; 
	border-radius: 5px; 
	font-weight: bold; 
	background-color: #d4af37;  
	border-color: #FCE28A;
}

.release-box:hover {
  	cursor: hand;
    cursor: pointer;
    opacity: .9; 
}
</style>
<meta name="robots" content="noindex">

<div class="release-box">
<a href="https://docs.perspectium.com/display/gold" style="text-decoration: none; color: #FFFFFF; display: block;">
Gold
</a>
</div>

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.

Prerequisites

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

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

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
languagexml
<?xml version="1.0" encoding="ISO-8859-1" standalone="no"?>
<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_name>examplesubscriber_automated_subscribe<test</task_name>
                <handler>com.perspectium.replicator.sql.SQLSubscriber</handler>
       <keystore_password>KEYSTORE_PASSWORD_GOES_HERE</keystore_password>
             <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>
                <keystore_alias>KEYSTORE_ALIAS_GOES_HERE</keystore_alias>
<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>
      <alias_password>ALIAS_PASSWORD_GOES_HERE</alias_password>
          <database_server>SERVER_URL</database_server>
                <database_user>USER</database_user>
                <database_password>PASSWORD</database_password>
     <initialization_vector>INITIALIZATION_VECTOR_GOES_HERE</initialization_vector>           <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"
           .  
            </task>keystore_alias="128bitkey"
 						alias_password="abc123">com.perspectium.replicator.sql.plugin.SQLSubscriberDecryptColumnPlugin</plugin>
        </subscribe>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.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.



Contact Perspectium Support

Image RemovedUS: 1 888 620 8880

UK: 44 208 068 5953

support@perspectium.com  

Can't find what you're looking for?  

See the FAQ or browse the Perspectium Community Forum.

Similar topics

Content by Label
showLabelsfalse
max5
showSpacefalse
sortmodified
cqllabel = "troubleshooting-datasync-agent" and space = currentSpace()